Theme Authoring

制作主题包

主题包是扩展名为 .wjnskin 的标准 ZIP，也可以把同结构的文件夹放进主程序同级的 themes/ 作为开发主题。

目录结构

my-theme/
  meta.json
  style.css
  host/*.css          # 可选，宿主界面模块
  node/*.css          # 可选，接线盘节点模块
  native_fx/*.css     # 可选，Native Fx 模块
  assets/             # 图片与字体

旧版只含根目录 style.css 的主题包仍然可用。

meta.json

必需字段：formatVersion、themeApiVersion、id、name、version、author、description、homepage、kind、namespaces。

{
  "formatVersion": 1,
  "themeApiVersion": 1,
  "id": "org.example.my-theme",
  "name": "My Theme",
  "version": "1.0.0",
  "author": "Your name",
  "description": "Describe the theme and its visual intent.",
  "homepage": "",
  "kind": "full",
  "namespaces": [
    "--wjn-theme-global-",
    "--wjn-theme-patchbay-"
  ]
}

• id 使用小写反向域名加短横线，长度 3–128。
• version 为 MAJOR.MINOR.PATCH。
• kind 只能为 full 或 fragment。
• namespaces 列出主题涉及的模块前缀，不能为空或重复。

编写 CSS

• 每个 CSS 文件只写一个 :root { ... } 块。
• 变量名应属于注册过的 --wjn-theme-<模块>-<角色>；未知键会警告且不参与绘制。
• 文件使用 UTF-8；只允许注释、变量声明和 var(...)。
• 不支持选择器、@ 规则或嵌套块。
• 图片和字体放在 assets/，用 url("assets/文件名") 引用。
• 图片支持 PNG/JPEG/WebP，字体支持 TTF/OTF，不支持 SVG。
• 加载顺序为根目录 style.css，再按路径排序合并模块 CSS；重复变量以后声明为准并给出行号诊断。

Token 的类型、默认值和继承关系见主仓库的 主题数据契约 和 Theme-v1-Registry.json。

从模板开始

1. 复制主仓库的 themes/template 到工作目录。
2. 修改 meta.json 的 id、name、author、description 和 version。
3. 修改 style.css，或 host/、node/、native_fx/ 中对应模块的 CSS。
4. 在模板目录运行 python build_theme.py，生成的 <id>.wjnskin 位于上一级 themes/。
5. 在「主题管理」中导入、预览、应用。

希望从继承关系开始而不是完整默认值时，可以使用 themes/template-simple-dev。

开发主题

• 把主题文件夹直接放进主程序同级的 themes/。
• 主题菜单显示为 名称 (Dev)。
• 修改 CSS 后选择「刷新当前 Dev 主题」重新读取。
• 开发文件夹里的 README、构建脚本等不会进入主题包。
• 同一 ID 的 Dev 文件夹优先于 .wjnskin 包。

校验与限制

导入前会完整校验主题包，失败不会替换正在使用的主题；诊断显示在主题管理页。

• 包文件最大 32 MiB，ZIP 条目最多 512，解压总量最多 128 MiB。
• meta.json 最大 64 KiB，单个 CSS 及合并后的 CSS 最大 1 MiB。
• 图片单文件最大 16 MiB，解码后最大 32 Mpix；字体单文件最大 16 MiB。
• 主题包内不能有 DLL、脚本或远程资源，也不允许 SVG、动画或多帧图片。
• 资源路径只能是 assets/ 下的相对路径。

参考

• 主题自定义（主仓库）
• 主题数据契约 v1
• 主题注册表