UI 视觉设计 / 系统课时
转换 React Native 样式常量
转换 React Native 样式常量
Web 端的 8px 不能直接复制为 React Native 的 padding。这里将已校验的 DTCG 颜色、尺寸和普通数值令牌转换成 TypeScript 常量,保留语义路径,并通过一个真实组件检查单位、颜色和类型是否正确。
学习目标
- 区分 DTCG 尺寸单位与 React Native 的无单位样式值。
- 编写可重复执行的脚本,生成带
as const的 TypeScript 令牌。 - 在
StyleSheet.create中验证产物,识别错误单位与未解析别名。
明确尺寸与颜色的映射
React Native 的 padding、borderRadius、fontSize、lineHeight 通常使用数字;固定尺寸表示密度无关的逻辑像素,而非设备物理像素。本例约定设计令牌中的 1 px 对应 React Native 的 1 个逻辑单位,所以 8px 输出为 8,不再乘设备像素密度。该约定须由设计与移动端共同确认。
| DTCG 类型 | 输入值 | Native 输出 | 校验重点 |
|---|---|---|---|
color |
sRGB [0.2,0.4,0.8] |
"#3366CC" |
色域、分量及 alpha |
dimension |
{"value":8,"unit":"px"} |
8 |
禁止直接输出 "8px" |
number |
0.5 |
0.5 |
用作 opacity 时限制为 0~1 |
DTCG 2025.10 的 dimension.$value 是带 value、unit 的对象。rem 虽是合法来源单位,却必须先确定基准字号再换算;此处选择遇到 rem 就停止生成,避免把 0.5rem 错当成 0.5。颜色示例只处理 sRGB,其他色域应增加明确的转换规则。

准备可转换的 DTCG 输入
在 React Native 项目根目录新建 tokens/native.json。以下只包含颜色、尺寸、数值三类令牌,所有别名已提前解析;完整项目应在上游校验引用与循环依赖,不应让移动端构建器猜测别名。
{
"color": {
"primary": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.2, 0.4, 0.8],
"hex": "#3366cc"
}
},
"onPrimary": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [1, 1, 1],
"hex": "#ffffff"
}
}
},
"spacing": {
"sm": { "$type": "dimension", "$value": { "value": 8, "unit": "px" } }
},
"radius": {
"md": { "$type": "dimension", "$value": { "value": 12, "unit": "px" } }
},
"font": {
"bodySize": { "$type": "dimension", "$value": { "value": 16, "unit": "px" } },
"bodyLineHeight": { "$type": "dimension", "$value": { "value": 24, "unit": "px" } }
},
"opacity": {
"disabled": { "$type": "number", "$value": 0.5 }
}
}分组名会原样保留为属性路径,例如 spacing.sm 变成 nativeTokens.spacing.sm。需要兼容更复杂的 DTCG 别名、模式或颜色空间时,应先用令牌处理流水线完成解析和转换,再进入这一生成步骤。
编写生成器并运行
在 scripts/build-native-tokens.mjs 写入以下 Node.js 脚本。它递归保留分组,按 $type 转值,对错误单位和不支持的令牌立即抛错,避免生成看似合法但运行时无效的样式值。
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
const source = JSON.parse(readFileSync('tokens/native.json', 'utf8'));
function convert(token, path) {
const { $type: type, $value: value } = token;
if (type === 'color') {
const rgb = value?.components;
if (value?.colorSpace !== 'srgb' || !Array.isArray(rgb) ||
rgb.length !== 3 || rgb.some(n => !Number.isFinite(n) || n < 0 || n > 1)) {
throw new Error(`${path}: invalid sRGB color`);
}
// 按 DTCG 的 0~1 sRGB 分量计算 React Native 可用的十六进制色值。
const hex = '#' + rgb.map(n => Math.round(n * 255)
.toString(16).padStart(2, '0')).join('');
if (value.hex && value.hex.toLowerCase() !== hex) {
throw new Error(`${path}: hex fallback mismatch`);
}
const alpha = value.alpha ?? 1;
if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
throw new Error(`${path}: invalid alpha`);
}
const suffix = alpha === 1 ? '' :
Math.round(alpha * 255).toString(16).padStart(2, '0');
return (hex + suffix).toUpperCase();
}
if (type === 'dimension') {
// 本项目约定 1 DTCG px 对应 1 个 Native 逻辑尺寸单位。
if (value?.unit !== 'px' || !Number.isFinite(value.value)) {
throw new Error(`${path}: expected px dimension`);
}
return value.value;
}
if (type === 'number' && Number.isFinite(value)) {
if (path.startsWith('opacity.') && (value < 0 || value > 1)) {
throw new Error(`${path}: opacity out of range`);
}
return value;
}
throw new Error(`${path}: unsupported token type ${type}`);
}
function walk(group, path = '') {
if (!group || typeof group !== 'object' || Array.isArray(group)) {
throw new Error(`${path || 'root'}: expected group`);
}
if (Object.hasOwn(group, '$value')) return convert(group, path);
const output = {};
for (const [name, child] of Object.entries(group)) {
if (name.startsWith('$')) continue; // 跳过分组元数据。
output[name] = walk(child, path ? `${path}.${name}` : name);
}
return output;
}
const values = walk(source);
mkdirSync('src/theme', { recursive: true });
writeFileSync('src/theme/tokens.native.ts',
`// Auto-generated; do not edit.\nexport const nativeTokens = ${JSON.stringify(values, null, 2)} as const;\n`);
console.log('Generated src/theme/tokens.native.ts');在项目根目录执行(需要 Node.js 20 或更新版本):
node scripts/build-native-tokens.mjs预期输出:
Generated src/theme/tokens.native.ts生成文件会包含 color.primary: "#3366CC"、spacing.sm: 8、radius.md: 12、font.bodySize: 16、font.bodyLineHeight: 24、opacity.disabled: 0.5,且带 as const。它是编译期可导入的 TypeScript 模块,不是需要在设备上读取的 JSON 资源。
在 React Native 组件中验收
在现有 TypeScript React Native 项目中将以下内容放入 App.tsx。StyleSheet.create 能检查样式属性与值的静态类型;生成器额外负责阻止语义上错误的 px 字符串进入产物。
import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { nativeTokens } from './src/theme/tokens.native';
export default function App() {
return (
<View style={styles.screen}>
<View style={styles.card}>
<Text style={styles.label}>Token 生效</Text>
</View>
</View>
);
}
const styles = StyleSheet.create({
screen: { flex: 1, justifyContent: 'center', padding: 24 },
card: {
backgroundColor: nativeTokens.color.primary,
padding: nativeTokens.spacing.sm,
borderRadius: nativeTokens.radius.md
},
label: {
color: nativeTokens.color.onPrimary,
fontSize: nativeTokens.font.bodySize,
lineHeight: nativeTokens.font.bodyLineHeight
}
});预期结果:应用中央出现蓝色卡片,内边距为 8、圆角为 12,白色文字字号为 16、行高为 24。分别在 iOS 和 Android 上检查卡片布局,并把系统字体调大再检查文字是否截断;React Native 的 Text 默认允许无障碍字体缩放,不能把字号令牌误当成固定物理像素。
定位转换失败与类型失配
- 把
spacing.sm改成{ "value": 0.5, "unit": "rem" }后重新运行,预期报错spacing.sm: expected px dimension。若团队决定按基准字号 16 换算,应显式规定0.5rem → 8,再修改构建转换逻辑。 - 将
color.primary.$value.components改成[0.2, 0.4, 2]会报color.primary: invalid sRGB color,说明越界色值没有混入产物。 - 若 TypeScript 报
padding或fontSize类型错误,先打开tokens.native.ts检查是否变成"8px"之类字符串,而不是用as any绕过检查。 - 更换品牌模式后应从对应已解析的输入重新生成,再比较 iOS、Android 的颜色与字号;不要在组件中手动覆盖一份旧常量。
转换规则保持单向:设计令牌作为输入,TypeScript 文件由脚本生成,业务组件只引用生成结果。每次变更令牌时重新构建并做类型检查,可防止平台间的尺寸单位和颜色值逐渐分叉。