【鸿蒙二开】WPS SDK 统一接口设计要点
社区里常有同学问：专业版和个人版是不是要写两套打开代码？按官方对接文档，API 是一套：单例 WPSApi，打开都用 OpenFileRequest。分叉主要在 HAR/凭据、激活序列号，以及少数字段（如不落地）是否生效。本帖用最短路径说明统一设计怎么落到二开工程。
统一链路长什么样
两端都必须：
registerApp 成功（否则 sendRequest 抛异常）
构造 OpenFileRequest（沙箱路径 + enableEdit 等）
WPSApi.sendRequest 拉起 WPS
专业版通常在注册成功回调里 setWpsFileToken；个人版注册成功即可打开，无需序列号。判断形态用 SdkConstants.isPersonalSdk()，别猜客户端包名。
import {
WPSApi, OpenFileRequest, Result, ResultCode, SdkConstants
} from '@wps/wps_sdk';
WPSApi.registerApp(APP_KEY, APP_SECRET, {
onCallback: (result: Result): void => {
if (result.code !== ResultCode.OK) {
console.error(result.code, result.msg);
return;
}
if (!SdkConstants.isPersonalSdk()) {
WPSApi.setWpsFileToken(PRO_SN);
}
}
});
function open(ctx, path: string, edit: boolean) {
const req = new OpenFileRequest(ctx, path);
req.enableEdit = edit;
return WPSApi.sendRequest(req);
}凭据与包名绑定，专业版/个人版凭据不可混用。换 flavor 后记得核对 bundleName，否则容易出 1013。
同一参数模型，差异在生效范围
水印、修订、extraOptions、回传类型字段名两端一致。enableLocalization（文档不落地）仅专业版生效；个人版设置了也不会走不落地逻辑。不落地时，分享/云文档/打印等可能被强制关闭，覆盖你在 extraOptions 里开的开关——联调要先确认落地策略，再谈菜单。
建议业务只维护一个 Facade：prepare(key, secret, sn?) + open(...)。序列号用构建配置注入，页面不要复制两套 Helper。
联调顺序与常见坑
推荐：注册 → 沙箱只读 → 可编辑 → 策略字段 → 回传；专业版再测不落地。
常见坑：
未注册就打开（两端一样会炸）
在 OpenFileRequest.wpsToken 每次塞序列号（更推荐全局 setWpsFileToken）
个人版也写不落地逻辑并期待生效
一次堆满所有开关导致 ResultCode.ERROR 难归因
文件路径建议先拷到应用 filesDir 再打开。直接传外部 URI 时，权限不足常表现为泛化失败，日志里不一定写明「权限」。换构建变体后核对 bundleName 与申请凭据一致，避免调试包装得上、正式包 1013。
工程上只保留一个 Facade 即可：prepare(key, secret, sn?) 负责注册与可选序列号，open(ctx, path, edit, …) 负责构造请求。水印、回传用可选参数扩展，不要为每个入口复制一份 new OpenFileRequest。产品选专业版还是个人版是场景问题；开发是否分叉 API 是工程问题——统一版要消掉的是后者。
小结与获取 SDK
统一版的工程含义是：学习一次接口，按场景申请对应 HAR，用适配层消化差异，而不是维护两套平行 API。字段与错误码以对接文档为准。联调时把 Result.code 与 msg 打全，比只打「打开失败」四个字好定位得多。
更多参数见官方对接文档：https://365.kdocs.cn/l/clQl5cek2NoT
申请 SDK HAR 与凭据：m_open_sdk@wps.cn（注明包名与专业版/个人版需求）。
技术交流 QQ 群：628436767
