使用配置文件自定义 UI

福昕 PDF SDK 鸿蒙版提供简洁友好的内置 UI，开发者无需耗费过多时间进行界面设计，即可快速构建功能完善的 PDF 应用。此外，SDK 还支持两种灵活的 UI 自定义方式，满足开发者个性化需求：

UI Extensions 组件源代码： 提供即用型 UI 模块，支持深度定制。
JSON 配置文件 (uiextensions_config.json)： 高效灵活地修改内置 UI 元素。

以下将介绍如何通过配置文件自定义功能模块、权限管理和 UI 元素。配置文件允许开发者轻松选择功能模块，设置权限和修改 UI 元素属性，无需编写额外代码或重新设计界面。

JSON 配置文件详解

配置文件支持 JSON 文件格式或直接在代码中编写。推荐使用 JSON 文件，其结构清晰，易于查看和配置。

您可以参考福昕 PDF SDK 鸿蒙版包中 samples/complete_pdf_viewer/entry/src/main/resources/rawfile 目录下的 JSON 配置文件，了解其结构和配置选项。其内容如下所示：

[config.json]

json

{
  "modules": {
    "readingbookmark": true,
    "outline": true,
    "annotations": {
      "highlight": true,
      "underline": true,
      "squiggly": true,
      "strikeout": true,
      "insert": true,
      "replace": true,
      "line": true,
      "rectangle": true,
      "oval": true,
      "arrow": true,
      "pencil": true,
      "eraser": true,
      "typewriter": true,
      "textbox": true,
      "callout": true,
      "note": true,
      "stamp": true,
      "polygon": true,
      "cloud": true,
      "polyline": true,
      "measure": true,
      "image": true,
      "audio": true,
      "video": true
    },
    "thumbnail": true,
    "attachment": true,
    "signature": true,
    "search": true,
    "pagenavigation": true,
    "form": true
  },
  "permissions": {
    "runJavaScript": true,
    "enableLink": true
  },
  "uiSettings": {
    "pageMode": "Single",
    "continuous": false,
    "zoomMode": "FitWidth",
    "colorMode": "Normal",
    "mapForegroundColor": "#5d5b71",
    "mapBackgroundColor": "#00001b",
    "enableFormNavigationBar": true,
    "highlightForm": true,
    "highlightFormColor": "#200066cc",
    "highlightLink": true,
    "highlightLinkColor": "#16007fff",
    "annotations": {
      "continuouslyAdd": true,
      "highlight": {
        "color": "#ffff00",
        "opacity": 1.0
      },
      "areaHighlight": {
        "color": "#ffff00",
        "opacity": 1.0
      },
      "underline": {
        "color": "#66cc33",
        "opacity": 1.0
      },
      "squiggly": {
        "color": "#993399",
        "opacity": 1.0
      },
      "strikeout": {
        "color": "#ff0000",
        "opacity": 1.0
      },
      "insert": {
        "color": "#993399",
        "opacity": 1.0
      },
      "replace": {
        "color": "#0000ff",
        "opacity": 1.0
      },
      "line": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2
      },
      "rectangle": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2,
        "fillColor": null
      },
      "oval": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2,
        "fillColor": null
      },
      "arrow": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2
      },
      "pencil": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2,
        "stylusOnly": false
      },
      "polygon": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2,
        "fillColor": null
      },
      "cloud": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2,
        "fillColor": null
      },
      "polyline": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2
      },
      "typewriter": {
        "textColor": "#0000ff",
        "opacity": 1.0,
        "textFace": "Courier",
        "textSize": 18
      },
      "textbox": {
        "color": "#ff0000",
        "textColor": "#0000ff",
        "opacity": 1.0,
        "textFace": "Courier",
        "textSize": 18
      },
      "callout": {
        "color": "#ff0000",
        "textColor": "#0000ff",
        "opacity": 1.0,
        "textFace": "Courier",
        "textSize": 18
      },
      "note": {
        "color": "#ff0000",
        "opacity": 1.0,
        "icon": "Comment"
      },
      "attachment": {
        "color": "#ff0000",
        "opacity": 1.0,
        "icon": "PushPin"
      },
      "image": {
        "rotation": 0,
        "opacity": 1.0
      },
      "measure": {
        "color": "#ff0000",
        "opacity": 1.0,
        "thickness": 2,
        "scaleFromUnit": "inch",
        "scaleToUnit": "inch",
        "scaleFromValue": 1.0,
        "scaleToValue": 1.0
      }
    },
    "form": {
      "textField": {
        "textColor": "#000000",
        "textFace": "Courier",
        "textSize": 0
      },
      "checkBox": {
        "textColor": "#000000"
      },
      "radioButton": {
        "textColor": "#000000"
      },
      "comboBox": {
        "textColor": "#000000",
        "textFace": "Courier",
        "textSize": 0,
        "customText": false
      },
      "listBox": {
        "textColor": "#000000",
        "textFace": "Courier",
        "textSize": 0,
        "multipleSelection": false
      }
    },
    "signature": {
      "color": "#000000",
      "thickness": 8
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203

**提示:**

上述 JSON 文件中的值是配置项的默认值。如果某些配置项不在 JSON 文件中，则将使用其默认值。例如，如果您注释掉 "highlight": true,, 但高亮功能仍然是可用的。

JSON 配置项描述

JSON 配置文件包括三个部分：功能模块，权限管理和 UI 设置 (例如，UI元素属性) 。本节将详细介绍这些配置项。

功能模块配置项

功能模块配置项的值类型是 bool，其中 true 表示启用该功能模块，false 表示将禁用该功能模块。默认值为 true。

功能模块	描述
readingbookmark	用户定义书签
outline	PDF 文档书签
annotations (highlight, underline, squiggly, strikeout, insert, replace, line, rectangle, oval, arrow, pencil, eraser, typewriter, textbox, callout, note, stamp, polygon, cloud, polyline, measure, image, audio, video)	注释模块集合
thumbnail	PDF页面缩略图显示和页面管理
attachment	PDF文档附件和附件注释
Signature	电子签名和手写签名
search	文本搜索
pagenavigation	PDF 页面导航
form	表单填写和表单数据导入导出

权限管理配置项

权限管理配置项的值类型为 bool，其中 true 表示将启用该权限，false 表示将禁用该权限。runJavaScript 和 enableLink 的默认值为 true。

权限管理	描述
runJavaScript	是否允许执行 JavaScript
enableLink	是否启用超链接

基础 UI 配置

参数	类型	说明
页面显示设置
`pageMode`	`String`	页面显示模式可选值：`Single` / `Facing` / `CoverLeft` / `CoverMiddle` / `CoverRight` / `Reflow` 默认值：`Single` 备注：动态 XFA 文件不支持 `Reflow` 模式
`continuous`	`Bool`	是否连续显示单页可选值：`true` / `false` 默认值：`false` 备注：在 `Reflow` 模式下无效
`zoomMode`	`String`	页面缩放模式可选值：`FitWidth` / `FitPage` 默认值：`FitWidth`
颜色与显示模式
`colorMode`	`String`	页面颜色显示模式可选值：`Normal` / `Night` / `Map` 默认值：`Normal` 备注：`Night` 是特殊的 `Map` 模式
`mapForegroundColor`	`RGB`	页面前景色（仅 `Map` 模式生效）默认值：`#5d5b71`
`mapBackgroundColor`	`RGB`	页面背景色（仅 `Map` 模式生效）默认值：`#00001b`
表单与链接设置
`enableFormNavigationBar`	`Bool`	是否启用表单导航栏可选值：`true` / `false` 默认值：`true`
`highlightForm`	`Bool`	是否高亮表单域可选值：`true` / `false` 默认值：`true`
`highlightFormColor`	`ARGB`	表单高亮颜色默认值：`#200066cc` 备注：包含 alpha 通道，对动态 XFA 文件无效
`highlightLink`	`Bool`	是否高亮超链接可选值：`true` / `false` 默认值：`true`
`highlightLinkColor`	`ARGB`	超链接高亮颜色默认值：`#16007fff` 备注：包含 alpha 通道

注释配置（annotations）

参数	类型	说明
通用配置
`continuouslyAdd`	`Bool`	是否连续添加某个注释可选值：`true` / `false` 默认值：`true`
文本高亮类注释
`highlight.color`	`RGB`	高亮颜色默认值：`#ffff00`
`highlight.opacity`	`numeric`	高亮透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`areaHighlight.color`	`RGB`	区域高亮颜色默认值：`#ffff00`
`areaHighlight.opacity`	`numeric`	区域高亮透明度可选值：`[0.0-1.0]` 默认值：`1.0` 备注：区域超出页面时使用默认配置
`underline.color`	`RGB`	下划线颜色默认值：`#66cc33`
`underline.opacity`	`numeric`	下划线透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`squiggly.color`	`RGB`	波浪线颜色默认值：`#993399`
`squiggly.opacity`	`numeric`	波浪线透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`strikeout.color`	`RGB`	删除线颜色默认值：`#ff0000`
`strikeout.opacity`	`numeric`	删除线透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`insert.color`	`RGB`	插入标记颜色默认值：`#993399`
`insert.opacity`	`numeric`	插入标记透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`replace.color`	`RGB`	替换标记颜色默认值：`#0000ff`
`replace.opacity`	`numeric`	替换标记透明度可选值：`[0.0-1.0]` 默认值：`1.0`
图形类注释
`line.color`	`RGB`	直线颜色默认值：`#ff0000`
`line.opacity`	`numeric`	直线透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`line.thickness`	`numeric`	直线宽度可选值：`[1-12]` 默认值：`2`
`rectangle.color`	`RGB`	矩形边框颜色默认值：`#ff0000`
`rectangle.opacity`	`numeric`	矩形透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`rectangle.thickness`	`numeric`	矩形边框宽度可选值：`[1-12]` 默认值：`2`
`rectangle.fillColor`	`RGB`	矩形填充色默认值：`null`
`oval.color`	`RGB`	椭圆形边框颜色默认值：`#ff0000`
`oval.opacity`	`numeric`	椭圆形透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`oval.thickness`	`numeric`	椭圆形边框宽度可选值：`[1-12]` 默认值：`2`
`oval.fillColor`	`RGB`	椭圆形填充色默认值：`null`
`arrow.color`	`RGB`	箭头颜色默认值：`#ff0000`
`arrow.opacity`	`numeric`	箭头透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`arrow.thickness`	`numeric`	箭头线宽可选值：`[1-12]` 默认值：`2`
`pencil.color`	`RGB`	画笔颜色默认值：`#ff0000`
`pencil.opacity`	`numeric`	画笔透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`pencil.thickness`	`numeric`	画笔粗细可选值：`[1-12]` 默认值：`2`
`pencil.addHistoricalPoints`	`Bool`	是否添加当前帧的历史坐标点可选值：`true` / `false` 默认值：`true`
`polygon.color`	`RGB`	多边形边框颜色默认值：`#ff0000`
`polygon.opacity`	`numeric`	多边形透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`polygon.thickness`	`numeric`	多边形边框宽度可选值：`[1-12]` 默认值：`2`
`polygon.fillColor`	`RGB`	多边形填充色默认值：`null`
`cloud.color`	`RGB`	云形边框颜色默认值：`#ff0000`
`cloud.opacity`	`numeric`	云形透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`cloud.thickness`	`numeric`	云形边框宽度可选值：`[1-12]` 默认值：`2`
`cloud.fillColor`	`RGB`	云形填充色默认值：`null`
`polyline.color`	`RGB`	折线颜色默认值：`#ff0000`
`polyline.opacity`	`numeric`	折线透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`polyline.thickness`	`numeric`	折线宽度可选值：`[1-12]` 默认值：`2`
文本类注释
`typewriter.textColor`	`RGB`	打字机文本颜色默认值：`#0000ff`
`typewriter.opacity`	`numeric`	打字机透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`typewriter.textFace`	`String`	打字机字体可选值：`Courier` / `Helvetica` / `Times` 默认值：`Courier` 备注：非法值时使用默认字体
`typewriter.textSize`	`Integer`	打字机字号可选值：`>=1` 默认值：`18`
`textbox.color`	`RGB`	文本框边框颜色默认值：`#ff0000`
`textbox.textColor`	`RGB`	文本框文本颜色默认值：`#0000ff`
`textbox.opacity`	`numeric`	文本框透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`textbox.textFace`	`String`	文本框字体可选值：`Courier` / `Helvetica` / `Times` 默认值：`Courier` 备注：非法值时使用默认字体
`textbox.textSize`	`Integer`	文本框字号可选值：`>=1` 默认值：`18`
`callout.color`	`RGB`	标注边框颜色默认值：`#ff0000`
`callout.textColor`	`RGB`	标注文本颜色默认值：`#0000ff`
`callout.opacity`	`numeric`	标注透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`callout.textFace`	`String`	标注字体可选值：`Courier` / `Helvetica` / `Times` 默认值：`Courier` 备注：非法值时使用默认字体
`callout.textSize`	`Integer`	标注字号可选值：`>=1` 默认值：`18`
其他注释
`note.color`	`RGB`	批注颜色默认值：`#ff0000`
`note.opacity`	`numeric`	批注透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`note.icon`	`String`	批注图标类型可选值：`Comment` / `Key` / `Note` / `Help` / `NewParagraph` / `Paragraph` / `Insert` 默认值：`Comment` 备注：非法值时使用默认图标
`attachment.color`	`RGB`	附件颜色默认值：`#ff0000`
`attachment.opacity`	`numeric`	附件透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`attachment.icon`	`String`	附件图标类型可选值：`Graph` / `PushPin` / `Paperclip` / `Tag` 默认值：`PushPin` 备注：非法值时使用默认图标
`image.rotation`	`numeric`	图片旋转角度可选值：`0` / `90` / `180` / `270` 默认值：`0`
`image.opacity`	`numeric`	图片透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`image.textSize`	`Integer`	图片文本标注字号可选值：`>=1` 默认值：`12`
`measure.color`	`RGB`	测量线颜色默认值：`#ff0000`
`measure.opacity`	`numeric`	测量线透明度可选值：`[0.0-1.0]` 默认值：`1.0`
`measure.thickness`	`numeric`	测量线宽度可选值：`[1-12]` 默认值：`2`
`measure.scaleFromUnit`	`String`	缩放基准单位可选值：`pt` / `m` / `cm` / `mm` / `inch` / `p` / `ft` / `yd` 默认值：`inch` 备注：缩放计算的基准单位
`measure.scaleToUnit`	`String`	缩放目标单位可选值：`pt` / `m` / `cm` / `mm` / `inch` / `p` / `ft` / `yd` 默认值：`inch` 备注：缩放计算的目标单位
`measure.scaleFromValue`	`numeric`	缩放基准数值默认值：`1.0` 备注：缩放计算的基准数值
`measure.scaleToValue`	`numeric`	缩放目标数值默认值：`1.0` 备注：缩放计算的目标数值

表单控件配置（form）

参数	类型	说明
form.textField 配置
`form.textField.textColor`	`RGB`	文本颜色默认值：`#000000`
`form.textField.textFace`	`String`	文本字体名称可选值：`Courier` / `Helvetica` / `Times` 默认值：`Courier` 说明：若设置为非法值，则使用默认字体
`form.textField.textSize`	`Integer`	文本字号可选值：`>=0` 默认值：`0` 说明：0 表示自动调整字体大小
form.checkBox 配置
`form.checkBox.textColor`	`RGB`	复选框文本颜色默认值：`#000000`
form.radioButton 配置
`form.radioButton.textColor`	`RGB`	单选按钮文本颜色默认值：`#000000`
form.comboBox 配置
`form.comboBox.textColor`	`RGB`	下拉框文本颜色默认值：`#000000`
`form.comboBox.textFace`	`String`	下拉框文本字体名称可选值：`Courier` / `Helvetica` / `Times` 默认值：`Courier` 说明：若设置为非法值，则使用默认字体
`form.comboBox.textSize`	`Integer`	下拉框文本字号可选值：`>=0` 默认值：`0` 说明：0 表示自动调整字体大小
`form.comboBox.customText`	`Bool`	下拉框是否允许自定义文本可选值：`true` / `false` 默认值：`false` 说明：True 表示允许自定义文本，False 表示不允许自定义文本
form.listBox 配置
`form.listBox.textColor`	`RGB`	列表框文本颜色默认值：`#000000`
`form.listBox.textFace`	`String`	列表框文本字体名称可选值：`Courier` / `Helvetica` / `Times` 默认值：`Courier` 说明：若设置为非法值，则使用默认字体
`form.listBox.textSize`	`Integer`	列表框文本字号可选值：`>=0` 默认值：`0` 说明：0 表示自动调整字体大小
`form.listBox.multipleSelection`	`Bool`	列表框是否支持多选可选值：`true` / `false` 默认值：`false` 说明：True 表示支持多选，False 表示不支持多选
signature（签名）配置
`signature.color`	`RGB`	签名颜色默认值：`#000000`
`signature.thickness`	`numeric`	签名线条粗细可选值：`[1-12]` 默认值：`8`

通过配置文件实例化 UIExtensionsManager 对象

在快速构建中，我们介绍了如何使用 UI Extensions 组件实例化 UIExtensionsManager 对象，并默认加载所有内置 UI 框架。本节将介绍如何使用配置文件实例化 UIExtensionsManager ，以便开发者根据需求轻松自定义 UI。

前提条件：

您已将名为 uiextensions_config.json 的 JSON 配置文件放置于 PDFReader/entry/src/main/resources/rawfile 目录下。

操作步骤：

在 PDFReader/entry/src/main/ets/pages/Index.ets 文件中，添加以下代码：

import { UIExtensionsManager, UIExtensionsComponent, ConfigModel } from 'uiextensions';

// ...

// @State uiextensionsManager: UIExtensionsManager = new UIExtensionsManager(getContext(this));
@State
uiextensionsManager: UIExtensionsManager = new UIExtensionsManager(
    getContext(this),
    new ConfigModel(getContext(this), 'uiextensions_config.json')
);

通过配置文件自定义 UI 示例

以下将演示如何通过修改配置文件，在项目中自定义功能模块、权限管理和 UI 设置（例如，UI 元素属性）。

为便于理解，我们将以 samples 文件夹下的 complete_pdf_viewer 示例为例进行演示。

打开 complete_pdf_viewer 示例步骤：

在 DevEco Studio 中打开 complete_pdf_viewer 示例工程。
在 samples/complete_pdf_viewer/entry/src/main/resources/rawfile 目录下找到配置文件 uiextensions_config.json。

示例 1：禁用 `search` 和 `pagenavigation` 功能模块

在 JSON 配置文件中，将 search 和 pagenavigation 的值设置为 false，如下所示：

json

"search": false,
"pagenavigation": false

重新编译并运行示例，对比效果如下：

示例2: 禁止执行 JavaScript

在 JSON 配置文件中，将 permissions 对象的 runJavaScript 属性设置为 false，如下所示：

json

{
  "permissions": {
    "runJavaScript": false
  }
}

重新编译并运行示例，此时点击包含 JavaScript 脚本的按钮将无任何响应。

示例3: 将高亮颜色从黄色设置为红色。

在 JSON 配置文件中，将 highlight 对象的 color 属性设置为 #ff0000（红色），如下所示：

json

{
  "highlight": {
    "color": "#ff0000",
    "opacity": 1.0
  }
}

重新编译并运行示例，对比效果如下：

使用配置文件自定义 UI ​

JSON 配置文件详解 ​

JSON 配置项描述 ​

功能模块配置项 ​

权限管理配置项 ​

基础 UI 配置 ​

注释配置（annotations） ​

表单控件配置（form） ​

通过配置文件实例化 UIExtensionsManager 对象 ​

通过配置文件自定义 UI 示例 ​

示例 1：禁用 search 和 pagenavigation 功能模块 ​

示例2: 禁止执行 JavaScript ​

示例3: 将高亮颜色从黄色设置为红色。 ​

使用配置文件自定义 UI

JSON 配置文件详解

JSON 配置项描述

功能模块配置项

权限管理配置项

基础 UI 配置

注释配置（annotations）

表单控件配置（form）

通过配置文件实例化 UIExtensionsManager 对象

通过配置文件自定义 UI 示例

示例 1：禁用 `search` 和 `pagenavigation` 功能模块

示例2: 禁止执行 JavaScript

示例3: 将高亮颜色从黄色设置为红色。