设置 UI v1
行为与约束
settings 在根引用包内 JSON 文件。缺省且无 option 时为 Empty;缺省且有 option 时为 AutoGenerated;有效路径为 Authored;无效路径/文档拒绝整个候选,不退回 AutoGenerated。来源与 canonical UI hash 单独记录,UI hash 不是 manifest hash。
根 schemaVersion=1、defaultLocale、pages 必需,translations 缺省空字典,hiddenOptions 缺省空数组。Page 的 id/title/groups 必需,Group 的 id/controls 必需、title 可省略;两者 order 缺省 0、visibleWhen 缺省空数组。页非空时至少一个 group,group 至少一个 control。数组保留作者顺序,order 范围为 −1000000~1000000。
Control 必需 id/option;widget 缺省 auto,也支持 toggle/choice/slider。label/description/unit/format 是展示文本;advanced/developerOnly 缺省 false;visibleWhen/enabledWhen 缺省空数组。slider 的 step 必须正数且匹配 option 类型,min/max 成对且仅能缩小硬范围。choice 的 values 必需,与 allowed 集合精确相等且顺序控制显示;每项只有 value/label,label 必需。toggle 绑定 boolean,choice 绑定 string/integer,slider 绑定有范围的 integer/number。auto 不接受专属 widget 字段。
每个 canonical option 必须恰好由一个 control 或 hiddenOptions 覆盖;hidden 项只有 option/reason 且两者必需。漏项、重复或同时显示/隐藏以 P9UI201 拒绝。UI 不重声明 option type/default/allowed/硬范围/impact。
UI condition 是 option 加 equals、notEquals、in 三者之一;同数组 AND,in 非空且值唯一,同类型并满足 option 范围。page/group 条件向下影响,控件可分别可见/启用;受控 option → 依赖 option 的 DAG 不允许自依赖或环(P9UI203)。不要混用 Manifest 的 oneOf 条件。
translations 为 locale → key:text 字典。locale 不区分大小写,key 区分大小写;有翻译表时必须包含 defaultLocale。解析按当前 locale → defaultLocale → 调用方 fallback → key。缺单个 key 正常回退。
路径上限 256 字符、包内 .json;文档最多 1 MiB。页 32、每页组 64、文档控件 512、每控件 choice 256、每 owner 条件 16、条件值 256、文档条件 4096、hidden 512、locale 32、每 locale 翻译 2048、文档翻译 8192。local ID 最多 64 字符,短文本 256,description/translation/reason 4096,locale 长度 1~35。各层拒绝重复键和未知属性。下列字段从实际 Loader 白名单投影,不伪装成上游官方 UI JSON Schema。
root
| 字段 | 归属 |
|---|---|
schemaVersion | 已复核 Loader 白名单;行为见上文 |
defaultLocale | 已复核 Loader 白名单;行为见上文 |
translations | 已复核 Loader 白名单;行为见上文 |
pages | 已复核 Loader 白名单;行为见上文 |
hiddenOptions | 已复核 Loader 白名单;行为见上文 |
page
| 字段 | 归属 |
|---|---|
id | 已复核 Loader 白名单;行为见上文 |
title | 已复核 Loader 白名单;行为见上文 |
order | 已复核 Loader 白名单;行为见上文 |
groups | 已复核 Loader 白名单;行为见上文 |
visibleWhen | 已复核 Loader 白名单;行为见上文 |
group
| 字段 | 归属 |
|---|---|
id | 已复核 Loader 白名单;行为见上文 |
title | 已复核 Loader 白名单;行为见上文 |
order | 已复核 Loader 白名单;行为见上文 |
controls | 已复核 Loader 白名单;行为见上文 |
visibleWhen | 已复核 Loader 白名单;行为见上文 |
control
| 字段 | 归属 |
|---|---|
id | 已复核 Loader 白名单;行为见上文 |
option | 已复核 Loader 白名单;行为见上文 |
widget | 已复核 Loader 白名单;行为见上文 |
label | 已复核 Loader 白名单;行为见上文 |
description | 已复核 Loader 白名单;行为见上文 |
unit | 已复核 Loader 白名单;行为见上文 |
format | 已复核 Loader 白名单;行为见上文 |
step | 已复核 Loader 白名单;行为见上文 |
min | 已复核 Loader 白名单;行为见上文 |
max | 已复核 Loader 白名单;行为见上文 |
advanced | 已复核 Loader 白名单;行为见上文 |
developerOnly | 已复核 Loader 白名单;行为见上文 |
values | 已复核 Loader 白名单;行为见上文 |
visibleWhen | 已复核 Loader 白名单;行为见上文 |
enabledWhen | 已复核 Loader 白名单;行为见上文 |
choice
| 字段 | 归属 |
|---|---|
value | 已复核 Loader 白名单;行为见上文 |
label | 已复核 Loader 白名单;行为见上文 |
condition
| 字段 | 归属 |
|---|---|
option | 已复核 Loader 白名单;行为见上文 |
equals | 已复核 Loader 白名单;行为见上文 |
notEquals | 已复核 Loader 白名单;行为见上文 |
in | 已复核 Loader 白名单;行为见上文 |
hiddenOption
| 字段 | 归属 |
|---|---|
option | 已复核 Loader 白名单;行为见上文 |
reason | 已复核 Loader 白名单;行为见上文 |
完整示例
来源与机器记录
字段归属清单 · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·