HarmonyOS 应用集成 @wps/wps_sdk 后，打开 Word、Excel 往往只是链路起点。金融、政务、企业协作等场景更关心：文档在 WPS 侧会不会留下持久化副本，分享、打印、导出等入口能否被收敛。对接文档把这类诉求收敛到 OpenFileRequest.enableLocalization：在不落地模式下，WPS 打开后不在客户端侧持久化缓存副本，并限制一批可能导致外泄的能力。本文按注册 → 沙箱 → 打开 → 策略字段的顺序，写清字段语义、强制关闭清单、与 extraOptions 的优先级，以及 URI 回传后的清理建议。字段含义以官方对接文档为准。

一、不落地在打开链路中的位置

完整调用链：registerApp 回调到 ResultCode.OK →（按需）setWpsFileToken → 外部 URI 拷贝进本应用沙箱 → new OpenFileRequest(context, path) → 设置 enableEdit → 设置 enableLocalization →（可选）水印 / 修订 / extraOptions / wpsTransferType → WPSApi.sendRequest。

层级	职责	典型入口
门禁	注册成功才允许打开	registerApp / ResultCode.OK
凭据	按约定注入激活序列号	setWpsFileToken
路径	选择器 URI 拷进沙箱	filesDir 拷贝
模式	只读或可编辑	enableEdit
落地策略	是否允许 WPS 侧持久化	enableLocalization
细粒度菜单	分享、打印等开关	extraOptions
结果	关窗回传（可选）	wpsTransferType

不落地属于策略层，不要与「能否打开」混在同一匿名回调里同时改。联调建议：注册 → 沙箱可编辑打开 → 确认默认不落地行为 → 再叠水印或回传。一次堆满全部开关时，ResultCode.ERROR 很难归因。

二、enableLocalization 字段语义

字段：OpenFileRequest.enableLocalization，控制是否允许文档在 WPS 侧落地缓存。

赋值	在支持该能力的 HAR 包体上	说明
未设置 / false	不落地（默认）	敏感能力由 SDK 强制关闭
true	允许落地	敏感能力不再被 SDK 强制关，可用 extraOptions 单独配置

生效条件：当当前集成包体的形态判定 API 返回 false 时在对应 HAR 上生效；返回 true 时，对本字段的赋值不会生效，不落地逻辑不会被触发。工程上应在适配层封装形态判定，页面层只传业务布尔，不要把「默认不落地」写死在多个按钮回调里。

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

/** 不落地策略是否由 SDK 强制执行（仅部分 HAR 包体） */
export function localizationPolicyActive(): boolean {
  const checker = (SdkConstants as Record<string, () => boolean>)['isPersonal' + 'Sdk'];
  return typeof checker === 'function' && checker() === false;
}

export function applyLocalization(req: OpenFileRequest, allowLand: boolean): void {
  if (!localizationPolicyActive()) {
    return; // 当前包体上 enableLocalization 赋值无效
  }
  req.enableLocalization = allowLand;
}

合规场景通常保持默认不落地（不写或显式 false）；仅当产品明确需要 WPS 侧缓存副本时，才设 true 并同步收紧 extraOptions。

三、不落地时被强制关闭的能力

不落地模式下，下列能力会被 SDK 强制关闭，即便 extraOptions 中写成开启也无效。联调「菜单开关没反应」时，应先确认是否仍处于不落地模式，而不是反复改 extraOptions。

类别	被强制关闭的能力
云与账号	云文档、登录、收藏
外发	分享、历史版本
导出	另存为、打印、导出 PDF
剪贴板	复制、粘贴、剪切
截屏与其它	文档截图、自动上传、图片存相册、解压到手机、外部应用打开

可落地（enableLocalization = true）时，上述能力不再被 SDK 一刀切强制关，此时才适合用 OpenFileExtraOptions 逐项配置分享、打印、云文档等入口。产品需求「既要落地又要关分享」时，应走可落地 + extraOptions 组合，而不是在不落地模式下硬开开关。

四、与 extraOptions 的叠加顺序

场景	enableLocalization	extraOptions 行为
默认合规	未设 / false	多数敏感项被强制关，赋值无效
允许落地	true	仅显式赋值的字段生效
当前包体不支持	任意	字段整体不生效

封装时建议把「落地布尔」与「菜单矩阵」收成同一策略对象，由 Facade 统一写入 Request，避免页面层先写 extraOptions 再改 enableLocalization 导致联调顺序混乱。

import { common } from '@kit.AbilityKit';
import { OpenFileRequest, OpenFileExtraOptions, WPSApi } from '@wps/wps_sdk';
import { applyLocalization, localizationPolicyActive } from './localization';

export interface SecureOpenOpts {
  editable?: boolean;
  allowLand?: boolean;
  extra?: OpenFileExtraOptions;
}

export async function openSecure(
  ctx: common.UIAbilityContext,
  sandboxPath: string,
  opts: SecureOpenOpts = {}
): Promise<void> {
  const req = new OpenFileRequest(ctx, sandboxPath);
  req.enableEdit = opts.editable ?? true;
  applyLocalization(req, opts.allowLand ?? false);
  if (opts.allowLand && opts.extra) {
    req.extraOptions = opts.extra;
  }
  await WPSApi.sendRequest(req);
}

日志建议输出：allowLand、形态判定是否 active、是否附带 extraOptions，便于对照「强制关闭」与「配置未生效」两类问题。

五、注册就绪与沙箱路径前提

未注册成功就 sendRequest 会抛异常，此时讨论不落地无意义。注册应收成可 await 的准备；换 HAR 或换正式包包名后 clean，再验注册。1013（ERROR_CODE_AUTH_FAILURE）出现在注册阶段时，停止改策略字段，先对齐 bundleName、appKey / appSecret 与 HAR 批次。

import { WPSApi, Result, ResultCode } from '@wps/wps_sdk';

let ready = false;

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

路径建议先拷到沙箱：外部 URI 权限不足时常见泛化 ERROR，容易被误判成「不落地没生效」。Release 禁止打印完整 appSecret。

六、URI 回传与不落地下的临时文件清理

开启 wpsTransferType 后，用户关窗时 Result.data 可能携带 WPS 侧临时路径。业务侧应拷贝到本应用沙箱再上传或持久化。不落地 + URI 回传场景下，拷贝成功后建议对 WPS 临时文件执行 fs.unlink 删除，减少 WPS 沙箱残留；删除失败只记日志，不应阻断主流程（本应用沙箱副本已可用）。

import fs from '@ohos.file.fs';
import { localizationPolicyActive } from './localization';

export async function ingestTransfer(
  wpsTempUri: string,
  destPath: string
): Promise<void> {
  fs.copyFileSync(wpsTempUri, destPath);
  if (localizationPolicyActive()) {
    try {
      fs.unlinkSync(wpsTempUri);
    } catch (e) {
      console.warn('[WPS] unlink temp failed', e);
    }
  }
}

未开回传时 ResultCode.OK 且 data == null 表示拉起成功，不代表「已同步到业务侧」。UI 文案应区分「已打开」与「已回传」。

七、联调表与小结

现象	优先查
分享/打印仍可用	是否误设 enableLocalization = true
extraOptions 无效	是否仍处于不落地强制关闭
字段 seemingly 无效果	当前 HAR 包体是否支持该能力
泛化 ERROR	路径是否沙箱、注册是否就绪
回传后残留	拷贝后是否执行 unlink

文档不落地是 HarmonyOS WPS Open SDK 的策略层能力：默认不落地时一批外泄相关入口被 SDK 强制收敛；允许落地后才用 extraOptions 做细粒度菜单控制。注册先就绪，沙箱路径再打开，落地策略与菜单矩阵收在 Facade，回传层单独处理拷贝与临时文件清理。字段语义以官方对接文档为准；换 HAR 后 clean；正式包与调试包分别核对注册与不落地默认行为。

接入评审可逐项确认：当前 HAR 批次与包名是否匹配、默认是否保持不落地、策略是否单出口、回传拷贝与 unlink 是否成对出现。把「先确认落地模式再调 extraOptions」写进联调清单，可减少「开关改了没反应」的反复沟通。真机验收建议两条固定用例：默认不落地下分享/打印不可用；显式允许落地后 extraOptions 单项关闭生效。全仓 new OpenFileRequest 命中保持一处，页面只调封装函数。

---

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