AiPPT 插件文档

title: 设计工具与工具箱业务逻辑 date: 2026-08-27 tags:

  • AiPPT
  • 设计工具
  • 工具箱
  • 收藏 status: active

设计工具与工具箱业务逻辑

快速认识

设计工具有两类入口：

  • Ribbon上的独立按钮；
  • 工具箱中的功能卡片。

页面、协议和宿主实现分开维护。一个功能出现在工具箱里，不代表所有平台都能执行。

WPS能力状态摘要：

  • 已实现：对齐、分布、文本对齐、图层顺序、翻转旋转、成组、AutoSize和布尔运算等基础排版经工具箱可用，部分没有顶层Ribbon按钮；
  • 有页面、没有Handler：智能透视、渐变蒙版、形状圆角、PPT压缩和PPT清理，调用返回未实现错误；
  • 明确不支持：convertToFreeForm、combineShapes、splitShapes、convertTextToVector等命令。

Windows和macOS的设计页面共用同一套TypeScript协议，由各自Native层执行。

PPT清理当前放在测试环境AiPPT(feature) → 扩展，使用独立按钮btn_assist_7。Windows和macOS已实现，WPS入口未开放。

1. 工具箱页面

入口：

pages/offline/bag-zone

主要组件：

FunctionPanel
MainLayout
DraggableNavItem
ContentPanel
CardWrapper
Card
AddPlan
EditCard

Windows使用CTP或窗口，macOS使用NSPanel，私有化WPS使用TaskPane。

2. 独立设计页面

功能页面协议模块
统一字体uniform-fontUniformFont
统一颜色uniform-colorUniformColor
一键Logoshape-logoShapeLogo
环形布局circular-layoutCircularLayout
阵列布局matrix-layoutMatrixLayout
智能缩放intelligent-scaleShapeScale
圆角shape-corners-roundedShapeCornersRounded
渐变shape-gradientShapeGradientMask
智能透视intelligent-perspectiveShape3DTransform
重设主题色reset-theme-colorApplication/主题色接口
PPT清理ppt-cleanupPptCleanup

页面存在只表示UI和前端调用存在。平台支持还要检查Handler。

PPT清理

页面：

pages/offline/ppt-cleanup

协议：

PptCleanup.Scan
PptCleanup.Remove

范围：

currentSlide
allSlides

只处理普通文本框。文本仅含空格、Tab、CR或LF时判定为空；占位符、自选图形、组合、表格、SmartArt、图片和线条全部保留。

流程：

选择当前页或全部页
→ Scan返回受影响页数和文本框数
→ 用户二次确认
→ Remove重新扫描并删除
→ 返回实际删除页数和文本框数

平台状态：

平台状态实现
Windows PowerPoint已实现C# WebviewJsCallback/PptCleanup，Office Interop
macOS PowerPoint已实现Swift Native/PptCleanup，PowerPoint AppleScript
私有化WPS未实现无dispatcher Handler，测试Ribbon不勾选Wps

3. WPS已实现但没有顶层Ribbon按钮

能力当前入口
Shape对齐和分布工具箱
文本对齐工具箱
图层顺序工具箱
翻转和旋转工具箱
成组和取消成组工具箱
AutoSize工具箱
布尔运算工具箱，依赖WPS API
图形连接线Handler存在，顶层Ribbon未展示
显示/隐藏ShapeHandler存在，当前白名单未展示

Ribbon不是能力全集。功能盘点要同时检查Ribbon、工具箱、页面和Handler。

4. WPS有页面但没有实现

下面的页面和TypeScript调用存在，但WPS dispatcher没有对应Handler：

智能透视
渐变蒙版
形状圆角
PPT压缩
PPT清理

调用会返回未实现错误，不能标记为WPS已支持。

5. WPS明确不支持

designTools.convertToFreeForm
designTools.combineShapes
designTools.splitShapes
designTools.convertTextToVector
designTools.releaseCompoundPath
designTools.position
designTools.dockShape
DesignTools.MoveShapeToLayout

边缘裁切是条件支持：

ShapeRange.MergeShapes
→ 失败后ExecuteMso ShapesIntersect
→ 两条路径都失败则返回不支持

6. 三端调用

Windows

Web页面
→ impl/cpp.ts
→ WebView2消息
→ C# WebviewJsCallback
→ Office Interop

macOS

Web页面
→ impl/cpp.ts
→ Swift Bridge
→ Swift/VBA/AppleScript

WPS

Web页面
→ impl/wps.ts或wps-dispatcher.ts
→ window.Application

7. WPS工具箱白名单

代码：

bag-zone/components/Layout/DefaultData.ts

允许的方法：

designTools.align
designTools.distribute
designTools.textAlign
designTools.mergeShapes
designTools.zOrder
designTools.shapeAutoSize
ShapeConnector.AddShapeConnector
designTools.group
designTools.ungroup
application.commandBars.ExecuteMso
designTools.rotate
designTools.flip

排除的WPS命令：

FontDialog
ParagraphDialog
ObjectFormatDialog
SelectionPane

原因是目标WPS版本不能稳定执行这些ExecuteMso命令。

8. 工具箱窗口模式

平台容器是否原生停靠
WindowsCustom Task Pane或WPF窗口CTP是
macOSNSPanel否
私有化WPSCreateTaskPane是

macOS工具箱支持在线方案和收藏。私有化WPS固定为本地卡片，不应把两者写成同一种功能。

9. 基础排版工具

协议：

designTools.align
designTools.distribute
designTools.textAlign
designTools.zOrder
designTools.flip
designTools.rotate
designTools.group
designTools.ungroup
designTools.shapeAutoSize
designTools.mergeShapes
designTools.showOrHideShapes
DesignTools.DuplicateShape

功能：

  • 相对选中Shape或Slide对齐；
  • 水平和垂直分布；
  • 文本左中右、两端和分散对齐；
  • 上移、下移、置顶和置底；
  • 水平和垂直翻转；
  • 旋转；
  • 成组和取消成组；
  • 文本自动换行和固定宽高；
  • Shape布尔运算；
  • 显示和隐藏；
  • 原位复制。

10. 收藏数据模型

SolutionVo
└── CardVo
    └── RibbonInfoVo
类型含义
SolutionVo一套工具箱方案
CardVo一个可布局的功能卡片
RibbonInfoVo卡片中的具体功能
FunctionVo可加入卡片的候选功能

功能项包含：

ribbonId
label
image/svgCode
action.method
action.params
sort

点击功能项时，工具箱直接发送action.method和action.params，与Ribbon使用同一协议。

11. 收藏接口

config/solution/list
config/solution/add
config/solution/update
config/solution/sort
config/solution/icons
config/card/list
config/card/drag
config/solution/updateBatch
config/pocket/function/list
config/solution/quota

公网Windows/macOS工具箱把方案和卡片保存在服务端。

私有化WPS当前使用固定本地工具箱：

loadLocalToolbox
→ defaultCardDataWPS

不加载用户自定义方案，也不请求在线口袋功能列表。

12. 新增工具的检查项

  1. 页面或卡片入口；
  2. action.method和参数；
  3. Windows Handler；
  4. macOS Handler；
  5. WPS Handler；
  6. WPS白名单；
  7. Ribbon配置；
  8. 选区类型和空选区处理；
  9. 撤销或状态恢复；
  10. 目标Office/WPS版本验证。

13. 代码位置

pages/offline/bag-zone/
pages/offline/uniform-font/
pages/offline/uniform-color/
pages/offline/circular-layout/
pages/offline/matrix-layout/
pages/offline/intelligent-scale/
common/client-communication/
common/http/BagZone.ts

相关文档：

关系图谱

反向链接