通过配置文件自定义 UI

本节介绍如何在 Android 平台基于 UI Extensions，通过配置文件 uiextensions_config.json 定制内置 UI。您可以在不修改业务代码的情况下，按需控制 UI 的启用范围与行为，例如：

启用/禁用功能模块（modules）
权限/能力开关（permissions）
UI 行为与样式（uiSettings，例如页面模式、链接高亮、注释默认属性等）

修改配置后，重新编译运行应用即可生效。

配置文件位置

在 SDK 示例工程中，配置文件位于：

samples/complete_pdf_viewer/app/src/main/res/raw/uiextensions_config.json

您也可以在自己的工程中按同样方式放置并使用该配置文件。

JSON 文件说明

UI Extensions 的配置既可以通过 JSON 文件提供，也可以在代码中直接构造配置对象。为便于阅读与维护，推荐优先使用 JSON 格式（更直观、更易于审阅配置差异）。

配置文件示例（`uiextensions_config.json`）

下面给出示例工程中的 完整配置文件。建议您先以该文件为模板，按需调整少量配置项，以快速验证定制效果。

[uiextensions_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
    }
  }
}

注意

关于默认值：配置文件中未显式声明的配置项，会按 SDK 的默认值处理。比如，即使您未在配置文件中写入或将 "highlight": true 注释掉，高亮功能也可能仍保持可用（因为默认值为启用）。
关于附件（attachment）与注释（annotations）的边界：
- modules.annotations 下的子项（如 highlight / underline 等）用于控制"注释工具"中的对应功能开关。
- 附件相关能力（包含"附件面板"与"附件注释"入口）由顶层模块 modules.attachment 统一控制，不受 modules.annotations 子项开关影响。
- 如果您的目标是隐藏/禁用 Comment 中所有注释相关入口，通常需要同时关闭 modules.annotations 与 modules.attachment。
例如（仅示意配置关系）：
json
```
{
  "modules": {
    "annotations": false,
    "attachment": false
  }
}
```
1

JSON 配置项说明

JSON 配置文件通常包括三个部分：功能模块（modules）、权限管理（permissions）、以及 UI 设置（uiSettings，例如 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	电子签名和手写签名
fillSign	为“平面表单（非交互表单）”填充文本与符号
search	文本搜索
navigation	PDF 页面导航
form	表单填写和表单数据导入导出
selection	文本选择
encryption	PDF 加密
multipleSelection	多选注释

权限管理配置项

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

权限管理	描述
runJavaScript	是否允许执行 JavaScript
copyText	是否允许复制文本
disableLink	是否禁用超链接

基础 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`
表单与链接设置
`disableFormNavigationBar`	`Bool`	是否禁用表单导航栏可选值：`true` / `false` 默认值：`false`
`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`

在 full-viewer 等示例中，直接实例化 UIExtensionsManager 会默认加载所有内置 UI。若您希望在初始化阶段就按 JSON 配置启用/禁用模块或调整 UI 行为，可按以下方式加载配置文件并实例化 UIExtensionsManager。

前提条件

您已将 uiextensions_config.json 放置于 app/src/main/res/raw/ 目录下（若工程中没有 raw 目录，请自行创建）。

在 MainActivity.java 中（示例代码按原文逻辑整理为可直接复制的形式）：

java

import com.foxit.uiextensions.UIExtensionsManager;
import com.foxit.uiextensions.config.Config;

import java.io.InputStream;

// ...

private PDFViewCtrl pdfViewCtrl = null;
private UIExtensionsManager uiExtensionsManager = null;

// 初始化 PDFViewCtrl 对象
pdfViewCtrl = new PDFViewCtrl(this);

// 加载配置文件
InputStream stream = this.getApplicationContext()
        .getResources()
        .openRawResource(R.raw.uiextensions_config);
Config config = new Config(stream);

// 使用配置文件初始化 UIExtensionsManager，并关联到 PDFViewCtrl
uiExtensionsManager = new UIExtensionsManager(this.getApplicationContext(), pdfViewCtrl, config);
pdfViewCtrl.setUIExtensionsManager(uiExtensionsManager);
uiExtensionsManager.setAttachedActivity(this);
uiExtensionsManager.onCreate(this, pdfViewCtrl, savedInstanceState);

示例：修改配置项实现 UI 定制

以下示例来自 SDK 示例工程（complete_pdf_viewer），展示如何通过修改 uiextensions_config.json 实现不同的 UI 行为变化。

示例 1：禁用某些功能模块

将 readingbookmark 与 navigation 置为 false：

json

{
  "modules": {
    "readingbookmark": false,
    "navigation": false
  }
}

示例 2：禁用超链接

将 disableLink 置为 true：

json

{
  "permissions": {
    "runJavaScript": true,
    "copyText": true,
    "disableLink": true
  }
}

示例 3：将高亮注释颜色从黄色改为红色

设置 highlight.color 为 #ff0000：

json

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

文档基础

内容处理

文本搜索

书签

注释

通过配置文件自定义 UI

配置文件位置

JSON 文件说明

配置文件示例（`uiextensions_config.json`）

JSON 配置项说明

功能模块配置项

权限管理配置项

基础 UI 配置

注释配置（annotations）

表单控件配置（form）

使用配置文件实例化 `UIExtensionsManager`

示例：修改配置项实现 UI 定制

示例 1：禁用某些功能模块

示例 2：禁用超链接

示例 3：将高亮注释颜色从黄色改为红色

通过配置文件自定义 UI ​

配置文件位置 ​

JSON 文件说明 ​

配置文件示例（uiextensions_config.json） ​

JSON 配置项说明 ​

功能模块配置项 ​

权限管理配置项 ​

基础 UI 配置 ​

注释配置（annotations） ​

表单控件配置（form） ​

使用配置文件实例化 UIExtensionsManager ​

示例：修改配置项实现 UI 定制 ​

示例 1：禁用某些功能模块 ​

示例 2：禁用超链接 ​

示例 3：将高亮注释颜色从黄色改为红色 ​

通过配置文件自定义 UI

配置文件位置

JSON 文件说明

配置文件示例（`uiextensions_config.json`）

JSON 配置项说明

功能模块配置项

权限管理配置项

基础 UI 配置

注释配置（annotations）

表单控件配置（form）

使用配置文件实例化 `UIExtensionsManager`

示例：修改配置项实现 UI 定制

示例 1：禁用某些功能模块

示例 2：禁用超链接

示例 3：将高亮注释颜色从黄色改为红色