HarmonyOS WPS Open SDK：用 extraOptions 管住分享打印与导出

在 HarmonyOS 应用接入 @wps/wps_sdk 后，打开与只读/可编辑往往先跑通，下一步产品会要求「预览禁止分享」「审批附件禁止另存为」或「关闭云文档入口」。对接文档把这类细粒度控制挂在 OpenFileRequest.extraOptions（类型 OpenFileExtraOptions）上。本文按调用链说明「仅显式赋值生效」的语义、常用开关分组、预设封装与联调清单，细节以官方对接文档为准。

一、功能开关在打开链路中的位置

典型时序：registerApp 成功 → 文件进沙箱 → new OpenFileRequest → 写入 enableEdit →（可选）水印/修订 → 写入 extraOptions → sendRequest。

层级	能力	入口
接入	注册、可选序列号	`registerApp` / `setWpsFileToken`
打开	拉起、只读/可编辑	`enableEdit`
策略	水印、修订	`wpsWaterMarkParams` / `wpsRevisionParams`
管控	分享、打印、导出等	`extraOptions`
结果	关窗回传	`wpsTransferType`

extraOptions 属于管控层，不要和「能否打开」绑在同一个布尔里。联调建议：注册 → 沙箱只读 → 可编辑 → 再逐项关分享/打印 → 最后回传。一次写满所有开关时，现象难归因。

二、核心规则：未赋值 ≠ false

对接文档写明：仅显式赋值的属性会生效；未赋值的项保持 WPS 默认行为。

常见误判是「对象 new 了但字段全空，以为等于全部关掉」。空对象不会关任何能力。封装时应按业务预设显式写 true / false，再赋给 request.extraOptions。

typescript 复制代码

import { OpenFileExtraOptions, OpenFileRequest } from '@wps/wps_sdk';

function applyLockedPreview(req: OpenFileRequest): void {
  const opt = new OpenFileExtraOptions();
  opt.enableShare = false;
  opt.enableHomeShareTab = false;
  opt.enableSaveAs = false;
  opt.enablePrint = false;
  opt.enableExport = false;
  opt.enableOpenWithExternalApp = false;
  req.extraOptions = opt;
}

只关掉需要管的项即可；不必把表里每一个字段都写一遍。未涉及的能力留给客户端默认。

三、开关分组与业务语义

按产品话术可粗分为四组（字段名以对接文档为准）：

分组	典型字段	常见诉求
外发	`enableShare` / `enableHomeShareTab` / `enableOpenWithExternalApp`	预览勿外传
落盘衍生	`enableSaveAs` / `enableExport` / `document_save`	审批附件勿另存
云与账号	`enableCloud` / `enableLogin` / `enableAutoUploadDoc`	减少云引导打扰
编辑辅助	`enableCopy` / `enablePaste` / `enablePrint` / `enableScreenShot`	只读预览收紧

enableCopy 同时影响剪切；关复制时要在验收用例里覆盖。enableScreenShot 与 Request 上同名能力二选一设置即可，避免两处互相覆盖造成联调困惑。

四、注册就绪与路径前提

未注册成功就 sendRequest 会抛异常，此时讨论开关无效。把注册收成可 await 的准备；换 HAR 或换正式包包名后 clean，再验注册。路径建议先拷到沙箱：外部 URI 权限不足时常见泛化 ERROR，容易被误判成「开关没生效」。

typescript 复制代码

let ready = false;

export function prepareWps(key: string, secret: string): Promise<void> {
  return new Promise((resolve, reject) => {
    if (ready) {
      resolve();
      return;
    }
    WPSApi.registerApp(key, secret, {
      onCallback: (result: Result): void => {
        if (result.code !== ResultCode.OK) {
          reject(new Error(`register ${result.code}`));
          return;
        }
        ready = true;
        resolve();
      },
    });
  });
}

需要激活序列号时，在注册成功回调里按凭据约定一次性设置，不要在每次 Request 上重复塞 Token。

五、可复用预设封装

把「预览收紧」「可编辑宽松」做成命名预设，页面不直接拼一长串布尔。

typescript 复制代码

export type ExtraPreset = 'preview-locked' | 'edit-default' | 'no-cloud';

function buildExtra(preset: ExtraPreset): OpenFileExtraOptions {
  const opt = new OpenFileExtraOptions();
  if (preset === 'preview-locked') {
    opt.enableShare = false;
    opt.enableSaveAs = false;
    opt.enablePrint = false;
    opt.enableExport = false;
    opt.enableOpenWithExternalApp = false;
  } else if (preset === 'no-cloud') {
    opt.enableCloud = false;
    opt.enableLogin = false;
    opt.enableAutoUploadDoc = false;
  }
  // edit-default: 不显式赋值，保持客户端默认
  return opt;
}

export async function openDoc(
  ctx: UIAbilityContext,
  src: string,
  mode: 'preview' | 'edit',
  preset?: ExtraPreset
): Promise<Result> {
  await prepareWps(APP_KEY, APP_SECRET);
  const path = copyToSandbox(ctx, src);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = mode === 'edit';
  if (preset && preset !== 'edit-default') {
    req.extraOptions = buildExtra(preset);
  }
  return WPSApi.sendRequest(req);
}

产品临时加「禁止打印」，只改预设或扩可选覆盖，不新开平行 Helper。关窗回传仍用独立字段，与 extraOptions 解耦。

六、联调表与日志

现象	优先查
抛异常	是否等注册完成
`1013`	凭据 / 正式包包名 / clean
开关「无效」	是否显式赋值、是否赋给 Request
仍能分享	`enableShare` / 首页分享 Tab 是否都关
泛化 ERROR	路径是否沙箱

日志固定：code / msg / ready / 沙箱 / enableEdit / 预设名 / 已赋值字段列表。全仓 new OpenFileRequest 命中保持一处。

七、小结与落地建议

HarmonyOS 上 WPS Open SDK 的 extraOptions，是打开管控层能力：在打开模式跑绿后再叠显式开关。未赋值保持默认，空对象不会关能力。封装用命名预设收口；路径进沙箱、注册先就绪、回传另算一层。字段语义以官方对接文档为准。

接入评审确认：HAR 批次、沙箱目录、预设是否走 Facade、正式包包名。缺一环容易出现「本地绿、上架红」。把「先模式后管控」写进联调清单，联调会从猜原因变成对表排查。换 HAR 后 clean；Release 不打印完整 secret。

真机验收可拆成固定用例：预览收紧（无分享/无另存）、可编辑默认、无云引导。三条都绿后，再叠水印或回传。若产品临时加禁止导出，只改预设，不复制打开函数。注释写清「本项目约定：extraOptions 只走 Facade」，比口头说「参考 Demo」更耐看。周五用正式包包名再验注册，并对照日志里的预设名与已赋值字段，确认管控相关误报是否下降。

从协作看，开关默认值应写进需求文档，避免不同页面各自猜。复制/粘贴、打印、导出属于高敏能力，验收清单要逐项点开菜单确认。路径拷贝失败要有明确提示，否则用户只会说「还能分享」或「打不开」。把上述约定坚持几周，管控层相关的反复提问通常会明显减少，接入节奏也会更稳。预设名建议用业务语言（如预览收紧），而不是字段堆叠名，方便产品和测试对齐。

基于 WPS Open SDK 鸿蒙版对接实践整理，仅供开发者参考。

官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT