UI 视觉设计 / 系统课时

生成 Android 的主题资源文件

生成 Android 的主题资源文件

把设计令牌转成 Android View 工程可直接引用的颜色、尺寸与主题 XML,并为深色模式提供同名资源覆盖。完成后,你能用资源编译检查命名和单位,再通过明暗模式切换确认主题资源是否正确生效。

学习目标

  • 把颜色、间距和字号映射为正确的 Android 资源名与单位。
  • 使用可运行的 Node.js 脚本生成默认与夜间主题文件。
  • 区分夜间资源匹配和构建变体的资源覆盖规则,并完成验证。

确定名称与单位契约

示例面向 Android View/XML 项目,要求 minSdk >= 21、模块名为 app,构建脚本使用 Node.js 18 或更高版本。资源文件输出到 app/src/main/res/;如果项目已经采用 AppCompat 或 Material Components,主题父类应沿用现有依赖,本例的系统 Theme.Material 仅用于独立演示。

设计输入 Android 资源名 默认值 夜间值或单位
交互主色 ds_action_primary #2563EB #93C5FD
页面底色 ds_surface #FFFFFF #111827
卡片内边距 16px ds_card_padding 16dp 不随主题改变
正文字号 14px ds_body_text_size 14sp 随系统字体缩放

资源名使用小写字母、数字和下划线,且以字母开头,例如 ds_action_primary。本例约定 DTCG 的逻辑 px 数值在 Android 端按 1:1 映射:布局间距使用 dp,字号使用 sp,不能输出成设备物理像素 px。颜色采用 sRGB 不透明值;含透明度时,Android XML 通常使用 #AARRGGBB,需另外处理 alpha。

编写资源生成脚本

在 Android 项目根目录创建 tools/build-android-tokens.mjs。为方便独立跟做,示例把具有 DTCG $type、$value 结构的已确定令牌放在脚本内;实际接入时,应改为读取经过模式选择、别名解析与校验的令牌文件。脚本只处理这里列出的 sRGB 不透明颜色和 px 尺寸,不宣称覆盖所有 DTCG 类型。

js
import { mkdir, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';

function color(hex) {
  if (!/^#[0-9A-Fa-f]{6}$/.test(hex)) throw new Error(`无效颜色: ${hex}`);
  return {
    $type: 'color',
    $value: {
      colorSpace: 'srgb',
      components: [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16) / 255),
      hex
    }
  };
}

const dimension = value => ({
  $type: 'dimension',
  $value: { value, unit: 'px' }
});

const tokens = {
  light: { ds_action_primary: color('#2563EB'), ds_surface: color('#FFFFFF') },
  night: { ds_action_primary: color('#93C5FD'), ds_surface: color('#111827') },
  size: { ds_card_padding: dimension(16), ds_body_text_size: dimension(14) }
};

function xml(lines) {
  return [
    '<?xml version="1.0" encoding="utf-8"?>',
    '<resources>',
    ...lines.map(line => `  ${line}`),
    '</resources>',
    ''
  ].join('\n');
}

function colors(mode) {
  return xml(Object.entries(tokens[mode]).map(([name, token]) => {
    if (token.$type !== 'color' || token.$value.colorSpace !== 'srgb') {
      throw new Error(`颜色类型错误: ${name}`);
    }
    return `<color name="${name}">${token.$value.hex}</color>`;
  }));
}

function dimens() {
  // 设计逻辑 px 依据用途分别映射到 dp 与 sp。
  const unit = { ds_card_padding: 'dp', ds_body_text_size: 'sp' };
  return xml(Object.entries(tokens.size).map(([name, token]) => {
    if (token.$type !== 'dimension' || token.$value.unit !== 'px' || !unit[name]) {
      throw new Error(`尺寸类型或单位错误: ${name}`);
    }
    return `<dimen name="${name}">${token.$value.value}${unit[name]}</dimen>`;
  }));
}

function theme(mode) {
  const parent = mode === 'night'
    ? '@android:style/Theme.Material.NoActionBar'
    : '@android:style/Theme.Material.Light.NoActionBar';
  return xml([
    `<style name="AppTheme" parent="${parent}">`,
    '  <item name="android:colorAccent">@color/ds_action_primary</item>',
    '  <item name="android:windowBackground">@color/ds_surface</item>',
    '</style>'
  ]);
}

// 两个限定目录使用相同的资源名,交给 Android 按配置选择。
const files = [
  ['values/colors.xml', colors('light')],
  ['values-night/colors.xml', colors('night')],
  ['values/dimens.xml', dimens()],
  ['values/themes.xml', theme('light')],
  ['values-night/themes.xml', theme('night')]
];

for (const [relative, content] of files) {
  const output = join('app/src/main/res', relative);
  await mkdir(dirname(output), { recursive: true });
  await writeFile(output, content, 'utf8');
  console.log(`wrote ${relative}`);
}

预期结果是生成五个合法的资源 XML。脚本会覆盖上述同名文件;在已有项目中应先确认它们没有手写内容,正式接入可改用独立的 ds_colors.xml、ds_dimens.xml 和 ds_themes.xml 文件名。

从项目根目录执行:

bash
node tools/build-android-tokens.mjs

预期输出:

text
wrote values/colors.xml
wrote values-night/colors.xml
wrote values/dimens.xml
wrote values/themes.xml
wrote values-night/themes.xml

理解主题引用与覆盖路径

生成后,values/colors.xml 中的 ds_action_primary 为 #2563EB,values-night/colors.xml 中同名资源为 #93C5FD;两处都被 AppTheme 的 android:colorAccent 引用。values/dimens.xml 只生成一次,包含 16dp 和 14sp,因此不会因主题切换改变间距与字号。

设计令牌输出 Android 默认和夜间资源的路径及覆盖关系

values/themes.xml 使用系统浅色父主题,values-night/themes.xml 则使用深色父主题;仅替换颜色 XML 而继续继承浅色父主题,其他系统控件的文本与背景可能仍保持浅色样式。AndroidManifest.xml 中现有的 <application> 节点需设置 android:theme="@style/AppTheme"(若 Activity 有独立主题,也要检查其覆盖)。

要区分两种覆盖:values-night 是运行时按 uiMode 选择的资源限定符,同名资源出现在 values 与 values-night 是合法的;构建变体则在资源合并时按“变体源集 > 构建类型 > 产品风味 > main > 依赖库”的优先级处理同限定符资源。反过来,在同一个 values 目录的两个 XML 中重复声明 ds_surface,通常会导致重复资源错误。

编译与设备核对

先运行 Android 项目已有的 Gradle Wrapper,确认资源文件可编译(需已安装对应 Android SDK,且 app 模块本身可构建):

bash
./gradlew :app:assembleDebug

预期输出中应包含:

text
BUILD SUCCESSFUL

在设备或模拟器上进行两次检查:先关闭系统深色主题,确认使用 #2563EB 主色与 #FFFFFF 页面底色;再开启深色主题,确认变为 #93C5FD 和 #111827。Android 10 及以上可使用系统深色主题设置;实际能否切换还取决于应用是否锁定 uiMode 或自行接管主题。

如果编译报告资源重名,先查同一限定目录里的同名 <color> 或 <dimen>;如果切换无效,确认清单引用的是 AppTheme、未被 Activity 主题覆盖,且存在 values-night;如果尺寸显示异常,检查是否把间距写成 px 或把字号误写成 dp。正式交付时,应把生成 XML 纳入版本对比或 CI,保证重新生成后资源名和单位没有意外变化。

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

目录与阅读设置

阅读设置

17

记录一个想法

生成 Android 的主题资源文件

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

登录哪都通