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 常量的数据流

准备可转换的 DTCG 输入

在 React Native 项目根目录新建 tokens/native.json。以下只包含颜色、尺寸、数值三类令牌,所有别名已提前解析;完整项目应在上游校验引用与循环依赖,不应让移动端构建器猜测别名。

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 转值,对错误单位和不支持的令牌立即抛错,避免生成看似合法但运行时无效的样式值。

js
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 或更新版本):

bash
node scripts/build-native-tokens.mjs

预期输出:

text
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 字符串进入产物。

tsx
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 文件由脚本生成,业务组件只引用生成结果。每次变更令牌时重新构建并做类型检查,可防止平台间的尺寸单位和颜色值逐渐分叉。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

转换 React Native 样式常量

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通