flex_theme_gen 1.0.4

Generate Flutter theme code from design tokens (YAML/JSON).

🌈 Flutter 主题生成系统

版本： 1.0.0

作者： Aiwen

功能： 通过 YAML 配置文件自动生成 Flutter 主题代码，支持链式调用（Padding / Radius / Bg / Border / Font），自动继承圆角，可自定义前缀（如 tw）。

---

flex_theme_gen 是一个 Flutter CLI 工具，通过 YAML 文件（设计 Tokens）自动生成完整的主题代码，包括：

• AppColors（明暗主题）
• Tokens（Spacing、Radius、Shadow、Border）
• Typography（字体体系）
• Tailwind 风格链式 UI 扩展（可配置前缀）

生成的代码可直接用于 Flutter 工程，无需手写主题类。

---

⚙️ 二、安装与运行

🔧 安装（本地或全局）

dart pub global activate flex_theme_gen

然后直接运行：

gen_flex_theme build

或者在项目中使用：

dart run flex_theme_gen:gen_flex_theme build

🧭 CLI 参数说明

参数	说明
--input	指定 design_tokens.yaml 的路径
--out	指定生成文件输出目录
--watch	监听文件变动自动重新生成

---

📁 三、YAML 配置示例（design_tokens.yaml）

fontsPackage: res
fonts:
  number: InterRes
  english: Roboto
  normal: Noto Sans SC

colors:
  light:
    colorFF33A9FF: FF33A9FF
    colorFF091C3D: FF091C3D
  dark:
    colorFF33A9FF: FF33A9FF
    colorFF091C3D: FF091C3D

tokens:
  prefix: tw   # 链式扩展方法前缀，可自定义
  spacing:
    2: 2
    4: 4
    6: 6
    8: 8
  radius:
    4: 4
    8: 8
    12: 12
  shadow:
    2: 2
    8: 8
  misc:
    blurSm: 2
    opacityDisabled: 0.5
  border:
    default:
      colorToken: colorFF33A9FF
      width: 1
    2: 2
    4: 4
    6: 6

typography:
  number:
    fontFamilyToken: number
    sizes:
      16R: { fontSize: 16, fontWeight: w400, lineHeight: 16 }
      16B: { fontSize: 16, fontWeight: w700, lineHeight: 16 }

---

📦 三方字体加载示例

在 pubspec.yaml 中注册第三方字体，以便 flex_theme_gen 的 Typography 自动识别：

flutter:
  fonts:
    - family: InterRes
      fonts:
        - asset: assets/fonts/Inter_24pt-Regular.ttf
          weight: 400
        - asset: assets/fonts/Inter_24pt-Bold.ttf
          weight: 700

在 design_tokens.yaml 中引用时：

fonts:
  number: InterRes     # 对应上面注册的 family 名称

这样 Typography 会自动生成：

TextStyles.number_16R
TextStyles.number_16B

---

🧱 四、在 pubspec.yaml 中配置 flex_theme_gen

flex_theme_gen 支持在 pubspec.yaml 中声明输入输出路径，类似于 flutter_gen。

✅ 示例：

dev_dependencies:
  flex_theme_gen:

flutter:
  assets:
    - apps_config/design_tokens.yaml

flex_theme_gen:
  input: apps_config/design_tokens.yaml   # 输入路径
  output: lib/generated/                  # 输出路径（生成的 .g.dart 文件）

然后直接执行：

dart run flex_theme_gen:gen_flex_theme build

⚙️ 优先级规则：

1.命令行参数最高（--input、--out）

2.其次是 pubspec.yaml 中的配置

3.最后才使用默认值（apps_config/design_tokens.yaml → output/）

---

🧩 五、生成文件一览

文件名	内容
app_colors.g.dart	明/暗主题颜色定义
tokens.g.dart	Spacing / Radius / Shadow / Misc / Border 常量
${prefix}_alias.g.dart	链式 UI 扩展（Padding / Radius / Bg / Border）
fonts.g.dart	字体定义
${prefix}_font.g.dart	字体链式扩展
typography.g.dart	Typography 定义
typography_resolved.g.dart	可直接应用的 TextStyle

---

🧩 六、链式调用（Tailwind 风格）

生成的 ${prefix}_alias.g.dart 提供链式构建方法。

前缀可自定义（默认为 tw）。

🔧 示例

Text(
  '注册',
  style: TextStyles.normal_P2_B.copyWith(
    color: colors.colorFFFFFFFF,
  ),
)
    .twPHx8()               // 横向 padding
    .twPVy6()               // 纵向 padding
    .twBg(colors.colorFF33A9FF) // 背景色
    .twRounded4()           // 圆角裁剪
    .onTap(() {
      print('注册点击');
    });

---

📚 支持方法总览

分类	方法	功能说明
Padding	.twP(double v)	padding: all
.twPHx(double v) / .twPVy(double v)	横向 / 纵向 padding
.twP4() .twPHx8() .twPVy16()	使用 Tokens.spacingXX
Radius	.twRounded4()	ClipRRect 裁剪圆角
.twRadius4()	DecoratedBox 视觉圆角
Background	.twBg(Color color)	设置背景色
Border	.twBorder({Color? color, double? width, double? radius})	默认边框（支持继承圆角）
.twBorder2() .twBorder4()	使用 Tokens.borderXX

.twBorder() 会自动检测并继承前面的 .twRadiusXX() 圆角值。

---

🚀 七、命令示例

一次性生成：

gen_flex_theme build --input apps_config/design_tokens.yaml --out output

持续监听：

gen_flex_theme watch --input apps_config/design_tokens.yaml --out output

或使用 pubspec.yaml 中的配置：

dart run flex_theme_gen:gen_flex_theme build

---

🔍 八、常见问题（FAQ）

问题	说明	解决方案
字体样式不变	未注册字体	检查 pubspec.yaml 与 design_tokens.yaml 字体 family 是否一致
Font family not found	路径或 family 错误	打开 .ttf 验证
明暗模式不切换	Theme 未绑定	确保使用 AppColors.light() / AppColors.dark()
Border 无法继承圆角	使用 .twRadius() 而非 .twRounded()	.twBorder() 会自动检测 .twRadiusXX() 设置的圆角
命令无效	未正确配置 pubspec.yaml	检查 flex_theme_gen 字段是否正确缩进在根级

---

🏁 九、总结

✅ YAML 驱动的主题生成系统

✅ 支持 Prefix（如 tw、fx）

✅ 一键生成 Colors / Tokens / Typography / Fonts

✅ Tailwind 风格链式扩展（Padding / Radius / Bg / Border）

✅ 边框自动继承圆角

✅ 模板系统可拓展

✅ 支持在 pubspec.yaml 中声明输入/输出路径

✅ 支持第三方字体加载与映射

让 Flutter 主题开发进入

全自动 · 结构化 · 可维护时代 🚀

---