UI 视觉设计 / 系统课时
校验字段约束与扩展元数据
校验字段约束与扩展元数据
这篇把 Token JSON 变成可以检查、可以安全回写的交付文件。你将按 DTCG 2025.10 核对名称、类型和值,把工具专属数据放进 $extensions,并用一段可运行的检查脚本验证字段规则和回写后的元数据保留情况。
学习目标
- 区分 Group 和 Token,识别名称、
$type、$value的合法边界。 - 用命名空间组织
$extensions,避免扩展信息污染标准字段。 - 运行基础校验,并判断跨工具回写有没有丢失未知元数据。
从可解析的 Token 文件开始
在项目目录新建 tokens.json。下面是一个完整的 DTCG 示例:spacing 组声明默认类型 dimension,两个子 Token 继承它;opacity.disabled 则显式声明 number。
{
"spacing": {
"$type": "dimension",
"$description": "界面间距",
"sm": {
"$value": { "value": 8, "unit": "px" },
"$extensions": {
"com.example.workflow": {
"source": "design",
"reviewId": "DS-204"
}
}
},
"md": {
"$value": { "value": 16, "unit": "px" }
}
},
"opacity": {
"disabled": {
"$type": "number",
"$value": 0.4
}
}
}是否为 Token 由 $value 识别:有 $value 的节点是 Token,没有的通常是 Group。注意 $type 不是按值自动猜测的;本例 spacing.sm 的有效类型来自父组。文件缺少 $value 时,原本想写的 Token 可能被解析成空组,业务侧还要核对预期 Token 清单。
校验名称、类型和值的边界
名称由 Group/Token 的对象键决定。它们不得以 $ 开头,也不得包含 {、}、.;规范保留 $root 作为特殊根 Token 名称。spacing.sm 可以表示完整路径,但不能把 "spacing.sm" 直接写成一个名称。大小写在规范中有区别,工程导出时仍应避免 sm 与 SM 同时存在。
| 检查点 | 通过示例 | 应拦截的写法 |
|---|---|---|
| 名称 | spacing、sm |
space.sm、$small |
| 类型 | dimension、number |
Dimension、无从继承的缺失类型 |
| 尺寸值 | {"value":8,"unit":"px"} |
"8px"、{"value":8,"unit":"dp"} |
| 数值 | 0.4 |
"0.4" |
| 扩展容器 | "$extensions":{...} |
"$extensions":"workflow" |
dimension 的单位只允许 px 或 rem,即使数值为 0 也必须写 unit。一般数值 Token 用 JSON 数字,不能把字符串数字当作可转换值;类型和取值必须同时成立。别名解析、循环依赖和引用目标类型还需要另行校验,单纯 JSON 语法通过不代表符合 DTCG。
为扩展数据设定保留规则
$extensions 可放在 Group 或 Token 内部,其值必须是 JSON 对象。内部按工具或团队命名空间分区,例如示例的 com.example.workflow;点号在这里合法,因为它是扩展对象的键,而不是 Group/Token 的名称。source 和 reviewId 是本课程自定义字段,并非 DTCG 标准字段。
跨工具处理要区分两种输出:重新保存含该 Token 的 DTCG 文件时,工具必须保留自己不理解的扩展数据;仅编译生成 CSS 变量时,CSS 无须承载这些编辑期元数据。不要把判断颜色、单位或 Token 引用所必需的信息只放进 $extensions,否则不识别扩展的工具无法正确解释值。

约定验收案例:工具 A 写入 com.example.workflow.reviewId = DS-204,工具 B 修改 spacing.sm 的尺寸后回写 DTCG JSON,reviewId 仍必须是 DS-204。若工具 B 把未知命名空间过滤掉,即使最终 CSS 数值正确,也不应视为无损回写。
运行基础检查与回写验收
在同一目录新建 check-tokens.mjs,用 Node.js 20 或更高版本执行。此脚本针对上例的普通 Group、dimension 与 number 做快速检查;它不是覆盖所有类型、$root、别名和组继承规则的完整规范验证器。
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
const source = JSON.parse(readFileSync("tokens.json", "utf8"));
const isObject = v => v !== null && typeof v === "object" && !Array.isArray(v);
const groupFields = new Set(["$type", "$description", "$extensions", "$deprecated", "$extends"]);
const tokenFields = new Set(["$type", "$value", "$description", "$extensions", "$deprecated"]);
let count = 0;
function checkToken(token, inheritedType, path) {
for (const key of Object.keys(token)) {
assert.ok(tokenFields.has(key), `${path}: 未知 Token 字段 ${key}`);
}
const type = token.$type ?? inheritedType;
const value = token.$value;
// 演示范围只包含两个具体类型,避免把局部校验误当完整规范。
if (type === "dimension") {
assert.ok(isObject(value) && typeof value.value === "number" &&
["px", "rem"].includes(value.unit), `${path}: dimension 值非法`);
} else {
assert.equal(type, "number", `${path}: 类型缺失或超出示例范围`);
assert.equal(typeof value, "number", `${path}: number 值非法`);
}
assert.ok(token.$extensions === undefined || isObject(token.$extensions),
`${path}: $extensions 必须是对象`);
count++;
}
function visit(group, inheritedType, prefix = "") {
assert.ok(isObject(group), `${prefix}: Group 必须是对象`);
const type = group.$type ?? inheritedType;
assert.ok(group.$extensions === undefined || isObject(group.$extensions),
`${prefix}: Group 扩展必须是对象`);
for (const [name, item] of Object.entries(group)) {
if (name.startsWith("$")) {
assert.ok(groupFields.has(name), `${prefix}: 未知 Group 字段 ${name}`);
continue;
}
assert.ok(!/[{}.]/.test(name), `非法名称: ${name}`);
assert.ok(isObject(item), `${name}: 节点必须是对象`);
const path = prefix ? `${prefix}.${name}` : name;
// 有 $value 才按 Token 校验,否则继续深入 Group。
if (Object.hasOwn(item, "$value")) checkToken(item, type, path);
else visit(item, type, path);
}
}
visit(source);
if (process.argv[2]) {
const saved = JSON.parse(readFileSync(process.argv[2], "utf8"));
assert.deepEqual(saved.spacing.sm.$extensions, source.spacing.sm.$extensions);
}
console.log(`基础校验通过:${count} 个 Token${process.argv[2] ? ";扩展字段保留" : ""}`);运行命令:
node check-tokens.mjs预期输出:
基础校验通过:3 个 Token把 spacing.sm.$value.unit 改成 dp,再次运行会触发断言失败。完成实际工具回写并获得 tokens-saved.json 后,运行 node check-tokens.mjs tokens-saved.json:若扩展一致,会追加“扩展字段保留”;若缺失或被改写,断言失败。该测试只比较本例的一个扩展路径,真实项目应遍历所有 Group 和 Token 的未知扩展。
正式发布前,再使用 DTCG 2025.10 格式规范 与 对应 JSON Schema 做全类型结构检查,并补上引用存在性、循环引用与跨文件解析检查;Schema 校验不能替代真实工具回写测试。