Guides

主工具栏

ComPDF 的主工具栏设计灵活且高度可配置。本指南将展示如何定义主工具栏选项以及添加完全自定义的菜单选项。

本章节涵盖以下内容：

• 配置已有的工具栏按钮项
• 添加更多菜单选项
• 自定义菜单选项

默认工具栏

默认工具栏包含以下工具。

Android	iOS

自定义工具栏按钮

您可以在显示 PDF 时使用 toolbarLeftItems、toolbarRightItems 属性自定义主工具栏按钮。由于 Android 与 iOS 的默认工具栏位置和交互不同，建议分别配置：

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  onIOSClickBackPressed={handleBack}
  configuration={ComPDFKit.getDefaultConfig({
    toolbarConfig: {
      toolbarLeftItems: Platform.OS === "android"
        ? ['back', 'thumbnail']
        : ['back'],
      toolbarRightItems: Platform.OS === "android"
        ? ['search', 'bota']
        : ['search', 'thumbnail', 'bota', 'menu']
    }
  })}
  />

说明: 不同平台的工具栏默认交互存在差异，示例中根据平台分别配置左右工具栏按钮。

自定义工具栏将如下所示。

Android	iOS

可用的工具栏选项类型

工具栏按钮项	描述
back	显示关闭按钮项。
thumbnail	显示缩略图按钮项。
search	显示搜索按钮项。
bota	显示大纲、书签、注释列表按钮项。
menu	显示菜单按钮项。
viewSettings	打开设置视图并设置滚动方向、显示模式、主题颜色等相关设置。
documentEditor	打开文档缩略图列表，可以在视图中删除、旋转和添加文档页面。
documentInfo	打开文档信息视图以显示基本文档信息和权限信息。
watermark	打开水印编辑视图以添加文本和图像水印，并将其保存为新文档。
security	打开安全设置视图，设置文档打开密码和权限密码。
flattened	将文档中的注释扁平化，注释将不可编辑。
save	保存 PDF 文档。
share	打开系统共享功能。
openDocument	打开系统文件选择器并打开新 PDF 文档。
snip	启动截图选区工具。
custom	自定义菜单选项

注意：请参考 CPDFToolbarAction 获取相关选项。

更多菜单

通过在主工具栏中配置 CPDFToolbarAction.menu，可以展示更多菜单选项。点击后将弹出菜单，供用户选择更多功能。更多菜单使用 availableMenus 进行配置，配置方式与上述工具栏按钮相同。

以下是配置示例：

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  onIOSClickBackPressed={handleBack}
  configuration={ComPDFKit.getDefaultConfig({
    toolbarConfig: {
      availableMenus: [
        CPDFToolbarAction.VIEW_SETTINGS,
        CPDFToolbarAction.DOCUMENT_EDITOR,
        CPDFToolbarAction.DOCUMENT_INFO,
        CPDFToolbarAction.WATERMARK,
        CPDFToolbarAction.SECURITY,
        CPDFToolbarAction.FLATTENED,
        CPDFToolbarAction.SAVE,
        CPDFToolbarAction.SHARE,
        CPDFToolbarAction.OPEN_DOCUMENT,
        CPDFToolbarAction.SNIP,
      ]
    }
  })}
  />

自定义菜单

在 2.6.0 及更高版本中，您可以通过 customToolbarLeftItems、customToolbarRightItems、customMoreMenuItems 属性添加自定义菜单选项。

SDK 提供两种自定义方式：

• 修改已有菜单选项的图标和标题
• 添加完全自定义的菜单选项

以下是配置示例：

const customToolbarConfig: CPDFToolbarConfig = {
  mainToolbarTitleVisible: false,
  customToolbarLeftItems: [
    {
      action: "back",
      icon: "ic_test_back",
    },
    {
      action: "custom",                          // 自定义按钮，必须为 custom
      identifier: "custom_editor",               // 自定义标识符，必须配置
      icon: "ic_test_edit",                      // 自定义图标
    },
  ],
  customToolbarRightItems: [
    {
      action: "bota",
      icon: "ic_test_book",
    },
    {
      action: "custom",
      identifier: "custom_text_search",
      icon: "ic_test_search",
    },
    {
      action: "menu",
      icon: "ic_test_more",
    },
  ],
  customMoreMenuItems: [
    {
      action: "viewSettings",
      title: "Custom View Settings",
      icon: "ic_test_setting",
    },
    {
      action: "custom",                          // 自定义按钮，必须为 custom
      title: "Custom Share",                     // 更多菜单中选项名称
      icon: "ic_test_share",                     // 更多菜单中的图标
      identifier: "custom_share",                // 自定义菜单的标识符，必须配置
    }
  ],
};

参数说明

参数	说明
action	必选参数，指定要自定义的菜单选项，参考 CPDFToolbarAction。
identifier	必选参数（仅自定义菜单），自定义菜单选项的唯一标识符。
icon	可选参数，指定菜单选项的图标。支持本地资源图片名称或文件路径。
title	可选参数，指定菜单选项的标题文本。仅在更多菜单中生效。

工具栏配置字段

字段	说明
toolbarLeftItems	主工具栏左侧显示的内置操作。
toolbarRightItems	主工具栏右侧显示的内置操作。
availableMenus	点击 menu 后在更多菜单中显示的内置操作。
customToolbarLeftItems	主工具栏左侧显示的自定义或覆盖后的按钮。
customToolbarRightItems	主工具栏右侧显示的自定义或覆盖后的按钮。
customMoreMenuItems	更多菜单中显示的自定义或覆盖后的菜单项。
mainToolbarVisible	显示或隐藏整个主工具栏。
mainToolbarTitleVisible	显示或隐藏主工具栏中的模式切换标题和入口。
annotationToolbarVisible	显示或隐藏注释模式工具栏。
contentEditorToolbarVisible	显示或隐藏内容编辑模式工具栏。
formToolbarVisible	显示或隐藏表单模式工具栏。
signatureToolbarVisible	显示或隐藏签名模式工具栏。
showInkToggleButton	显示或隐藏注释工具栏中的墨迹切换按钮。

自定义菜单点击事件

仅当使用 action = custom 自定义菜单选项时，您需要通过 onCustomToolbarItemTapped 回调处理点击事件：

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={ComPDFKit.getDefaultConfig({
    toolbarConfig: customToolbarConfig,
  })}
  onIOSClickBackPressed={handleBack}
  onCustomToolbarItemTapped={(identifier) =>{
    if (identifier === 'custom_text_search') {
      console.log('Custom Search Action Tapped');
      // 处理自定义搜索操作
    } else if (identifier === 'custom_editor') {
      console.log('Custom Editor Action Tapped');
      // 处理自定义编辑操作
    } else if (identifier === 'custom_share') {
      console.log('Custom Share Action Tapped');
      // 处理自定义分享操作
    }
  }}
  />

添加自定义图标资源

要自定义菜单图标，您需要在 Android 和 iOS 平台中分别添加图标资源：

• Android：将图标文件（如 ic_test_search.png）放入 android/app/src/main/res/drawable 目录。
• iOS：将图标文件（如 ic_test_search.png）添加到 ios/Runner/Assets.xcassets 资源集。