WPS / PowerPoint 控制 API

用于远程控制 WPS 演示或 Microsoft PowerPoint 的 HTTP API 服务。

通过 COM 自动化接口操控本地 WPS/PowerPoint 应用，支持打开文件、启动放映、翻页、跳转、自动翻页、退出放映等功能，适用于演讲、演出等场景下的自动化幻灯片控制。

环境要求

• 操作系统： Windows
• Python： 3.10+
• 办公软件： WPS Office 或 Microsoft Office（至少安装其一）

安装

# 克隆项目
git clone <仓库地址>
cd ppt_control

# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

启动服务

python ppt_control.py

启动后服务监听 http://0.0.0.0:8000，默认自动启动 WPS（若未安装则回退到 PowerPoint）。

• Swagger 文档： http://127.0.0.1:8000/docs
• ReDoc 文档： http://127.0.0.1:8000/redoc

响应格式

所有接口统一返回以下 JSON 格式：

{
  "code": 20000,
  "message": "操作结果描述"
}

字段	类型	说明
code	int	状态码，20000 成功，50000 失败
message	string	成功时为操作结果描述，失败时为错误提示信息

接口列表

应用管理

方法	路径	说明
POST	/api/ppt/start_app	启动或重启 WPS / PowerPoint 应用
GET	/api/ppt/app_info	获取当前运行的应用信息（名称、版本、状态）
GET	/api/status	获取系统整体状态
POST	/api/ppt/exit_app	优雅关闭应用（通过 COM）
POST	/api/ppt/force_close	强制关闭应用进程

文件操作

方法	路径	说明
POST	/api/ppt/open	打开指定路径的 PPT 文件
POST	/api/ppt/close	关闭演示文稿（不关闭应用）

放映控制

方法	路径	说明
POST	/api/ppt/start	启动幻灯片放映
GET	/api/ppt/is_ready	检查是否已进入放映模式
GET	/api/ppt/current	获取当前幻灯片位置
POST	/api/ppt/next	下一步（触发动画或翻页）
POST	/api/ppt/prev	上一步（触发动画或翻页）
POST	/api/ppt/next_slide	下一页（跳过动画直接翻页）
POST	/api/ppt/prev_slide	上一页（跳过动画直接翻页）
POST	/api/ppt/goto	跳转到指定幻灯片
POST	/api/ppt/blank	黑屏/白屏/恢复
POST	/api/ppt/auto_play	根据时间线自动翻页（同步阻塞）
POST	/api/ppt/auto_play_async	异步自动翻页（立即返回，后台执行）
POST	/api/ppt/stop_auto_play	停止自动翻页
POST	/api/ppt/exit_show	退出放映模式

next/prev 与 next_slide/prev_slide 的区别：

• next / prev 模拟鼠标点击，会逐步触发幻灯片上的动画效果，所有动画播完后才翻页
• next_slide / prev_slide 跳过所有动画，直接跳转到上/下一张幻灯片

媒体信息

方法	路径	说明
GET	/api/media/info	获取当前幻灯片中的媒体信息（视频/音频）

接口详细说明

POST /api/ppt/start_app

启动或重启 WPS / PowerPoint 应用。

请求参数：

{
  "prefer": "wps"
}

参数	类型	默认值	说明
prefer	string	"wps"	首选应用：wps 或 ppt

POST /api/ppt/open

打开指定 PPT 文件。

请求参数：

{
  "file_path": "C:\Users\xxx\Desktop\demo.pptx"
}

参数	类型	必填	说明
file_path	string	是	PPT 文件的完整路径

POST /api/ppt/goto

跳转到指定幻灯片。

请求参数：

{
  "slide": 3
}

参数	类型	必填	说明
slide	int	是	目标幻灯片编号（从 1 开始）

POST /api/ppt/auto_play

根据时间线自动翻页，适合配合音乐或演讲节奏控制 PPT。

请求参数：

{
  "timeline": [[38.0, 2, 1.5], [50.0, 3, 1.2]],
  "lead_time": 0.0,
  "auto_exit": false
}

参数	类型	默认值	说明
timeline	array	必填	时间线数组 [[时间点, 翻页次数, 翻页间隔秒], ...]
lead_time	float	0.0	提前触发时间（秒）
auto_exit	bool	false	播放完成后是否自动退出放映

timeline 格式： [时间点, 翻页次数, 翻页间隔秒]

位置	类型	必填	默认值	说明
[0]	float	是	-	触发时间点（秒，相对于开始时刻）
[1]	int	否	1	翻页次数
[2]	float	否	0.0	多次翻页时的间隔秒数（翻页次数为 1 时无效）

示例：

[[38.0, 2, 1.5], [50.0, 3, 1.2]] 表示：

• 第 38 秒：点击 2 次，每次间隔 1.5 秒
• 第 50 秒：点击 3 次，每次间隔 1.2 秒

[[5.0, 1], [10.0, 1]] 表示：

• 第 5 秒和第 10 秒各点击 1 次（无需指定间隔）

POST /api/ppt/auto_play_async

异步版自动翻页，调用后立即返回，翻页在后台线程执行。参数与 /api/ppt/auto_play 完全一致。

可通过 /api/ppt/stop_auto_play 停止后台翻页任务。

POST /api/ppt/stop_auto_play

停止正在运行的自动翻页任务。此接口不受串行化中间件限制，可在自动翻页运行期间随时调用。

无需请求参数。

POST /api/ppt/blank

在放映模式下切换黑屏、白屏或恢复正常显示。

请求参数：

{
  "action": "black"
}

参数	类型	默认值	说明
action	string	"black"	black（黑屏）、white（白屏）、resume（恢复正常）

POST /api/ppt/close

关闭当前打开的演示文稿，但不关闭 WPS / PowerPoint 应用。如果正在放映会先退出放映模式。

无需请求参数。

打包为 EXE

pyinstaller --onefile --name ppt_control ^
  --hidden-import=comtypes.stream ^
  --hidden-import=uvicorn.logging ^
  --hidden-import=uvicorn.loops ^
  --hidden-import=uvicorn.loops.auto ^
  --hidden-import=uvicorn.protocols ^
  --hidden-import=uvicorn.protocols.http ^
  --hidden-import=uvicorn.protocols.http.auto ^
  --hidden-import=uvicorn.protocols.websockets ^
  --hidden-import=uvicorn.protocols.websockets.auto ^
  --hidden-import=uvicorn.lifespan ^
  --hidden-import=uvicorn.lifespan.on ^
  ppt_control.py

打包完成后在 dist\ 目录下生成 ppt_control.exe，可直接复制到任意位置双击运行，目标机器无需安装 Python 环境。

项目结构

ppt_control/
├── ppt_control.py       # 主程序（FastAPI 服务）
├── requirements.txt     # Python 依赖
└── README.md            # 项目说明

技术说明

• COM 自动化： 通过 comtypes 库操作 WPS (Kwpp.Application) 或 PowerPoint (PowerPoint.Application)
• 线程安全： 串行化中间件 + RLock + 线程本地 COM 初始化，确保 COM 对象不被多线程并发访问；异步翻页线程通过 GetActiveObject 重新获取 COM 引用，避免跨线程访问 STA 对象
• 容错机制： COM 对象有效性检测、"被呼叫方拒绝"错误自动重试、进程存活双重检测
• 应用优先级： 默认优先使用 WPS，失败自动回退到 PowerPoint