5.4 KiB
WebUp Cloud 插件与主题开发文档
适用扩展 API 版本 1。在管理后台打开「插件与主题」,选择自己制作的 ZIP,上传并校验,然后点击「启用此版本」。启用的插件出现在用户工作台的「扩展工具」。启用的主题应用到首页和用户工作台。
通用清单
将 UTF-8 编码的 manifest.json 放在 ZIP 根目录:
{
"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 绑定事件。
<!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 标准 · CSP 规范
开发主题
把清单中的 type 改为 theme,使用自己的 id。创建 theme.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 提供。
打包与验证
从示例目录或你自己的文件目录运行以下任一命令。
# 在插件目录
Compress-Archive -Path manifest.json,index.html -DestinationPath ../word-counter.zip
# 在主题目录
Compress-Archive -Path manifest.json,theme.json -DestinationPath ../forest-theme.zip
# 插件
zip -j ../word-counter.zip manifest.json index.html
# 主题
zip -j ../forest-theme.zip manifest.json theme.json
- 用站点超级管理员账号上传。后台显示校验错误、包类型、版本和 SHA-256。主题上传后可先查看浅色与深色色卡。
- 启用插件后,以普通账户打开「扩展工具」并试用。启用主题后,刷新首页并在工作台切换浅色和深色检查文字、按钮与背景。
- 更新包时增加
version。已安装的同一type/id/version再上传同一个 ZIP 会返回原记录。如果 ZIP 字节变了,请提高版本号。同一插件只启用一个版本,站点同时只启用一套主题。 - 回退时启用保留的旧版本。停用当前主题可恢复默认配色。停用后可以移除旧包,重新使用时需保留原 ZIP。站点最多保留 60 个扩展版本。
完整源码示例位于仓库的 examples/extensions/word-counter 和 examples/extensions/forest-theme。