五个 target

本頁內容尚未翻譯。

每个 target 实现 CodegenTarget 接口（{ name, outDir, generate(input): GeneratedFile[] }），由管线依次调用。

共享的暗色产物构造模式

四个平台 target 用同一套模式把 tokenSet.dark（Map<path, value>）转成 ResolvedToken[]：

const darkTokens = [...tokenSet.dark.entries()]
  .map(([path, value]) => {
    const base = tokenSet.byPath.get(path)
    return {
      path,
      type: base?.type ?? ('color' as const),   // 明色同名键取类型，否则兜底 color
      value,
      description: base?.description,
    }
  })
  .sort((a, b) => a.path.localeCompare(b.path))

然后按 path 排序走同一棵 emit 树。明色产物带 description 注释；spread（扩展量）在所有端都被忽略并注释说明。

android.ts —— Kotlin + Jetpack Compose

产物：dist/android/top/lhgb/ui/tokens/LhTokens.kt + LhDarkTokens.kt

常量：PACKAGE = 'top.lhgb.ui.tokens'（家族反域名规范，总纲 D20）

`formatKotlin(path, token): FormatResult`

返回 { literal, features }——features 是用到的运行时类型集合，决定 import 清单：

类型	字面量	features
color	`ComposeColor(0xAARRGGBB)`	`color`
dimension（px）	`${d.value}.${usesSp(path) ? 'sp' : 'dp'}`	`dimension`
dimension（%）	`0.50f // 50%（分数，由容器尺寸换算）`（`(v/100).toFixed(3)` 后去掉一个尾零）	—
duration	`200 // 200ms（毫秒）`	—
cubicBezier	`CubicBezierEasing(0.4f, 0f, 0.2f, 1f)`	`bezier`
shadow	`Shadow(color = ..., offset = Offset(xf, yf), blurRadius = bf)`	`color`, `shadow`
number / string	原样 / `JSON.stringify`	—

`emitTree(lines, group, indent, features)`

递归输出嵌套 object PascalCase { ... }，成员 val name = literal，description 作为行尾注释。features 在遍历中累积。

`buildKotlinBody(tokenSet, rootName, features)` / `buildDarkKotlinBody(tokenSet, features)`

明色根 object 名由参数传入（LhTokens），暗色根固定 LhDarkTokens。

`importsFor(features): string[]`

import 清单由实际用到的特性决定，没用到就不导入：

feature	import
`color`	`androidx.compose.ui.graphics.Color as ComposeColor`
`dimension`	`androidx.compose.ui.unit.dp` + `.sp`
`shadow`	`androidx.compose.ui.graphics.Shadow` + `androidx.compose.ui.geometry.Offset`
`bezier`	`androidx.compose.animation.core.CubicBezierEasing`

`renderKotlinFile(body, version, features): string`

把头部「请勿手改」横幅、按 features 生成的 import 块与 body 拼成完整 .kt 文件。

ios.ts —— Swift + SwiftUI

产物：dist/ios/Sources/LhUITokens/LhTokens.swift + LhDarkTokens.swift，存在 shadow 令牌时额外生成 LhShadow.swift

`formatSwift(token): string`

类型	字面量
color（a=1）	`SwiftUI.Color(red: 0.169, green: 0.298, blue: 0.486)`
color（a<1）	同上 + `.opacity(0.4)`
dimension	`CGFloat(40)`；`%` 输出分数 + 注释
duration	`0.200 // 0.2s（秒）`——SwiftUI 动画以秒为单位，构建期换算（毫秒 ÷ 1000，保留 3 位小数）
cubicBezier	`(x1: 0.4, y1: 0, x2: 0.2, y2: 1) // 贝塞尔控制点，端自行构造 easing`
shadow	`LhShadow(color:opacity:radius:x:y:)`

`swiftMemberName(name): string`

成员名与 Swift 关键字同形时加反引号（如 `default`），否则产物无法编译。

`buildSwiftBody(tokenSet, rootName): string` / `buildDarkSwiftBody(tokenSet): string`

拼 public enum 根结构：明色根名由参数传入（LhTokens），暗色根固定 LhDarkTokens，内部都靠 emitTree 递归填充。文件头横幅在 iosTarget.generate 里直接拼。

`emitTree(lines, group, indent)`

Swift 的无实例命名空间惯用法：嵌套 public enum PascalCase，成员 public static let name = ...。

harmony.ts —— 鸿蒙 ArkTS + ArkUI

产物：dist/harmony/tokens/LhTokens.ets + LhDarkTokens.ets，存在 shadow 令牌时额外生成 LhShadow.ets

`formatEts(token): string`

类型	字面量
color	`'#FF2B4C7C'`（ArkUI 接受 `#AARRGGBB` 字符串，走 `toArgbHash`）
dimension	纯 `vp` 数值；`%` 输出分数 + 注释
duration	`200 // 200ms（毫秒）`
cubicBezier	`[0.4, 0, 0.2, 1] // 组件侧以 curves.cubicBezierCurve 消费`
shadow	`{ color: '#...', radius: 8, offsetX: 0, offsetY: 2 }`

`typeAnnotation(token): string`

唯一带类型注解的平台（ArkTS 是强类型）：

类型	注解
color	`ResourceColor`
dimension	`Dimension \| number`
duration / number	`number`
shadow	`LhShadow`
cubicBezier	`number[]`
string	`string`

`emitTree(lines, group, indent)`

根 export class，嵌套类不带 export（ArkTS 类体内不允许 export 声明），成员 static readonly name: T = literal。

`buildEtsBody(tokenSet, rootName): string` / `buildDarkEtsBody(tokenSet): string`

拼 export class 根结构：明色根名由参数传入（LhTokens），暗色根固定 LhDarkTokens，内部都靠 emitTree 递归填充。文件头横幅在 harmonyTarget.generate 里直接拼。

windows.ts —— Windows C# + WinUI 3

产物：dist/windows/Tokens/LhTokens.cs + LhDarkTokens.cs，存在 shadow 令牌时额外生成 LhShadow.cs，存在贝塞尔令牌时额外生成 LhEasing.cs

命名空间 Top.Lhgb.Ui.Tokens（反域名，总纲 D20）。

`toCsColor(c): string`

颜色转 WinUI 工厂调用：Windows.UI.Color.FromArgb(0xFF, 0x2B, 0x4C, 0x7C)。

`doubleLiteral(value): string`

整数补 .0 后缀（8 → 8.0），避免隐式类型转换歧义。

`formatCs(token): FormatResult`

类型	C# 字面量	字段类型
color	`Windows.UI.Color.FromArgb(0xFF, 0x2B, 0x4C, 0x7C)`	`Windows.UI.Color`
dimension（整数）	`40.0`	`double`
dimension（小数）	`0.5`	`double`
dimension（%）	`0.500 // 50%（分数，由容器尺寸换算）`	`double`
duration	`200 // 200ms（毫秒）`	`int`
cubicBezier	`new LhEasing(0.4, 0, 0.2, 1)`	`LhEasing`
shadow	`new LhShadow(0xFF..., 0.0, 2.0, 8.0)`	`LhShadow`
number	`400` / `1.8`	`int` / `double`
string	`"Source Code Pro, ..."`	`string`

note（单位 / 换算说明）与 description 合并为一条行内注释；分号必须落在 literal 与注释之间，否则带注释的 literal（分数 / 时长 / 贝塞尔 / 投影）会让分号被注释吞掉（CS1002）。

`csMemberName(name): string`

转 PascalCase：default → Default、extraLarge → ExtraLarge。顺带规避 default / base 等 C# 上下文关键字（分组名同样走 pascalCase）。

`emitTree(lines, group, indent)`

嵌套 public static class 表达令牌层级（C# 的静态类即命名空间惯用法），成员 public static readonly T Name = literal;。

`buildCsBody(tokenSet, rootName)` / `buildDarkCsBody(tokenSet)`

明色根名由参数传入（LhTokens），暗色根固定 LhDarkTokens，内部都靠 emitTree 递归填充。文件头横幅在 windowsTarget.generate 里由 windows/LhTokens.cs.hbs 渲染。

导出

export { csTokenPath } —— 点路径转 LhTokens.Color.Primary.Default，供测试与外部消费。

docs.ts —— 文档产物（不经模板）

产物：dist/docs/tokens.md + tokens.light.json + tokens.dark.json

唯一不使用 handlebars 模板的 target，直接用代码拼字符串。

`literalValue(token): string`

color 输出 原值 → #rrggbb（a<1 时 → rgba(r, g, b, a)），其余直接 String(value)。

`buildTokenTable(input): string`

按 path 的顶级命名空间分组输出 markdown 表格「令牌 | 类型 | 明色 | 暗色 | 说明」；nativeOnly 标注为「原生新增」；暗色列无覆盖时填 —。

`buildDarkJson(input): string`

暗色覆盖表排序后 JSON.stringify(..., null, 2)。

三个产物的用途见 docs 产物。

五个 target

共享的暗色产物构造模式

android.ts —— Kotlin + Jetpack Compose

formatKotlin(path, token): FormatResult

emitTree(lines, group, indent, features)

buildKotlinBody(tokenSet, rootName, features) / buildDarkKotlinBody(tokenSet, features)

importsFor(features): string[]

renderKotlinFile(body, version, features): string

ios.ts —— Swift + SwiftUI

formatSwift(token): string

swiftMemberName(name): string

buildSwiftBody(tokenSet, rootName): string / buildDarkSwiftBody(tokenSet): string

emitTree(lines, group, indent)

harmony.ts —— 鸿蒙 ArkTS + ArkUI

formatEts(token): string

typeAnnotation(token): string

emitTree(lines, group, indent)

buildEtsBody(tokenSet, rootName): string / buildDarkEtsBody(tokenSet): string

windows.ts —— Windows C# + WinUI 3

toCsColor(c): string

doubleLiteral(value): string

formatCs(token): FormatResult

csMemberName(name): string

emitTree(lines, group, indent)

buildCsBody(tokenSet, rootName) / buildDarkCsBody(tokenSet)

导出

docs.ts —— 文档产物（不经模板）

literalValue(token): string

buildTokenTable(input): string

buildDarkJson(input): string

`formatKotlin(path, token): FormatResult`

`emitTree(lines, group, indent, features)`

`buildKotlinBody(tokenSet, rootName, features)` / `buildDarkKotlinBody(tokenSet, features)`

`importsFor(features): string[]`

`renderKotlinFile(body, version, features): string`

`formatSwift(token): string`

`swiftMemberName(name): string`

`buildSwiftBody(tokenSet, rootName): string` / `buildDarkSwiftBody(tokenSet): string`

`emitTree(lines, group, indent)`

`formatEts(token): string`

`typeAnnotation(token): string`

`emitTree(lines, group, indent)`

`buildEtsBody(tokenSet, rootName): string` / `buildDarkEtsBody(tokenSet): string`

`toCsColor(c): string`

`doubleLiteral(value): string`

`formatCs(token): FormatResult`

`csMemberName(name): string`

`emitTree(lines, group, indent)`

`buildCsBody(tokenSet, rootName)` / `buildDarkCsBody(tokenSet)`

`literalValue(token): string`

`buildTokenTable(input): string`

`buildDarkJson(input): string`