title: AiPPT Web 通信协议与平台适配 date: 2026-08-27 tags:

AiPPT
WebView
Native Bridge
WPS status: active

AiPPT Web 通信协议与平台适配

共享Web页面不直接依赖C#或Swift。页面调用TypeScript接口，运行时选择Native Bridge或WPS实现。

1. 最小调用与返回

页面只依赖interface.ts契约，运行时选择实现：

export const Application = window.Application ? WpsImpl : CppImpl;

环境	选择
WPS JS加载项	`impl/wps.ts`
Windows PowerPoint插件	`impl/cpp.ts`
macOS PowerPoint插件	`impl/cpp.ts`

最短调用链（Windows/macOS）：

页面 → impl/cpp.ts → postMessageToClient → C#/Swift Handler → PPT对象模型 → Response

最短调用链（WPS）：

页面 → impl/wps.ts → window.Application

统一Response<T>格式：

{
  code: number;
  body: T;
  message?: string;
  action?: string;
}

错误原则：

成功才resolve；
Native/WPS错误要reject；
未实现返回明确method名；
取消和用户关闭要与执行失败区分；
不返回空成功掩盖缺失功能。

排查具体现象见12. 调试顺序。WebView构建和平台离线包集成见WebView实现与打包。

2. 目录

aippt-plugin-webview/src/common/client-communication/
├── Application/
├── Browser/
├── Client/
├── Global/
├── Libraries/
├── wps-dispatcher.ts
├── wps-helpers.ts
└── 业务模块.ts

3. 五个基础模块

模块	负责	不负责
`Application`	当前PPT、Slide、Shape、选区、主题、备注、事件	插件窗口和系统文件选择器
`Browser`	Window、Panel、TaskPane、尺寸、位置、刷新	PPT内容操作
`Client`	Session、下载、日志、缓存、Ribbon、退出	Slide和Shape
`Global`	文件、路径、设置、系统窗口、DPI、外部URL	素材业务
`Libraries`	模板、Slide、图片和Shape的插入、替换、上传	通用窗口和登录

4. 接口结构

Application/
├── interface.ts
├── type.ts
├── index.ts
└── impl/
    ├── cpp.ts
    └── wps.ts

interface.ts是页面契约。两个实现必须返回相同的Response<T>结构。

5. Native Bridge路径

sequenceDiagram
    participant Page as Web页面
    participant API as impl/cpp.ts
    participant Bridge as postMessageToClient
    participant Native as C#或Swift
    participant PPT as PowerPoint

    Page->>API: 调用统一接口
    API->>Bridge: module.method和params
    Bridge->>Native: WebView消息
    Native->>PPT: 宿主对象模型
    PPT-->>Native: 结果
    Native-->>Bridge: code/body/message
    Bridge-->>Page: Promise resolve或reject

Windows桥由WebView2注入，Native处理器在WebviewJsCallback。macOS桥由WKWebView和Swift Client注入。

6. WPS模块化路径

impl/wps.ts直接调用：

window.Application
window.Application.FileSystem
window.Application.PluginStorage
window.Application.CreateTaskPane
window.Application.CreateWebDialog

WPS实现要兼容同步属性、Promise属性和不同版本的方法名。

7. module.method兼容路径

部分业务仍直接调用：

postMessageToClient("designTools.align", params)

在WPS环境中：

postMessageToClient
→ invokeWpsClientMethod
→ handlers[method]
→ wps-helpers
→ window.Application

代码：

utils/ClientUtil.ts
common/client-communication/wps-dispatcher.ts
common/client-communication/wps-helpers.ts

handler查找不区分大小写。没有handler时返回未实现错误。

8. 窗口ID和回调

窗口URL的Hash中通常带业务ID：

#id=btn_tools_28

用途：

查找当前Dialog或Panel；
设置窗口属性；
页面间消息；
复用或关闭窗口；
绑定下载进度回调。

Windows/macOS回调挂在window上的UUID表。WPS窗口ID保存在PluginStorage的dialogMap/taskPaneMap。

9. Token和设置

页面通过StorageAdaptor读写登录和设置：

StorageAdaptor
→ PersistentStorage
→ Global.getSettings/setSettings

平台存储：

平台	实现
Windows	Native Settings、注册表或文件
macOS	UserDefaults和Native Settings
WPS	WPS FileSystem中的aippt-cache.json
普通Web	localStorage

HTTP请求从StorageAdaptor.Token读取Token并加入Bearer头。

10. 新增接口

新增基础PPT能力时：

在interface.ts定义方法；
补充请求和响应类型；
在impl/cpp.ts定义Native消息；
Windows实现对应Handler；
macOS实现对应Handler；
在impl/wps.ts实现WPS路径；
如果保留旧协议，同步wps-dispatcher；
用三个目标宿主验证返回值和错误。

只改impl/cpp.ts会导致WPS缺功能；只加dispatcher会让模块化接口继续走旧路径。

11. 新增业务模块

页面级业务可以单独建模块，例如：

UniformFont.ts
CircularLayout.ts
ExportPdf.ts
JoinImage.ts

业务模块负责参数和调用，不应直接包含平台判断。平台判断留在基础模块或dispatcher中。

12. 调试顺序

现象	先查
页面按钮无反应	浏览器控制台和method名
Windows无回调	WebView2消息、C# Handler注册
macOS无回调	Swift rootRouter和导出符号
WPS提示未实现	dispatcher handler和大小写
WPS窗口找不到	Hash ID、dialogMap/taskPaneMap
HTTP无Token	StorageAdaptor和平台设置缓存
下载完成但未插入	Client.download回调和Libraries方法

AiPPT 插件文档

探索