flutter_xgen

🚀 VSCode + Flutter 开发效率小工具 一站式集成资源管理、热刷新、国际化、图标生成、重命名等核心能力，告别重复劳动，让开发更流畅高效。

✨ 核心特性

1. 🧭 统一功能面板

支持通过 fxg.yaml 配置 主项目（main project） 与 子项目（sub projects）

⚠️ 注意：如果项目中使用了 fxg.yaml 文件配置面板，则 fxg_xxx_yyy 等功能会优先读取 fxg.yaml 中的配置。

配置示例

fxg:
  main_project:
    dir: "" # 相对路径
    fxg_app_icon:
      # 主项目图标配置
      ...
    fxg_app_rename:
      # 主项目重命名配置
      ...
    fxg_assets_gen:
      # 主项目资源生成配置
      ...

  sub_projects:
    - dir: "" # 相对路径
      fxg_assets_gen:
        # 子项目资源生成配置
        ...

核心特点

📌 统一入口：侧边栏聚合所有核心功能入口，操作直观
⚡ 快速切换：支持功能模块与配置项快速切换
🔄 实时生效：所有配置修改即时生效，无需重启插件或项目

2. ⚡ 跨编辑器自动热刷新

🌟 即使在 Emacs、Vim、WebStorm 等外部编辑器中修改 .dart 文件，也能自动触发 VS Code 调试会话中的热刷新
🔍 当项目通过 VS Code 调试（F5） 启动时，插件会监听文件系统变更并自动执行热刷新
🧠 智能判断刷新方式：系统内置规则自动区分 Hot Reload（状态保留）与 Hot Restart（应用重启）
- 修改 main.dart、pubspec.yaml、路由、DI、配置等结构性文件 → 自动 Hot Restart
- 修改普通 Widget、业务逻辑等代码 → 自动 Hot Reload
🚀 保存即刷新，实时预览修改结果，无需切回 VS Code 或手动输入命令
🎛️ Generator Web 面板支持手动触发 Hot Reload / Hot Restart，并显示当前调试会话状态

3. 🧩 类型安全的资源管理（`assets.dart`）

自动扫描项目资源并生成类型安全的 Dart 类，彻底避免硬编码与路径拼写错误。 ✅ 支持图片预览、SVGA 动画预览、文件大小显示、TinyPNG 压缩等功能。

🔑 核心能力

📸 悬停预览图片或动画
📊 文件大小可视化（KB / MB / GB）
🎨 一键 TinyPNG 无损压缩
📁 文件新增/删除实时同步生成
🔒 静态类型检查 + 智能补全
🧱 多模块隔离管理，避免命名冲突

🔧 配置方式（`fxg.yaml` 或 `pubspec.yaml`）

✅ 单模块示例

fxg_assets_gen:
  output_dir: lib/generated
  named_with_parent: true
  output_filename: assets
  class_name: Assets
  filename_split_pattern: "[-_]"
  leading_with_package_name: false
  uniqify_name: true
  exclude_paths:
    - assets/temp/
    - assets/icons/unused/
  include_paths:
    - assets/images/
    - assets/sounds/

🧩 多模块示例

fxg_assets_gen:
  - output_dir: lib/generated
    output_filename: assets_main
    class_name: AssetsMain
    include_paths:
      - assets/main/
  - output_dir: lib/generated
    output_filename: assets_store
    class_name: AssetsStore
    include_paths:
      - assets/store/

⚙️ 参数说明

参数名	类型	默认值	说明
`output_dir`	string	`lib/generated`	输出目录
`named_with_parent`	bool	`true`	是否在变量名中包含上级目录名
`output_filename`	string	`assets`	生成文件名（不含 `.dart`）
`class_name`	string	`Assets`	生成类名
`filename_split_pattern`	string	`"[-_]"`	文件名分隔符正则（例：`dog-icon → dogIcon`）
`leading_with_package_name`	bool	`false`	是否添加包名前缀
`uniqify_name`	bool	`true`	重名文件自动加后缀
`auto_detection`	bool	`true`	是否自动监听 assets 目录变化
`include_paths`	string[]	无	包含路径（支持 glob 语法）
`exclude_paths`	string[]	无	排除路径（支持 glob 语法）

⚠️ Glob 特殊符号注意事项

在 YAML 配置中使用 glob 模式（如 *、**）时，必须加引号，否则可能被解析为 YAML 语法而导致不生效：
# ❌ 错误：glob 可能不生效
include_paths:
  - lib/**

# ✅ 正确：使用引号包裹
include_paths:
  - "lib/**"
exclude_paths:
  - "lib/generated/**"
  - "**/*.g.dart"

🧾 示例

assets/
 ├─ images/
 │   ├─ cat.png
 │   └─ dog-icon.jpg
 └─ sounds/
     └─ meow.mp3

生成：

class Assets {
  static const imagesCat = "assets/images/cat.png";
  static const imagesDogIcon = "assets/images/dog-icon.jpg";
  static const soundsMeow = "assets/sounds/meow.mp3";
}

使用：

Image.asset(Assets.imagesCat);
AudioPlayer.play(Assets.soundsMeow);

4. 🌍 文本国际化

兼容 Flutter Intl / Intl Utils，支持 ARB 多语言文案管理，简化国际化流程。

📘 配置参考： 🔗 https://github.com/localizely/intl_utils#configure-package

⚠️ 不支持 localizely_api_key 云端配置。

5. 🏷️ 应用重命名

自动批量修改 App 名称、包名、Bundle ID 等跨平台配置。支持单 target 与多 target 的 iOS 工程结构。

fxg_app_rename:
  app_name: "MyApp" # 若子项中包含 app_name，该项失效
  flutter:
    app_name: "MyApp"
  android:
    enable: true
    package: "com.company.myapp"
  ios:
    # --- 写法一：单 target（Map 结构） ---
    app_name: "MyApp"
    bundle_name: "MyApp"
    target_name: "Runner"
    bundle_id: "com.company.myapp"

    # --- 写法二：多 target（List 结构）每一项的 target_name 不能为空 ---
    # - app_name: "MyApp"
    #   bundle_name: "MyApp"
    #   target_name: "Runner"
    #   bundle_id: "com.company.myapp"
    # - enable: false
    #   target_name: "RunnerTest"
    #   # bundle_id 与 bundle_ids 二选一；仅在需要区分环境时使用 bundle_ids
    #   bundle_ids:
    #     debug: "com.company.myapp.test.debug"
    #     release: "com.company.myapp.test.release"
  macos:
    enable: false
    app_name: "MacOSApp"
    bundle_name: "MacOSAppBN"
    bundle_id: "com.app.macos"
    copyright: "flutter_xgen@2025"

⚙️ 参数说明

参数名	类型	默认值	说明
`app_name`	string	无	全局应用名称（可被子项覆盖）
`flutter.app_name`	string	无	Flutter 层应用名（任务栏显示名称）
`android.enable`	bool	`true`	是否启用 Android 修改
`android.package`	string	无	Android 包名
`ios[].enable`	bool	`true`	是否启用该 iOS target
`ios[].target_name`	string	无	iOS target 名称
`ios[].bundle_id`	string	无	iOS Bundle ID（支持分 debug/release）
`macos.enable`	bool	`false`	是否启用 macOS 修改
`macos.bundle_id`	string	无	macOS Bundle ID
`macos.copyright`	string	无	macOS 版权信息

bundle_id 与 bundle_ids 是互斥配置。默认使用 bundle_id；只有 Debug / Profile / Release 需要不同 Bundle ID 时，才使用 bundle_ids。

6. 🖼️ 应用图标生成

自动生成多平台图标资源，无需手动切图。

fxg_app_icon:
  enable: true
  app_icon: "assets/icons/app.png" # 要求尺寸: 1024x1024
  android:
    enable: true
    app_icon: "assets/icons/_android_app.png"
    enable_circle_icon: true
    firebase_notification_icon: "assets/icons/notification.png"
  ios:
    enable: false
    app_icon: "assets/icons/ios.png"
    ios_mode: "single_size"   # 可选: single_size | all_sizes | none，默认 single_size
    macos_mode: "none"        # 可选: all_sizes | none，默认 none
    watchos_mode: "none"      # 可选: single_size | all_sizes | none，默认 none
    launch_image: "assets/icons/launch.png"
  macos:
    enable: false
    app_icon: "assets/icons/macos.png"
    icon_mode: "all_sizes"    # 可选: all_sizes | none，默认 all_sizes
    enable_round_icon: true    # 启用圆角图标（Big Sur 风格，默认 true）
    preserve_alpha: true       # 保留透明通道（默认 true）
    command_tab_scale: 0.82    # Command+Tab 图标缩放比例（默认 0.82）
  web:
    enable: false
    app_icon: "assets/icons/web.png" # 建议尺寸: 512x512 或更大
  linux:
    enable: false
    app_icon: "assets/icons/linux.png"
    icon_name: "my_app"        # 可选，默认从 .desktop 或项目名推断
  windows:
    enable: false
    app_icon: "assets/icons/windows.png"
    ico_filename: "app_icon.ico"

⚙️ 参数说明

参数名	类型	默认值	说明
`enable`	bool	无	是否启用 `fxg_app_icon`
`app_icon`	string	无	主图标文件路径（1024x1024 PNG）
`android.enable`	bool	`false`	是否启用 Android 图标生成
`android.app_icon`	string	无	Android 图标文件路径
`android.enable_circle_icon`	bool	`false`	是否生成传统圆形图标并配置 `roundIcon`
`android.firebase_notification_icon`	string	无	Firebase 通知图标路径
`ios.enable`	bool	`false`	是否启用 iOS 工程 AppIcon 生成
`ios.app_icon`	string	无	iOS 工程图标文件路径
`ios.ios_mode`	string	`single_size`	iOS 工程内 iOS AppIcon 模式：`single_size` / `all_sizes` / `none`
`ios.macos_mode`	string	`none`	iOS 工程内 Mac Catalyst AppIcon 模式：`all_sizes` / `none`
`ios.watchos_mode`	string	`none`	iOS 工程内 watchOS AppIcon 模式：`single_size` / `all_sizes` / `none`
`ios.launch_image`	string	无	启动图路径
`macos.enable`	bool	`false`	是否启用 macOS 图标生成
`macos.app_icon`	string	无	macOS 图标文件路径
`macos.icon_mode`	string	`all_sizes`	macOS 独立工程图标模式：`all_sizes` / `none`
`macos.enable_round_icon`	bool	`true`	启用圆角图标（Big Sur 22% 圆角）
`macos.preserve_alpha`	bool	`true`	保留透明通道
`macos.command_tab_scale`	number	`0.82`	Command+Tab 图标缩放比例
`web.enable`	bool	`false`	是否启用 Flutter Web PWA 图标
`web.app_icon`	string	无	Web 图标文件路径（建议 512x512）
`linux.enable`	bool	`false`	是否启用 Linux 桌面图标生成
`linux.app_icon`	string	无	Linux 图标文件路径（1024x1024 PNG）
`linux.icon_name`	string	自动推断	Linux `.desktop` 使用的图标名
`windows.enable`	bool	`false`	是否启用 Windows 图标生成
`windows.app_icon`	string	无	Windows 图标文件路径（1024x1024 PNG）
`windows.ico_filename`	string	`app_icon.ico`	Windows ICO 文件名

ios.ios_mode、ios.macos_mode、ios.watchos_mode 现在彼此独立配置，不再使用 enable_pad、enable_macos、enable_watch 旧字段。

single_size 模式会生成并复用 1024.png；all_sizes 模式会为每个 Apple 槽位写入带 filename 的条目，并实际生成对应 PNG 文件。

7. 🤖 AI Agent Skills

fxg_app_icon 与 fxg_app_rename 已整理为可复用的开源 agent skills，适用于支持 skills 生态的 AI 工具，不仅限于 Codex，也包括 Claude Code、Cursor、Cline、Gemini CLI 等。

开源仓库：

ivine/flutter_xgen_skills

安装示例：

npx skills add ivine/flutter_xgen_skills --skill fxg-app-icon
npx skills add ivine/flutter_xgen_skills --skill fxg-app-rename

如果需要显式指定 agent，也可以追加 --agent <agent-name>：

npx skills add ivine/flutter_xgen_skills --skill fxg-app-icon --agent codex
npx skills add ivine/flutter_xgen_skills --skill fxg-app-icon --agent claude-code

这两个 skill 的定位：

fxg-app-icon：基于 fxg_app_icon 配置生成 Flutter 多平台图标
fxg-app-rename：基于 fxg_app_rename 配置批量修改 Flutter 应用名称、包名与 Bundle ID

8. 📚 Import 排序工具

自动排序 import，保持代码结构统一、风格整洁。

fxg_import_sort:
  exclude_paths: [lib/generated/**] # 支持 glob 语法
  include_paths: [lib/**]
  sort_by: length        # 可选：'length' | 'alphabetical'
  sort_order: asc        # 可选：'asc' | 'desc'

⚙️ 参数说明

参数名	类型	默认值	说明
`exclude_paths`	string[]	无	排除的路径（支持 glob 语法）
`include_paths`	string[]	`["lib/**"]`	包含的路径（默认扫描整个 lib 目录）
`sort_by`	string	`"length"`	排序依据：`length`（按长度）或 `alphabetical`（按字母）
`sort_order`	string	`"asc"`	排序方向：`asc` 或 `desc`

⚠️ Glob 特殊符号注意事项

在 YAML 配置中使用 glob 模式（如 *、**）时，必须加引号，否则可能被解析为 YAML 语法而导致不生效：
# ❌ 错误：glob 可能不生效
exclude_paths: [lib/generated/**]

# ✅ 正确：使用引号包裹
exclude_paths: ["lib/generated/**"]
include_paths: ["lib/**", "test/**"]

❓ 常见问题

Q：跨编辑器热刷新不生效？ ✅ 请检查以下几点：

通过 VS Code 调试（F5）启动项目
启用 VS Code 自动保存（File → Auto Save）
外部编辑器已正确保存文件
打开「输出 → FXGLog」查看日志

📮 反馈与贡献

💌 提交 Issue： 👉 flutter_xgen_feedback

Flutter XGen

Dengwww

flutter_xgen

✨ 核心特性

1. 🧭 统一功能面板

配置示例

核心特点

2. ⚡ 跨编辑器自动热刷新

3. 🧩 类型安全的资源管理（`assets.dart`）

🔑 核心能力

🔧 配置方式（`fxg.yaml` 或 `pubspec.yaml`）

✅ 单模块示例

🧩 多模块示例

⚙️ 参数说明

🧾 示例

4. 🌍 文本国际化

5. 🏷️ 应用重命名

⚙️ 参数说明

6. 🖼️ 应用图标生成

⚙️ 参数说明

7. 🤖 AI Agent Skills

8. 📚 Import 排序工具

⚙️ 参数说明

❓ 常见问题

📮 反馈与贡献

Flutter XGen

Dengwww

flutter_xgen

✨ 核心特性

1. 🧭 统一功能面板

配置示例

核心特点

2. ⚡ 跨编辑器自动热刷新

3. 🧩 类型安全的资源管理（assets.dart）

🔑 核心能力

🔧 配置方式（fxg.yaml 或 pubspec.yaml）

✅ 单模块示例

🧩 多模块示例

⚙️ 参数说明

🧾 示例

4. 🌍 文本国际化

5. 🏷️ 应用重命名

⚙️ 参数说明

6. 🖼️ 应用图标生成

⚙️ 参数说明

7. 🤖 AI Agent Skills

8. 📚 Import 排序工具

⚙️ 参数说明

❓ 常见问题

📮 反馈与贡献

3. 🧩 类型安全的资源管理（`assets.dart`）

🔧 配置方式（`fxg.yaml` 或 `pubspec.yaml`）