110 lines
5.4 KiB
Markdown
110 lines
5.4 KiB
Markdown
# 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`。
|