鸿蒙 WPS 二开实战：用 Open SDK 的 extraOptions 管控文档内功能开关

在 HarmonyOS 应用开发中，越来越多的政企、金融、办公类应用需要在端内直接打开并编辑 Word、Excel、PPT 等文档。相比自建预览引擎，接入 WPS Open SDK 是更稳妥的路线：由 WPS 提供成熟的排版与编辑能力，三方应用通过二开接口完成拉起、鉴权、参数配置与结果回传。对于安全合规要求较高的场景，仅仅「能打开文档」往往不够——厂商还需要精细控制 WPS 内部的分享、打印、云同步等行为。WPS Open SDK 鸿蒙版为此提供了 extraOptions 能力，本文将结合二开实践经验，系统讲解其用法与注意事项。

一、为什么二开场景需要 extraOptions

WPS 作为完整的办公客户端，内置了分享、收藏、云文档、打印、导出等丰富功能。这些能力在普通个人办公场景中是加分项，但在政务 OA、央企内网、金融合规系统等 ToB 场景中，却可能成为数据外泄的通道。三方应用通过鸿蒙 WPS 二开接口打开文档时，通常希望：

• 允许用户在内嵌环境中阅读或编辑业务文档；
• 禁止或限制将文档分享到外部、上传云端、截屏外传；
• 在部分场景中保留打印或导出能力，在另一些场景中彻底关闭。

如果只能控制「只读 / 可编辑」，粒度显然不足。WPS Open SDK 在 OpenFileRequest 上提供了 extraOptions 字段，类型为 OpenFileExtraOptions，用于对 WPS 内部能力做细粒度开关。这是鸿蒙 WPS 二开体系中非常重要的一环，也是专业版安全方案的关键拼图。

二、extraOptions 在 SDK 架构中的位置

鸿蒙 WPS 二开的典型流程是：集成 HAR 包 → registerApp 完成注册 → 构造 OpenFileRequest → WPSApi.sendRequest 拉起 WPS。extraOptions 正是 OpenFileRequest 的扩展参数之一，与 enableEdit（编辑模式）、水印参数、修订参数、关闭回传参数等并列。

需要强调的是：extraOptions 采用的是「显式赋值生效」策略——只有开发者明确赋值的属性才会覆盖默认行为，未赋值的项保持 WPS 客户端原有逻辑。这种设计对二开同学很友好：不必一次性配置十几项开关，可以按场景逐步收紧权限。

下面列出 OpenFileExtraOptions 的主要属性及其含义，便于在正式项目中查阅：

属性	控制的能力
enableShare	分享功能
enableHomeShareTab	首页分享 Tab
enableStar	收藏 / 星标
enableCloud	云文档相关
enableLogin	登录引导
enableHistoryVersion	历史版本
enableAccompany	随行面板
enableCopy	复制（同时影响剪切）
enablePaste	粘贴
document_save	保存
enableSaveAs	另存为
enablePrint	打印
enableExport	导出 PDF、图片存相册等
enableScreenShot	文档内截图
enableAutoUploadDoc	自动上传文档
enableOpenWithExternalApp	使用外部应用打开

在实际二开项目中，建议由产品、安全、研发共同确定一份「场景—开关矩阵」，再映射到上述字段，避免上线后临时改配置。

三、代码示例：为政务场景收紧 WPS 内能力

以下示例展示在专业版 SDK 场景下，打开一份可编辑文档，同时通过 extraOptions 关闭分享、云文档、打印、导出和截图等能力。示例基于 TypeScript / ArkTS 写法，与官方对接文档保持一致。

import { common } from '@kit.AbilityKit';
import {
  WPSApi,
  OpenFileRequest,
  OpenFileExtraOptions,
  Result,
  ResultCode,
} from '@wps/wps_sdk';

function openDocWithRestrictedFeatures(
  context: common.UIAbilityContext,
  sandboxPath: string
) {
  const request = new OpenFileRequest(context, sandboxPath);
  request.enableEdit = true;

  const extra = new OpenFileExtraOptions();
  extra.enableShare = false;
  extra.enableHomeShareTab = false;
  extra.enableCloud = false;
  extra.enablePrint = false;
  extra.enableExport = false;
  extra.enableScreenShot = false;
  extra.enableOpenWithExternalApp = false;
  request.extraOptions = extra;

  WPSApi.sendRequest(request)
    .then((result: Result) => {
      if (result.code === ResultCode.OK) {
        console.info('文档已在受限模式下打开');
      } else {
        console.error('打开失败', result.msg);
      }
    })
    .catch((e: Error) => {
      console.error(e.message);
    });
}

几点说明：

关于文件路径，建议先拷贝到应用沙箱，再传入 OpenFileRequest，避免权限不足导致 WPS 无法读取。专业版场景下激活序列号推荐在 registerApp 成功回调中通过 setWpsFileToken 全局设置，而不是在单次 Request 里传 wpsToken。截图控制也可通过 request.enableScreenShot 设置，与 extraOptions.enableScreenShot 二选一即可，避免重复配置。

四、与专业版「文档不落地」的关系

鸿蒙 WPS 二开的专业版 SDK 支持「文档不落地」能力，通过 enableLocalization 控制。当该参数不设置或为 false 时，专业版默认进入不落地模式：文档不在 WPS 侧持久化缓存，同时 SDK 会强制关闭一批敏感能力，包括云文档、分享、打印、导出、截图、外部应用打开等——即使你在 extraOptions 里把它们设为 true，也不会生效。

这意味着：在严格的不落地场景中，安全边界首先由 enableLocalization 决定，extraOptions 是在「允许落地」（enableLocalization = true）的前提下，才成为有效的细粒度旋钮。二开团队在设计方案时应先与业务方确认是否必须不落地，再决定 extraOptions 的可配置空间。

对个人版（ToC）SDK 而言，enableLocalization 设置后不生效，不落地逻辑不会触发，但 extraOptions 仍可按照个人版 WPS 客户端的实际行为进行配置，具体以官方对接文档为准。

五、ToB 与 ToC 二开时的配置建议

统一版 WPS Open SDK 的核心价值之一，是专业版与个人版共用一套 API 设计。对于 extraOptions，两端接口一致，但部署环境不同：

专业版 ToB 场景：建议默认关闭分享、云文档、外部打开；是否允许打印、导出由合规等级决定；配合水印与关闭回传，形成完整闭环。

个人版 ToC 场景：面向大众用户的阅读、轻编辑应用，可适当放开复制、保存等基础能力，但仍建议评估是否需要限制截图和分享。

统一代码结构：可用 SdkConstants.isPersonalSdk() 判断当前集成的 SDK 版本，在同一代码库中分支处理不落地与 extraOptions 的组合逻辑，降低维护成本。

六、常见问题与排查思路

现象一：配置了 enableShare = false，用户仍能分享。 检查是否处于专业版不落地模式，或不落地强制关闭逻辑已覆盖。也要确认属性是否显式赋值，以及 WPS 客户端版本是否满足 SDK 要求。

现象二：个人版与专业版表现不一致。 核对 HAR 包与接入凭据是否匹配，专业版与个人版凭据不可混用。

现象三：sendRequest 无回调。 务必通过 .then() 处理结果，.catch() 捕获未注册等异常，这是二开接入的基本规范。

七、小结

对于鸿蒙 WPS 二开而言，extraOptions 是让三方应用从「仅能打开文档」迈向「可运营、可管控」的关键能力。它位于 OpenFileRequest 扩展参数层，与编辑模式、水印、关闭回传等能力协同工作；在专业版不落地场景下，还需与 enableLocalization 综合考量。建议团队在接入阶段就梳理功能开关矩阵，在测试环境逐项验证，再推广到生产。

如果你正在评估鸿蒙端文档二开方案，WPS Open SDK 统一版已支持专业版与个人版双端覆盖，接口与参数保持一致，有利于降低长期维护成本。

---

本文基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。
官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT
技术交流 QQ 群：628436767