Skip to content

INSTALL.md

Latest commit

 

History

History
197 lines (138 loc) · 9.36 KB

INSTALL.md

File metadata and controls

197 lines (138 loc) · 9.36 KB
Raw

INSTALL.md —— 从零到跑通本系列示例

本文档写给“第一次接触 WPS 插件开发”的观众：从下载哪些软件开始，到把五个示例逐个安装进 WPS。

适用环境：Windows 10/11。全程不需要编译工具链、不需要证书签名、不需要联网注册（网页类元素用本地服务器发布即可）。

1. 需要从零下载的软件

1.1 WPS Office（必需）

事项 说明
下载 官网下载 WPS 个人版安装包（.exe），或使用 WPS 专业版
版本要求 能运行本系列至少需要较新版本（个人版 2021 之后的 12.1.x 系列）。打开任意 .pptx，设置 → 关于 WPS 查看版本号
注意 不要装 Microsoft Store / 应用商店的 UWP 精简版（缺宏与加载项能力）
企业定制版 如果所在公司版没有“宏/加载项”，需要管理员在后台开启加载项权限

安装后建议先双击一个 .pptx 确认正常，再继续。

1.2 Node.js（强烈推荐，用于起本地网页服务）

1.3 代码编辑器（可选）

1.4 可以不用装的东西

  • ❌ 不需要 Visual Studio / C++ 工具链；
  • ❌ 不需要申请任何开发者证书（本地离线加载项直接放目录即可被加载）；
  • ❌ 不需要把插件上传到应用商店（那是另一套“在线加载项”流程，本系列用离线模式）。

2. 先理解：WPS 本地加载项是怎么“装进去”的

WPS 每次启动演示文稿时，会扫描用户目录下的注册文件：

%APPDATA%\kingsoft\wps\jsaddons\
├── publish.xml            ← 注册表：声明有哪些插件
└── <NAME>_<VERSION>\      ← 插件本体文件夹（本系列每个示例一个）
    ├── ribbon.xml            注入到“功能区”的按钮
    ├── index_TaskPane.html   任务窗格页面
    └── js\main.js            功能区按钮的回调（点击后打开任务窗格）

publish.xml 里一行一个插件，例如：

<?xml version="1.0" encoding="UTF-8"?>
<jsplugins>
  <jsplugin name="BASIC_RECT" enable="enable_dev" url="file://" type="wpp" version="1.0"/>
</jsplugins>

关键约定：

字段 说明
name / version 与插件文件夹名严格对应：文件夹必须叫 <name>_<version>
type wpp=演示、et=表格、wps=文字。本系列全部是 wpp
enable enable_dev，本地开发者模式

也就是说：“安装一个示例” = 复制插件文件夹 + 在 publish.xml 登记一行，仅此而已。本仓库的 tools/install.ps1 帮你自动完成这两步。

3. 推荐安装方式：脚本一键安装

打开 PowerShell，进入仓库目录：

cd d:\Projects\Misc\AnyTest\ppt_plugin_tutorials

安装某个示例（示例目录名见下表）：

powershell -ExecutionPolicy Bypass -File .\tools\install.ps1 -Demo 01_basic_shape -Kill
  • -Demo：01_basic_shape / 02_canvas_draw / 03_camera_element / 04_webgl_3d / 05_web_content
  • -Kill：装完后自动结束 WPS 进程（推荐，省得你手动退托盘）

然后重新打开 WPS → 新建或打开一个 .pptx，顶部功能区会出现对应标签（如「矩形色块」），点标签里的按钮即可打开任务窗格。

五个示例可以全部装上、互不冲突，功能区会各自出现一个标签。

4. 手动安装（了解原理，或脚本不可用时的备选）

  1. 打开资源管理器，地址栏输入 %APPDATA%\kingsoft\wps 回车；
  2. 进入（或新建）jsaddons 文件夹；
  3. 把某个示例的 addin\publish.xml 内容登记进 jsaddons\publish.xml：
    • 若目标不存在：直接复制整份文件；
    • 若已存在：用文本编辑器打开，把 <jsplugin .../> 那一行插到 </jsplugins> 之前，保留原有内容；
  4. 把该示例 addin\<NAME>_<VERSION> 整个文件夹复制到 jsaddons\ 下；
  5. 完全退出 WPS（含右下角托盘图标），重开 .pptx。

检查是否装好：jsaddons 下应同时存在 publish.xml 和插件文件夹，例如：

%APPDATA%\kingsoft\wps\jsaddons\
├── publish.xml
├── BASIC_RECT_1.0\
│   ├── ribbon.xml
│   ├── index_TaskPane.html
│   ├── css\style.css
│   └── js\{main,host,core,taskpane}.js
└── CANVAS_DRAW_1.0\  ...

卸载：删除对应插件文件夹，并把 publish.xml 里它的那一行删掉即可。（WPS 会自动生成 authaddin.json 这类缓存，残留条目不影响使用，可一并手动删除对应 name 条目。）

5. 网页类元素（02/03/04/05）需要本地网页服务

原理（重要，视频里会反复讲）：

  • WPS 的网页形状不允许直接打开 file:// 本地文件（空白页），必须走 http://127.0.0.1；
  • 03 摄像头用的 getUserMedia 也只在 localhost/127.0.0.1 这类“安全来源”下可用。

所以先启动本仓库的静态服务器（Node 版）：

# 语法：node tools/serve.js <端口> <元素目录>
node tools/serve.js 8011 .\02_canvas_draw\element

没装 Node 的备选（Python 3.7+，命令行为 python 或 py -3）：

python -m http.server 8011 --directory .\02_canvas_draw\element

浏览器打开 http://127.0.0.1:8011/canvas.html 验证可访问后，再去插件里点“插入”。

各示例约定端口：

示例 元素目录 服务命令
02 画布 02_canvas_draw\element node tools/serve.js 8011 .\02_canvas_draw\element
03 摄像头 03_camera_element\element node tools/serve.js 8012 .\03_camera_element\element
04 3D 04_webgl_3d\element node tools/serve.js 8013 .\04_webgl_3d\element
05 网页内容(示例页) 05_web_content\element node tools/serve.js 8005 .\05_web_content\element

05 嵌入远端网站时不需要本地服务；只有嵌入仓库自带的 dashboard.html 示例时才需要 8005。

6. 每个示例的运行清单

目录 功能 需要服务器？ 操作
01_basic_shape 插入矩形色块，可调颜色/透明度 否 打开 pptx → 点「矩形色块」标签 → 「插入矩形」按钮 → 调颜色实时上色
02_canvas_draw 实时画布元素 是（8011） 先启动服务 → 点「手绘画布」标签 → 插入画布 → 放映(F5) 后在元素里画
03_camera_element 摄像头画面元素 是（8012） 同上；放映后点元素内的“开启摄像头”，授权即可看到画面
04_webgl_3d WebGL 3D 元素 是（8013） 同上；放映后看到旋转立方体/三维曲线动画
05_web_content 插入任意网页 可选（8005） 输入网址 → 选尺寸 → 插入 → 放映后点击交互

编辑状态下网页元素显示的是网页首帧缩略图，真正“活”起来要到放映（F5）。这是 WPS 网页形状的设计行为，不是 bug。

7. 常见问题

现象 原因与处理
功能区没出现示例标签 插件未注册成功：检查 jsaddons\publish.xml 是否 UTF-8、插件文件夹名是否严格等于 <name>_<version>、是否完全重启了 WPS（含托盘）
点了按钮打开的是 Chrome/浏览器 插件版本过旧或路径解析失败：确认 js/main.js 顶部 PLUGIN_DIR_NAME 与插件文件夹名一致，且使用 Application.Env.GetAppDataPath() 拼绝对路径（本系列代码已内置）
任务窗格打开但提示“AddWebShapeEx 不可用” 当前 WPS 版本太旧或定制版裁掉了网页形状能力；01 不依赖该能力仍可演示，02~05 需升级 WPS 或换用网页形状可用的版本
插入后元素在编辑态是静态图 正常，放映后才渲染为可交互网页
元素显示空白/加载失败 服务没启动、端口/路径写错，或网址本身不可达；先在浏览器里打开元素 URL 验证
摄像头黑屏或被拒绝 必须用 http://127.0.0.1:<端口> 访问（安全来源）；检查是否有摄像头、是否被系统隐私设置拦截、是否在放映状态
WebGL 空白 检查显卡驱动/是否在远程桌面或虚拟机中（软件渲染受限）；浏览器里先打开 3D 元素页验证
企业定制版没有这些能力 加载项/宏被管理员关闭，需联系管理员开启

8. 教学建议（配套视频用）

  1. 每集先展示“成品效果”，再拆讲对应示例目录与代码；
  2. 01 讲清 publish.xml → ribbon.xml → main.js → 任务窗格 → core.js 的数据流，后续所有示例共用这层认知；
  3. 02 开始引入“本地服务 + 网页元素”双进程思维（插件管壳、网页管内容）；
  4. 03、04 复用 02 的壳，只替换 element/*.html，正好印证“元素内容可替换”的架构；
  5. 05 作为综合篇收尾，讲解远端内容、尺寸预设、透明度探测这些工程化细节。