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

5.4 KiB
Raw Blame History

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
  1. 用站点超级管理员账号上传。后台显示校验错误、包类型、版本和 SHA-256。主题上传后可先查看浅色与深色色卡。
  2. 启用插件后,以普通账户打开「扩展工具」并试用。启用主题后,刷新首页并在工作台切换浅色和深色检查文字、按钮与背景。
  3. 更新包时增加 version。已安装的同一 type/id/version 再上传同一个 ZIP 会返回原记录。如果 ZIP 字节变了,请提高版本号。同一插件只启用一个版本,站点同时只启用一套主题。
  4. 回退时启用保留的旧版本。停用当前主题可恢复默认配色。停用后可以移除旧包,重新使用时需保留原 ZIP。站点最多保留 60 个扩展版本。

完整源码示例位于仓库的 examples/extensions/word-counter 和 examples/extensions/forest-theme。