福昕开发者文档中心

uiextensions_config.json 配置说明 ​

本文说明福昕 PDF SDK 鸿蒙版 UIExtensions 配置文件的配置项、默认值、可选值与含义。如何加载配置并做常见定制，见 使用配置文件自定义 UI。

对应样例文件（发版包）：

samples/complete_pdf_viewer/entry/src/main/resources/rawfile/uiextensions_config.json

  • 集成时可将该文件复制到自有工程 rawfile，再按本文修改所需项。
  • 发版包内亦可查阅同内容的 docs/uiextensions_config.md；更细的 API / 类型定义见包内 API Reference，以及 UIExtensions 源码 libs/uiextensions/.../config/UIExtensionsConfig.ets。

未在配置文件中写出的字段，使用 SDK 内置默认值。

使用注意 ​

  1. 颜色字符串支持 #RRGGBB 或 #AARRGGBB（含透明度）。

  2. 根级仅识别三个对象：modules、permissions、uiSettings。

  3. 建议在完整样例配置上修改取值。若自行删减 uiSettings.annotations、uiSettings.form、modules.annotations 等嵌套对象中的子项，被删掉的子项不会再回落到 SDK 默认值。例如仅写出：

    json
    "uiSettings": {
  "annotations": {
    "highlight": { "color": "#00ff00", "opacity": 1.0 }
  }
}

    则 annotations 会被整段替换为上述内容，结果只保留 highlight；continuouslyAdd、underline、note 等其它子项不会自动补回。

  4. 模块开关关闭后，对应工具栏 / 面板入口通常不可用；实际能力仍受文档权限与授权影响。

1. modules — 功能模块开关 ​

类型均为 boolean，可选值：true / false。

1.1 顶层模块 ​

配置项默认值说明
modules.readingbookmarktrue阅读书签
modules.outlinetrue文档大纲
modules.thumbnailtrue页面缩略图
modules.attachmenttrue附件面板 / 附件类注释相关能力
modules.signaturetrue数字签名
modules.fillSigntrue填写并签名（Fill & Sign）
modules.searchtrue搜索面板
modules.pagenavigationtrue页面导航
modules.formtrue表单填写
modules.selectiontrue选择工具（页面文本选择）
modules.encryptiontrue文件加密 / 保护相关入口
modules.multipleSelectiontrue注释多选

1.2 modules.annotations — 注释工具开关 ​

配置项默认值说明
highlighttrue高亮
underlinetrue下划线
squigglytrue波浪线
strikeouttrue删除线
inserttrue插入文本（Caret）
replacetrue替换文本（Caret）
linetrue直线
rectangletrue矩形
ovaltrue椭圆
arrowtrue箭头
penciltrue铅笔 / 墨迹
erasertrue橡皮擦
typewritertrue打字机
textboxtrue文本框
callouttrue注释框
notetrue便签
stamptrue图章
polygontrue多边形
cloudtrue云朵
polylinetrue折线
measuretrue测量
imagetrue图片
audiotrue音频
videotrue视频
redactiontrue密文（Redaction）

全部注释工具均为 false 时，注释相关模块不会加载。

2. permissions — 权限开关 ​

类型均为 boolean，可选值：true / false。
最终行为还受 PDF 文档自身权限约束。

配置项默认值说明
permissions.copyTexttrue是否允许复制页面文本
permissions.runJavaScripttrue是否启用 JavaScript
permissions.enableLinktrue是否启用链接跳转 / 链接操作
permissions.copyAnnotfalse是否允许复制注释

3. uiSettings — 界面与阅读设置 ​

3.1 页面布局与缩放 ​

配置项类型默认值可选值说明
uiSettings.pageModestring"Single"Single / Facing / Cover / Reflow页面布局：单页 / 双页 / 封面模式 / 重排。非法值将被忽略
uiSettings.continuousbooleanfalsetrue / false是否连续滚动
uiSettings.zoomModestring"FitWidth"FitWidth / FitHeight / FitPage初始缩放模式。非法值将被忽略

3.2 颜色与高亮 ​

配置项类型默认值可选值 / 约束说明
uiSettings.colorModestring"Normal"Normal / Night / MapPDF 页面颜色模式：白天 / 夜间 / 自定义映射（与系统 UI 深色主题不同）
uiSettings.mapForegroundColorstring"#FF5d5b71"#RRGGBB / #AARRGGBBcolorMode 为 Map 时的前景色
uiSettings.mapBackgroundColorstring"#FF00001b"同上colorMode 为 Map 时的背景色
uiSettings.reflowBackgroundColorstring"#FFFFFFFF"同上重排模式背景色
uiSettings.pdfViewBackgroundColorstring未设置颜色字符串，可省略PDF 视图背景色（可选）
uiSettings.highlightFormbooleantruetrue / false是否高亮表单域
uiSettings.highlightFormColorstring"#200066cc"颜色字符串表单域高亮色
uiSettings.highlightLinkbooleantruetrue / false是否高亮链接
uiSettings.highlightLinkColorstring"#16007fff"颜色字符串链接高亮色

3.3 工具栏与交互 ​

配置项类型默认值可选值说明
uiSettings.fullscreenbooleantruetrue / false是否启用全屏相关能力（与点击显隐工具栏等配合）
uiSettings.enableTapToToggleToolbarbooleantruetrue / false点击阅读页空白是否切换顶栏 / 底栏显隐
uiSettings.showPenOnlySwitchbooleantruetrue / false墨迹属性栏是否显示「仅触控笔」开关
uiSettings.enableFormNavigationBarbooleantruetrue / false是否显示表单域导航条
uiSettings.enablePageSliderbooleantruetrue / false是否显示页码滑动条
uiSettings.enableTopbarDraggablenumber20 / 1 / 2 / 3顶栏是否可拖动（见下表）

enableTopbarDraggable 取值 ​

值含义
0全部设备关闭
1仅手机开启
2仅平板开启（默认）
3手机与平板均开启

4. uiSettings.annotations — 注释默认属性 ​

4.1 通用字段约定 ​

字段类型推荐范围 / 可选值说明
color / textColor / fillColorstring#RRGGBB / #AARRGGBB；fillColor 可为 null描边色 / 文本色 / 填充色
opacitynumber0.0～1.0不透明度
thicknessnumber1～12（线条 / 形状类注释常用）线宽；铅笔等工具在界面中可能允许更大范围
textFacestringCourier / Helvetica / Times字体
textSizenumber注释工具：> 0；表单见第 5 节字号（pt）
stylusOnlybooleantrue / false铅笔是否默认仅触控笔输入
rotationnumber0 / 90 / 180 / 270图片注释旋转角度
scaleFromUnit / scaleToUnitstringpt / inch / ft / yd / p / mm / cm / m测量比例单位；无法识别时回退为 pt
scaleFromValue / scaleToValuenumber正数测量比例数值

4.2 连续添加 ​

配置项类型默认值说明
uiSettings.annotations.continuouslyAddbooleantrue创建注释后是否保持当前工具，便于连续添加

4.3 各注释类型默认值 ​

配置项主要字段与默认值
highlightcolor: "#ffff00"，opacity: 1.0
areaHighlightcolor: "#ffff00"，opacity: 1.0
underlinecolor: "#66cc33"，opacity: 1.0
squigglycolor: "#993399"，opacity: 1.0
strikeoutcolor: "#ff0000"，opacity: 1.0
insertcolor: "#993399"，opacity: 1.0
replacecolor: "#0000ff"，opacity: 1.0
linecolor: "#ff0000"，opacity: 1.0，thickness: 2
rectangle / oval / polygon / cloudcolor: "#ff0000"，opacity: 1.0，thickness: 2，fillColor: null
arrow / polylinecolor: "#ff0000"，opacity: 1.0，thickness: 2
pencilcolor: "#ff0000"，opacity: 1.0，thickness: 2，stylusOnly: false
typewritertextColor: "#0000ff"，opacity: 1.0，textFace: "Courier"，textSize: 18
textbox / calloutcolor: "#ff0000"，textColor: "#0000ff"，opacity: 1.0，textFace: "Courier"，textSize: 18
notecolor: "#ff0000"，opacity: 1.0，icon: "Comment"
attachmentcolor: "#ff0000"，opacity: 1.0，icon: "PushPin"
imagerotation: 0，opacity: 1.0
measurecolor: "#ff0000"，opacity: 1.0，thickness: 2，scaleFromUnit/scaleToUnit: "inch"，scaleFromValue/scaleToValue: 1.0
redactionfillColor: "#000000"，textColor: "#ff0000"，textFace: "Courier"，textSize: 12

4.4 便签图标 note.icon ​

可选值：

Check / Circle / Comment / Cross / Help / Insert / Key / NewParagraph / Note / Paragraph / RightArrow / RightPointer / Star / UpArrow / UpLeftArrow

默认：Comment

4.5 附件图标 attachment.icon ​

可选值：Graph / PushPin / Paperclip / Tag

默认：PushPin

5. uiSettings.form — 表单域默认属性 ​

配置项主要字段默认值说明
form.textFieldtextColor / textFace / textSize"#000000" / "Courier" / 0textSize 为 0 表示自动字号（>= 0）
form.checkBoxtextColor"#000000"复选框
form.radioButtontextColor"#000000"单选框
form.comboBoxtextColor / textFace / textSize / customText"#000000" / "Courier" / 0 / falsecustomText：是否允许自定义输入
form.listBoxtextColor / textFace / textSize / multipleSelection"#000000" / "Courier" / 0 / falsemultipleSelection：是否允许多选

textFace 可选值同注释：Courier / Helvetica / Times。

6. uiSettings.signature — 签名外观默认值 ​

配置项类型默认值约束说明
uiSettings.signature.colorstring"#000000"颜色字符串创建签名时的墨迹颜色
uiSettings.signature.thicknessnumber8使用时若 < 2 会按 2 处理笔画粗细

7. 枚举速查 ​

配置项可选值
pageModeSingle、Facing、Cover、Reflow
zoomModeFitWidth、FitHeight、FitPage
colorModeNormal、Night、Map
enableTopbarDraggable0、1、2、3
textFaceCourier、Helvetica、Times
测量单位（scaleFromUnit / scaleToUnit）pt、inch、ft、yd、p、mm、cm、m
note.iconCheck、Circle、Comment、Cross、Help、Insert、Key、NewParagraph、Note、Paragraph、RightArrow、RightPointer、Star、UpArrow、UpLeftArrow
attachment.iconGraph、PushPin、Paperclip、Tag
image.rotation0、90、180、270
opacity0.0～1.0
thickness（线条 / 形状类常见）1～12