福昕开发者文档中心

使用配置文件自定义 UI ​

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

  1. UI Extensions 组件源代码： 提供即用型 UI 模块，支持深度定制。
  2. 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
    },
    "attachment": 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,
        "addHistoricalPoints": true
      },
      "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
      }
    }
  }
}

NOTE

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

JSON 配置项描述 ​

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

功能模块配置项 ​

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

功能模块描述
readingbookmark用户定义书签
outlinePDF 文档书签
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)注释模块集合
attachmentPDF文档附件和附件注释
search文本搜索
pagenavigationPDF 页面导航
form表单填写和表单数据导入导出

权限管理配置项 ​

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

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

UI 配置项及其属性 ​

UI 配置子项描述/属性值类型可选值默认值备注
pageMode页面显示模式StringSingle/Facing/CoverLeft /CoverMiddle/CoverRight/ReflowSingle动态 XFA 文件不支持 Reflow 模式。
continuous是否连续的显示单页页面Booltrue/falsefalseTrue 表示连续显示，false 表示不连续显示。该配置项在 "Reflow" 模式下无效。
zoomMode页面缩放模式StringFitWidth/FitPageFitWidth
colorMode页面颜色显示模式StringNormal/Night/MapNormal"Night" 是一种特殊的 "Map" 模式。
mapForegroundColor页面显示的前景颜色RGB---#5d5b71只有在 "colorMode" 设置为 "Map" 时，该配置项才有效。
mapBackgroundColor页面显示的背景颜色RGB---#00001b只有在 "colorMode" 设置为 "Map" 时，该配置项才有效。
enableFormNavigationBar是否禁用表单的辅助导航栏Booltrue/falsetrue
highlightForm是否高亮表单域Booltrue/falsetrue
highlightFormColor表单高亮颜色ARGB#200066cc包括 alpha 通道，并且对动态 xfa 文件无效。
highlightLink是否高亮超链接Booltrue/falsetrue
highlightLinkColor超链接高亮颜色ARGB#16007fff包括 alpha 通道。
annotationscontinuouslyAddBooltrue/falsetrue是否连续添加某个注释
highlightcolorRGB#ffff00
opacitynumeric[0.0-1.0]1.0
areaHighlightcolorRGB#ffff00
opacitynumeric[0.0-1.0]1.0如果区域超出页面，则使用默认的配置。
underlinecolorRGB#66cc33
opacitynumeric[0.0-1.0]1.0
squigglycolorRGB#993399
opacitynumeric[0.0-1.0]1.0
strikeoutcolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
insertcolorRGB#993399
opacitynumeric[0.0-1.0]1.0
replacecolorRGB#0000ff
opacitynumeric[0.0-1.0]1.0
linecolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
rectanglecolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
fillColorRGBnull
ovalcolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
fillColorRGBnull
arrowcolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
pencilcolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
addHistoricalPointsBooltrue/falsetrue是否添加当前帧的历史坐标点
polygoncolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
fillColorRGBnull
cloudcolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
fillColorRGBnull
polylinecolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
typewritertextColorRGB#0000ff
opacitynumeric[0.0-1.0]1.0
textFaceStringCourier/Helvetica/TimesCourier文本字体名称。如果设置为非法值，则使用默认字体。
textSizeInteger>=118
textboxcolorRGB#ff0000
textColorRGB#0000ff
opacitynumeric[0.0-1.0]1.0
textFaceStringCourier/Helvetica/TimesCourier文本字体名称。如果设置为非法值，则使用默认字体。
textSizeInteger>=118
calloutcolorRGB#ff0000
textColorRGB#0000ff
opacitynumeric[0.0-1.0]1.0
textFaceStringCourier/Helvetica/TimesCourier文本字体名称。如果设置为非法值，则使用默认字体。
textSizeInteger>=118
notecolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
iconStringComment/Key/Note/Help/ NewParagraph/Paragraph/InsertComment如果设置为非法值，则使用默认值。
attachmentcolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
iconStringGraph/PushPin/Paperclip/TagPushPin如果设置为非法值，则使用默认值。
imagerotationnumeric0/90/180/2700
opacitynumeric[0.0-1.0]1.0
textSizeInteger>=112
measurecolorRGB#ff0000
opacitynumeric[0.0-1.0]1.0
thicknessnumeric[1-12]2
scaleFromUnitStringpt/m/cm/mm/inch/p/ft/ydinch缩放的基准单位。
scaleToUnitStringpt/m/cm/mm/inch/p/ft/ydinch缩放的目标单位。
scaleFromValuenumeric1.0缩放的基准数值。
scaleToValuenumeric1.0缩放的目标数值。

通过配置文件实例化 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 文件中，添加以下代码：
ts
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 示例步骤：

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

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

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

json
"search": false,
"pagenavigation": false

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

sample_1.pngsample_2.png

示例2: 禁止执行 JavaScript ​

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

js
"permissions"
:
{
    "runJavaScript"
:
    false,
}
,

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

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

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

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

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