layout —— 包结构与 manifest

读者:做工具的用户,和替他干活的 AI。两者读同一份。

它是什么

一个工具就是一个目录。目录里有一份 manifest.json(身份与元数据)、若干个组件(xWidget/)、可选的页面(page/)和资产。发布时这个目录被整个封成一个 .xbundle:归档里的文件集合 = manifest.files ∪ manifest.json,一个字节都不多。所以「目录里有什么」= 「用户设备上会下载到什么」。

目录布局与文件后缀都是硬约定:客户端按后缀决定用哪个引擎解析,按固定路径去找 page/router.json、xWidget/*.xwidget。放错位置的文件不会报错,只是永远不被加载。

manifest.json 是这个包对平台说的全部话:它叫什么、归哪一类、要连哪些域名、要不要用户的密钥、最低要什么引擎。安装面板、商店组件、网络守卫都只读这一份;写错的后果通常不是崩溃,而是装得上、跑得起来、但某件事永远不发生(例如 host 没声明 → 请求被静默拦掉)。

最小可用示例

numable init 生成的包就长这样,可直接复制后改字段:

{
  "id": "01KZ58G6AXEKVWCQFYNY9S6EEM",
  "version": 1,
  "title": "我的工具",
  "lang": "zh-CN",
  "category": "dashboard",
  "subtitle": "从一个时间组件开始",
  "domain": "01KZ58G6AXEKVWCQFYNY9S6EEM",
  "minEngine": "1.0.0",
  "network": [],
  "i18n": {
    "en-US": { "title": "My Tool", "subtitle": "Start from a clock card" }
  }
}

它对应的目录:

<包目录>/
  manifest.json              身份与元数据(必需)
  logo.png                   512×512 满幅方图(发布必需)
  banner.xbanner             工具页顶部横幅(可选)
  page/
    router.json              页面路由表(有页面才需要)
    html/<route>/index.html  H5 页
    xpage/<name>.xpage       XPage 页(声明式,零 WebView)
    form/<name>.xform        表单页
    rc/<name>.rcn            页面域 RCN
    flow/<name>.af|.df       页面域流:.af 交互 / .df 取数
    assets/                  页面用的图片与文本资产
  xWidget/
    <名>.xwidget             组件声明,一组件一文件
    rc/<名>.rcn              组件的画法
    flow/<名>.df             组件的取数流
    assets/                  组件用的资产
  .numable/                  本机 sidecar:夹具与渲染产物,永不进包
  .gitignore                 init 已写好(.numable/ .studio/ build/)

怎么写

后缀硬约定

组件域 xWidget/ 与页面域 page/ 各有一套 rc/ + flow/,物理隔离;两边的 @[file://…] 基准也不同(见 numable docs xwidget)。

manifest 字段

category 的 11 个枚举值

finance 财经 · developer 开发者 · productivity 效率 · life 生活 · health 健康 · system 系统 · tech 科技 · news 资讯 · tools 效率 · dashboard 看板 · testing 测试。

平台自带这 11 个 key 的中英词表,写枚举 key 就自动双语。tools 与 productivity 显示同一个名字,新包用 productivity。写枚举以外的自由文本也能装,但你得自己在 i18n 里给它英文覆盖,否则英文环境显示中文。

credentials(用户自带密钥)

"credentials": [
  {
    "id": "gh",
    "type": "token",
    "required": false,
    "hosts": ["api.github.com"],
    "label": "GitHub 访问令牌",
    "i18n": { "en-US": { "label": "GitHub token" } },
    "help": "https://github.com/settings/tokens"
  }
]

密钥本身永远不进包、不进 params、不进 data.*。本机测试把值放 .numable/params/_credentials.json({"gh":"ghp_…"}),它在 sidecar 里,不进包也不进版本控制。接入细节见 numable docs df。

i18n(元数据 B 表)

"lang": "zh-CN",
"title": "GitHub 示例",
"subtitle": "某个用户最近的公开动态",
"i18n": { "en-US": { "title": "GitHub Sample", "subtitle": "A user's recent public activity" } }

裸字段就是 lang 那一门,译文旁挂在 i18n.<locale> 下;可覆盖的字段只有 title / subtitle / category / description。这里的空串表示「缺译文」,平台会继续往下兜底 —— 和内容文案表(A 表)里空串表示「刻意留空」正好相反。完整规则见 numable docs i18n。

不要写的字段

⚠️ 第二行那些字段没有闸:check 一声不吭,克隆一个现成包时会连它们一起带过来。新建包后先把 manifest 通读一遍,见到就删。

legacyId 也属于这一类,但它有一个小用处:check 拿它当报错行首的包名前缀。新包不必写,已经有的留着也无害。

注释怎么写

JSON 没有注释语法,包里统一用 _note 键:

{
  "id": "hi",
  "type": "txt",
  "_note": "这行是标题,字号跟着卡宽走",
  "text": "${@i18n.title}",
  "x": "12pt", "y": "12pt", "w": "-1", "h": "-1",
  "fontSize": "16pt", "textColor": "#1A1A1A|#FFFFFF"
}

• 键名必须以 _note 开头(_note / _noteWhy / _note2 都行)。check 的各条闸都按这个前缀跳过注释,别的下划线名字不保证被跳过 —— 在注释里举例写个 ${@i18n.x} 或 abs::(),会被当成真的引用报出来。
• 注释是某个对象上的一个字段,不能自己单独站着。往 cells / react / children 数组里塞一个 {"_note": "…"} 会让整个组件渲染失败(那是个没有 type 的 cell),check G7c 拦。

资产约定

• logo.png:包根,512×512 正方形,满幅、自己不烤圆角。宿主统一按 边长 × 0.2237 裁圆角;图自己先圆一次,四角会出现透明缺口或双重圆角。
• 总量上限 3MB(源目录全部文件之和);单个文件超过 256KB 会出提示 —— 流越大每次取数越慢,拆成几条流或把重复展开的表达式改成查表。图片优先用 RCN 画,或用包内 .uri 文本资产。
• 别往包目录塞不发布的东西:夹具、截图、笔记一律放 .numable/(. 开头的名字一律被跳过,不会打进包),或放到包目录之外。

没有 logo.png 会怎样

不报错,也不是空白:平台画一个首字母占位图标 —— 一个纯色圆角方块加一个字。

• 字 = title 去掉首尾空格后的第一个字符,英文转大写(中文包就是第一个汉字);title 为空时是 #。
• 底色 = 按 manifest.id 从 8 色板里定死取一个(把 id 的字符码求和对 8 取模),所以同一个包每次都是同一种颜色,换不了。
• 这个占位是自用包的正常形态;check --profile publish 会用 G11 拦住没有 logo.png 的发布包。

要控制第一个字长什么样,就改 title 的首字;要别的图,只能自己出 logo.png。

banner.xbanner

包根一个单文件,工具页顶部那张 16:9 的横幅。不写就用平台的默认模板(把包名、分类、首字母图标摆上去);写了就整块归你画。它就是一个组件的 canvas:source(画什么)、depends(取什么数)、refresh(多久重取一次)三个键与 .xwidget 里的写法完全一样,只是尺寸由 scene 给、没有 layout。

{
  "version": 2,
  "id": "banner",
  "ratio": "16:9",
  "theme": "auto",
  "scene": { "width": 338, "height": 190, "corner": 18 },
  "params": {},
  "canvas": {
    "source": {
      "cells": [
        { "id": "bg", "type": "layer", "x": "0pt", "y": "0pt",
          "w": "{parent.w}", "h": "{parent.h}", "bgColor": "#884532|#884532" },
        { "id": "t", "type": "txt", "text": "${@i18n.t}",
          "x": "24pt", "y": "114pt", "w": "-1", "h": "-1",
          "fontSize": "20pt", "textColor": "#FFFFFF|#FFFFFF",
          "typeface": "System-Bold", "maxLines": "1" },
        { "id": "s", "type": "txt", "text": "${@i18n.s}",
          "x": "24pt", "y": "{t.b}+6pt", "w": "-1", "h": "-1",
          "fontSize": "12pt", "textColor": "#B8FFFFFF|#B8FFFFFF", "maxLines": "1" }
      ],
      "i18n": {
        "zh-CN": { "t": "我的工具", "s": "一句话说明" },
        "en-US": { "t": "My source", "s": "One line about it" }
      }
    },
    "depends": []
  }
}

要取数的横幅(比如海报上放一条行情)把画布与取数流都放进 xWidget/,在横幅里引用它们;工具页会按 refresh 定时重取:

{
  "canvas": {
    "source": "@[file://xWidget/rc/banner.rcn]",
    "depends": [{ "flow": "@[file://xWidget/flow/quote.df]", "params": { "code": "${code}" } }],
    "refresh": { "interval": ["600"] }
  }
}

五件要记住的事:

1. 必须写 scene —— 横幅没有 layout 档位可依,尺寸只能自己声明,width / height 必须为正,少了这一块整张横幅渲不出来。惯用值就是上面那组 338 × 190(16:9)加 corner: 18。
2. 引用写包根路径。横幅在包根,@[file://…] 从包根算起,要写 xWidget/rc/…、xWidget/flow/…;.xwidget 里从 xWidget/ 算起,别照抄过来。
3. 拿不到包的元数据。${meta.title} 之类只有默认模板才有,自定义横幅里求值为空。要显示包名就自己写进 source 的 i18n,像上面那样。
4. params 是固定值。取数流里写 ${键名} 取到的就是它;横幅只有一份,用户不能像组件那样在仪表盘上改。不取数就留空对象,depends 留空数组、不写 refresh。
5. 双语靠自觉:check 的 i18n 闸(G8)不扫 .xbanner。横幅上的字漏了英文没人会告诉你,发布前自己切语言看一眼。

不要写顶层 rcn / flow:App 只读 canvas,那种写法会被当作没有横幅、换成默认模板,check 用 G43 拦下。

规则(违反 = 返工)

出错怎么办

相关

numable docs xwidget · numable docs i18n · numable docs lint-codes