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 类型。
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 文件名。
从项目根目录执行:
node tools/build-android-tokens.mjs预期输出:
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,因此不会因主题切换改变间距与字号。

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 模块本身可构建):
./gradlew :app:assembleDebug预期输出中应包含:
BUILD SUCCESSFUL在设备或模拟器上进行两次检查:先关闭系统深色主题,确认使用 #2563EB 主色与 #FFFFFF 页面底色;再开启深色主题,确认变为 #93C5FD 和 #111827。Android 10 及以上可使用系统深色主题设置;实际能否切换还取决于应用是否锁定 uiMode 或自行接管主题。
如果编译报告资源重名,先查同一限定目录里的同名 <color> 或 <dimen>;如果切换无效,确认清单引用的是 AppTheme、未被 Activity 主题覆盖,且存在 values-night;如果尺寸显示异常,检查是否把间距写成 px 或把字号误写成 dp。正式交付时,应把生成 XML 纳入版本对比或 CI,保证重新生成后资源名和单位没有意外变化。