buildTokens

从 Excel 设计规范文件自动解析并生成多种格式的设计令牌文件（CSS、SCSS、Less、JS、TS、JSON）。

前置依赖

依赖参数

参数名	类型	说明
deps.readFileSync	FileSystem['readFileSync']	同步读取文件内容
deps.writeFileSync	FileSystem['writeFileSync']	同步写入文件内容
deps.existsSync	FileSystem['existsSync']	检查文件/目录是否存在
deps.mkdirSync	FileSystem['mkdirSync']	创建目录
deps.join	Path['join']	路径拼接
deps.resolve	Path['resolve']	解析绝对路径
deps.error	Console['error']	错误日志输出
deps.log	Console['log']	信息日志输出
deps.mixColors	(baseColor: string, overlayColor: string, overlayOpacity: number) => string	混合颜色计算函数

环境要求

• xlsx: Excel 文件解析库
• fs/path: Node.js 文件系统和路径模块

npm install xlsx
# Node.js 环境自带 fs 和 path

函数签名

import type { FileSystem, Path } from '../../../references/node.d'
import type { Console } from '../../../references/console.d'
import type { XLSXLibrary } from '../../../references/xlsx.d'

export interface BuildTokensDeps {
  /** 同步读取文件内容 */
  readFileSync: FileSystem['readFileSync']
  /** 同步写入文件内容 */
  writeFileSync: FileSystem['writeFileSync']
  /** 检查文件/目录是否存在 */
  existsSync: FileSystem['existsSync']
  /** 创建目录 */
  mkdirSync: FileSystem['mkdirSync']
  /** 路径拼接 */
  join: Path['join']
  /** 解析绝对路径 */
  resolve: Path['resolve']
  /** 错误日志输出 */
  error: Console['error']
  /** 信息日志输出 */
  log: Console['log']
  /** 混合颜色计算函数 */
  mixColors: (baseColor: string, overlayColor: string, overlayOpacity: number) => string
}

export interface BuildConfig {
  /** Excel 文件路径 */
  excelPath: string
  /** 默认输出目录 */
  outputDir: string
  /** 生成的文件配置 */
  outputs: {
    css?: { enabled: boolean; filename?: string; prefix?: string; outputDir?: string }
    scss?: { enabled: boolean; filename?: string; prefix?: string; outputDir?: string }
    less?: { enabled: boolean; filename?: string; prefix?: string; outputDir?: string }
    js?: { enabled: boolean; filename?: string; exportName?: string; outputDir?: string }
    ts?: { enabled: boolean; filename?: string; exportName?: string; typeName?: string; outputDir?: string }
    json?: { enabled: boolean; filename?: string; indent?: number; outputDir?: string }
  }
  /** 是否生成 README 文档 */
  generateReadme?: boolean
  /** README 文档输出目录 */
  readmeOutputDir?: string
  /** 是否显示详细日志 */
  verbose?: boolean
}

export interface BuildResult {
  /** 解析出的令牌数量 */
  tokenCount: number
  /** 生成的文件信息 */
  files: Array<{
    format: string
    filename: string
    size: number
    path: string
  }>
  /** 输出目录路径 */
  outputDir: string
}

function buildTokens(
  config: BuildConfig,
  XLSX: XLSXLibrary,
  deps: BuildTokensDeps,
  logger?: { log: (message: string) => void }
): BuildResult

参数

参数名	类型	必填	说明
config	BuildConfig	是	构建配置，包含 Excel 文件路径、输出目录和文件格式配置
XLSX	XLSXLibrary	是	XLSX 库实例，用于解析 Excel 文件
deps	BuildTokensDeps	是	文件系统和日志依赖，包含所有 Node.js API 和 mixColors 函数
logger	{ log: (message: string) => void }	否	可选的日志记录器，用于输出构建过程信息

返回值

类型	说明
BuildResult	构建结果对象，包含解析的令牌数量和生成的文件列表

工作原理

1. 配置合并：合并默认配置和用户提供的配置
2. 文件检查：使用 deps.existsSync 检查 Excel 文件是否存在
3. 令牌解析：调用 parseDesignTokens 解析 Excel 文件，生成 TokenMap
4. 目录创建：使用 deps.mkdirSync 创建输出目录
5. 文件生成：
   • CSS 变量：生成 :root { --color: #FF0000; } 格式
   • SCSS/Less 变量：生成 $color: #FF0000; 格式
   • JS/TS 对象：生成 export const tokens = { color: '#FF0000' } 格式
   • JSON 文件：生成格式化的 JSON 对象
6. 颜色处理：自动将 RGBA 转换为 8 位十六进制格式
7. README 生成：自动生成使用说明文档
8. 结果返回：返回包含文件信息和令牌数量的结果对象

异常

错误类型	触发条件	错误信息
Error	Excel 文件不存在	"Excel 文件不存在: [路径]"
Error	XLSX 库解析失败	XLSX 库内部错误
Error	mixColors 依赖缺失	"mixColors 依赖未提供"
Error	文件系统权限不足	Node.js 文件系统错误

使用示例

基础用法

import * as XLSX from 'xlsx'
import * as fs from 'fs'
import * as path from 'path'
import { mixColors } from 'zcw-shared/functions/design-tokens/mixColors'
import { buildTokens } from 'zcw-shared/functions/design-tokens/buildTokens'

const config = {
  excelPath: './design-tokens.xlsx',
  outputDir: './dist/tokens',
  outputs: {
    css: { enabled: true, filename: 'design-tokens.css' },
    scss: { enabled: true, filename: '_design-tokens.scss' },
    js: { enabled: true, filename: 'design-tokens.js' },
    ts: { enabled: true, filename: 'design-tokens.ts' }
  },
  verbose: true
}

const result = buildTokens(
  config,
  XLSX,
  {
    readFileSync: fs.readFileSync,
    writeFileSync: fs.writeFileSync,
    existsSync: fs.existsSync,
    mkdirSync: fs.mkdirSync,
    join: path.join,
    resolve: path.resolve,
    error: console.error,
    log: console.log,
    mixColors
  },
  { log: console.log }
)

console.log(`生成 ${result.tokenCount} 个设计令牌`)
console.log('生成的文件:', result.files.map(f => `${f.filename} (${f.format})`))

简化用法

import { buildTokensSimple } from 'zcw-shared/functions/design-tokens/buildTokens'

const result = buildTokensSimple(
  './design-tokens.xlsx',
  './dist/tokens',
  XLSX,
  {
    readFileSync: fs.readFileSync,
    writeFileSync: fs.writeFileSync,
    existsSync: fs.existsSync,
    mkdirSync: fs.mkdirSync,
    join: path.join,
    resolve: path.resolve,
    error: console.error,
    log: console.log,
    mixColors
  },
  { log: console.log },
  { verbose: true, formats: ['css', 'js', 'ts'] }
)

自定义配置

const advancedConfig = {
  excelPath: './design-tokens.xlsx',
  outputDir: './dist',
  outputs: {
    css: { 
      enabled: true, 
      filename: 'tokens.css', 
      prefix: 'dt',
      outputDir: './dist/css' 
    },
    scss: { 
      enabled: true, 
      filename: '_tokens.scss', 
      prefix: 'dt',
      outputDir: './dist/scss' 
    },
    json: { 
      enabled: true, 
      filename: 'tokens.json', 
      indent: 4,
      outputDir: './dist/data' 
    }
  },
  generateReadme: true,
  readmeOutputDir: './dist/docs',
  verbose: true
}

const result = buildTokens(advancedConfig, XLSX, deps, logger)