问 【鸿蒙二开】WPS Open SDK 能力全景与参数映射

鸿蒙侧接 WPS Open SDK 时，建议把「能力」对齐到接口字段：注册、只读与可编辑、水印、extraOptions、关窗回传、以及不落地相关约束。先对照清楚再写封装，联调会少走弯路。本文用精简代码说明如何组合，方便社区同事对照工程落地。

能力对照

先注册，再沙箱路径，再叠加策略。一次堆参难排查。

注册

未注册 sendRequest 会 reject；1013 查包名与凭据。

import { common } from '@kit.AbilityKit';
import {
  WPSApi,
  RegisterAppRequest,
  OpenFileRequest,
  OpenFileExtraOptions,
  WaterMark,
  TransferType,
  ResultCode,
  SdkConstants,
} from '@wps/wps_sdk';

let wpsReady = false;

async function ensureRegistered(ctx: common.UIAbilityContext): Promise<void> {
  if (wpsReady) return;
  const r = await WPSApi.sendRequest(
    new RegisterAppRequest(ctx, APP_KEY, APP_SECRET)
  );
  if (r.code === ResultCode.ERROR_CODE_AUTH_FAILURE) {
    throw new Error(`1013: ${r.msg ?? ''}`);
  }
  if (r.code !== ResultCode.OK) {
    throw new Error(`register ${r.code}`);
  }
  if (!SdkConstants.isPersonalSdk() && ACTIVATION_SN) {
    WPSApi.setWpsFileToken(ACTIVATION_SN);
  }
  wpsReady = true;
}

组合打开

import fs from '@ohos.file.fs';

function toSandbox(ctx: common.UIAbilityContext, src: string): string {
  const dir = `${ctx.filesDir}/wps_cap`;
  fs.mkdirSync(dir, true);
  const dest = `${dir}/${Date.now()}.docx`;
  fs.copyFileSync(src, dest);
  return dest;
}

async function openWithCapability(
  ctx: common.UIAbilityContext,
  src: string,
  opts: {
    editable: boolean;
    watermark?: string;
    transfer?: boolean;
    lockShare?: boolean;
  }
) {
  await ensureRegistered(ctx);
  const path = toSandbox(ctx, src);
  const req = new OpenFileRequest(ctx, path);
  req.enableEdit = opts.editable;

  if (opts.watermark) {
    const wm = new WaterMark();
    wm.Enable = true;
    wm.WaterMaskText = opts.watermark;
    wm.Angle = -30;
    wm.FontColor = '#19000000';
    wm.FontSize = 16;
    req.wpsWaterMarkParams = wm;
  }

  if (opts.transfer) {
    req.wpsTransferType = TransferType.URI;
  }

  if (opts.lockShare) {
    const extra = new OpenFileExtraOptions();
    extra.enableShare = false;
    extra.enableCloud = false;
    extra.enablePrint = false;
    extra.enableExport = false;
    req.extraOptions = extra;
  }

  const res = await WPSApi.sendRequest(req);
  if (res.code !== ResultCode.OK) {
    throw new Error(res.msg ?? String(res.code));
  }
  return res;
}

联调顺序：只读 → 可编辑 → 关分享 → 水印 → 回传。不落地模式下部分菜单可能被强制关闭，以真机为准。

回传注意

async function openAndCollect(ctx: common.UIAbilityContext, src: string) {
  const res = await openWithCapability(ctx, src, {
    editable: true,
    transfer: true,
    watermark: `${uid}|内部`,
    lockShare: true,
  });
  // 未关窗时可能没有 data，不要当失败
  if (!res.data?.fileUri) {
    return null;
  }
  const f = fs.openSync(res.data.fileUri, fs.OpenMode.READ_ONLY);
  const dest = `${ctx.filesDir}/wps_out/${Date.now()}.docx`;
  fs.mkdirSync(`${ctx.filesDir}/wps_out`, true);
  fs.copyFileSync(f.fd, dest);
  fs.closeSync(f);
  return dest;
}

OK && !data 多为未关窗。切回应用不等于关窗。

小结

能力全景 = 参数组合。把场景收成选项，页面只调统一入口。字段以官方文档为准。

鸿蒙侧刚开始梳理 WPS Open SDK 能力时，建议先把产品口头需求翻译成字段：打开、编辑、水印、关外发、回传、落地约束。对照清楚后再写封装，联调会少走弯路。

补充联调建议：小 docx / xlsx 各测一轮；换 HAR 后 clean；日志打 code/msg。菜单与预期不符时，先查不落地强制关闭，再查 extraOptions 是否赋值。页面不要散落多处 new OpenFileRequest，统一入口更稳。

真机回归至少覆盖：只读打开、可编辑、关分享、关窗回传。OK 且无 data 时先确认是否关文档窗。序列号用全局注入，不要每次 open 赋值。把能力对照表贴到项目 README，方便同事接手。

工程实践上，我还会固定几条约定：Preview / Edit 共用函数；策略参数只允许在打开模块赋值；页面禁止直接构造请求。Debug 与 Release 使用不同凭据文件，打包前打印 bundleName。把入口收束后，换 HAR、改 flavor 时回归范围更小，也更适合多人协作持续迭代鸿蒙 WPS 二开能力。

更多参数见官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT

申请 SDK HAR 与凭据：m_open_sdk@wps.cn（注明包名与接入需求）。

技术交流 QQ 群：628436767