Files
webup-cloud/frontend/public/extension-development.md
WebUp Cloud db82325ed7
Verify control plane / verify (push) Canceled after 0s
Initial import of WebUp Cloud
2026-11-07 13:31:14 +08:00

110 lines
5.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# WebUp Cloud 插件与主题开发文档
适用扩展 API 版本 1。在管理后台打开「插件与主题」,选择自己制作的 ZIP,上传并校验,然后点击「启用此版本」。启用的插件出现在用户工作台的「扩展工具」。启用的主题应用到首页和用户工作台。
## 通用清单
将 UTF-8 编码的 `manifest.json` 放在 ZIP 根目录:
```json
{
"apiVersion": 1,
"type": "plugin",
"id": "studio.word-counter",
"version": "1.0.0",
"name": "文字统计",
"description": "在工作台统计字符和词数。"
}
```
| 字段 | 要求 |
| --- | --- |
| `apiVersion` | 整数 `1` |
| `type` | `plugin` 或 `theme` |
| `id` | 最长 64 字符,以小写英文字母开头。后续可用小写字母、数字及由 `.` 或 `-` 隔开的段。建议使用开发者前缀 |
| `version` | 最长 32 字符。三段式非负整数,例如 `1.0.0`,每段除 `0` 外不加前导零 |
| `name` | 展示名称,最长 80 字符 |
| `description` | 可选说明,最长 500 字符 |
ZIP 最大 512 KiB。插件只打包 `manifest.json` 和 `index.html`,主题只打包 `manifest.json` 和 `theme.json`。选中两个文件打包,别把外层目录、依赖或隐藏文件一起压进去。清单最多 8 KiB,HTML 最多 256 KiB,主题 JSON 最多 16 KiB,均按解压后的大小计。
## 开发插件
插件在工作台中的独立页面运行。把 HTML、样式和脚本构建成一个 `index.html`。用 `<style>` 写样式、`<script>` 写逻辑,并通过 `addEventListener` 绑定事件。
```html
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>文字统计</title>
<label>输入文字 <textarea id="input"></textarea></label>
<output id="result">0 个字符</output>
<script>
const input = document.getElementById("input");
const result = document.getElementById("result");
input.addEventListener("input", () => {
result.textContent = Array.from(input.value).length + " 个字符";
});
</script>
</html>
```
- 适合本地转换、计算器、文档速查及其他在浏览器内完成的工具。图片可以使用内嵌 data URL。运行时不加载 CDN、外部脚本、字体或接口,也不支持 HTML 事件属性、`eval`、弹窗及表单提交。
- 插件框架没有平台会话、宿主 DOM、存储访问权限,也没有接入钱包、项目、服务器、支付或后台事件的接口。v1 插件不提供后端执行或宿主消息桥。请勿在插件包中保存秘密或在插件中索取账户密码、密钥等敏感信息。
- 所有登录用户可使用已启用的插件。停用或切换后,新打开的页面只加载现行版本。已经打开的插件可运行到用户刷新或离开页面。
- 测试时,从用户工作台打开插件页面。直接打开 iframe 地址不会加载插件。生产反代需保留插件文档自己的 CSP 响应头。仓库内的 Nginx 配置已经为该路径单独转发。
插件框架的边界依据 HTML 的 iframe sandbox 和 CSP sandbox 规则。框架自身仍可发起文档导航,管理员应审核包的来源与代码。[HTML 标准](https://html.spec.whatwg.org/multipage/iframe-embed-object.html#attr-iframe-sandbox) · [CSP 规范](https://www.w3.org/TR/CSP3/#directive-sandbox)
## 开发主题
把清单中的 `type` 改为 `theme`,使用自己的 `id`。创建 `theme.json`:
```json
{
"light": {
"accent": "#146B57",
"accentSoft": "#DCF5EB",
"background": "#F1F8F4",
"surface": "#FFFFFF",
"text": "#13382C",
"muted": "#4B675D",
"border": "#CBDDD3",
"soft": "#E8F3ED"
},
"dark": {
"accent": "#6FE0BE",
"background": "#15271F",
"surface": "#20352B",
"text": "#E3F6ED"
}
}
```
浅色和深色至少填写一个。可只声明需要修改的颜色,缺省项沿用系统样式。所有值须为 `#RRGGBB`。字段对应主色、浅强调色、背景、表面、正文、辅助文字、边框和次背景。首页使用浅色配色。用户工作台跟随用户的浅色或深色选择。后台、登录页、已发布的用户站点及插件内页使用各自样式。v1 主题提供配色扩展,页面布局由 WebUp Cloud 提供。
## 打包与验证
从示例目录或你自己的文件目录运行以下任一命令。
```powershell
# 在插件目录
Compress-Archive -Path manifest.json,index.html -DestinationPath ../word-counter.zip
# 在主题目录
Compress-Archive -Path manifest.json,theme.json -DestinationPath ../forest-theme.zip
```
```sh
# 插件
zip -j ../word-counter.zip manifest.json index.html
# 主题
zip -j ../forest-theme.zip manifest.json theme.json
```
1. 用站点超级管理员账号上传。后台显示校验错误、包类型、版本和 SHA-256。主题上传后可先查看浅色与深色色卡。
2. 启用插件后,以普通账户打开「扩展工具」并试用。启用主题后,刷新首页并在工作台切换浅色和深色检查文字、按钮与背景。
3. 更新包时增加 `version`。已安装的同一 `type/id/version` 再上传同一个 ZIP 会返回原记录。如果 ZIP 字节变了,请提高版本号。同一插件只启用一个版本,站点同时只启用一套主题。
4. 回退时启用保留的旧版本。停用当前主题可恢复默认配色。停用后可以移除旧包,重新使用时需保留原 ZIP。站点最多保留 60 个扩展版本。
完整源码示例位于仓库的 `examples/extensions/word-counter` 和 `examples/extensions/forest-theme`。