yx_icon_fonts_flutter/README.md

# YX Icon Fonts

从 iconfont.json 生成 Flutter IconData 常量的 Dart CLI 工具。

## 特性

- 🎨 解析 iconfont.cn 导出的 JSON 文件
- 📝 生成类型安全的 Flutter IconData 常量
- ⚙️ YAML 配置文件支持
- 🏗️ 自定义类名和输出路径
- 📚 自动生成文档注释

## 安装

在您的 Flutter 项目的 `pubspec.yaml` 中添加为开发依赖：

```yaml
dev_dependencies:
  yx_icon_fonts:
    git:
      url: https://gitea.23544.com/wangyang/yx_icon_fonts_flutter
      ref: v2.0.0
```

然后运行：

```bash
dart pub get
```

## 快速开始

### 1. 初始化配置文件

```bash
dart run yx_icon_fonts init
```

这将在项目根目录创建 `icon_generator_config.yaml` 配置模板。

### 2. 准备资源文件

从 [iconfont.cn](https://www.iconfont.cn/) 下载您的图标项目，将以下文件放到项目中：

- `iconfont.ttf` - 字体文件
- `iconfont.json` - 图标配置文件

### 3. 配置 pubspec.yaml

在 `pubspec.yaml` 中注册字体：

```yaml
flutter:
  fonts:
    - family: iconfont
      fonts:
        - asset: assets/fonts/iconfont.ttf
```

### 4. 编辑配置文件

修改 `icon_generator_config.yaml`：

```yaml
input:
  font_file: "assets/fonts/iconfont.ttf"
  json_file: "assets/fonts/iconfont.json"
  font_family: "iconfont"

output:
  file_path: "lib/generated/icons.dart"
  class_name: "AppIcons"
```

### 5. 生成代码

```bash
dart run yx_icon_fonts generate
```

### 6. 使用生成的图标

```dart
import 'package:your_app/generated/icons.dart';

// 在 Widget 中使用
Icon(AppIcons.iconHome, size: 24, color: Colors.blue)

// 在 IconButton 中使用
IconButton(
  icon: Icon(AppIcons.iconSettings),
  onPressed: () {},
)
```

## 命令参考

### help - 显示帮助

```bash
dart run yx_icon_fonts help
```

### init - 初始化配置

```bash
# 创建配置文件
dart run yx_icon_fonts init

# 强制覆盖已存在的配置文件
dart run yx_icon_fonts init --force
```

### generate - 生成代码

```bash
# 使用默认配置文件
dart run yx_icon_fonts generate

# 指定配置文件
dart run yx_icon_fonts generate --config my_config.yaml

# 详细输出
dart run yx_icon_fonts generate --verbose
```

## 配置选项

完整的配置选项请参考 [icon_generator_config.template.yaml](./icon_generator_config.template.yaml)。

### generator 配置

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| name | string | "Icon Generator" | 生成器名称，用于代码注释 |
| version | string | "1.0" | 版本号 |
| author | string | "" | 作者信息 |

### input 配置

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| font_file | string | "assets/fonts/iconfont.ttf" | 字体文件路径 |
| json_file | string | "assets/fonts/iconfont.json" | JSON 配置文件路径 |
| font_family | string | "iconfont" | 字体家族名称 |

### output 配置

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| file_path | string | "lib/generated/icons.dart" | 输出文件路径 |
| class_name | string | "AppIcons" | 生成的类名 |
| generate_docs | bool | true | 是否生成文档注释 |
| use_const_constructor | bool | true | 是否使用 const 构造函数 |

## 生成的代码示例

```dart
// ignore_for_file: constant_identifier_names

// ============================================
// 此文件由 yx_icon_fonts 自动生成，请勿手动修改
// 生成时间: 2025-01-01 12:00
// 图标数量: 50
// ============================================

import 'package:flutter/widgets.dart';

/// MyApp Icons 图标常量
class AppIcons {
  AppIcons._();

  // 统一的 IconData 构造方法
  static const _icon = _IconDataFactory._();

  /// icon_home (U+E600)
  static final IconData iconHome = _icon(0xe600);

  // ... 更多图标
}

/// 内部 IconData 工厂类
class _IconDataFactory {
  const _IconDataFactory._();

  static const String _fontFamily = 'iconfont';

  IconData call(int codePoint) => IconData(codePoint, fontFamily: _fontFamily);
}
```

## 从 v1.x 迁移

v2.0 版本将 yx_icon_fonts 从 Flutter 库转换为了 CLI 工具。主要变化：

1. **安装方式变化**：从 `dependencies` 改为 `dev_dependencies`
2. **资源文件位置**：字体和 JSON 文件现在放在使用项目中，而非库中
3. **配置方式**：使用 YAML 配置文件，支持自定义类名和路径

## License

MIT License