Skip to content

README.md

Latest commit

 

History

History
149 lines (100 loc) · 5.48 KB

README.md

File metadata and controls

149 lines (100 loc) · 5.48 KB

tdesign_flutter_tools

Flutter Version Dart Version

TDesign Flutter 组件库文档生成工具

一个用于自动生成 TDesign Flutter 组件库示例代码和 API 文档的命令行工具,基于 smart_cli。

组件注释规范

组件widget注释示例

/// 组件简介（必须）

组件属性注释示例

/// 属性简介（必须）

工具职责边界

工具只负责通用 AST 解析规则，不会对个别组件做特殊兼容，也不会修正源码里不合规的注释。

由工具负责（通用规则） 由源码注释负责（需合规编写）
从构造参数 AST 提取类型、默认值 字段/参数的 /// 说明文案
构造参数与公开属性/静态成员分表展示 注释内容与字段语义一致（如 content 不应写「标题」）
过滤 this.xxx 被误识别为默认值 错别字、遗漏注释、注释写在错误位置
解析 abstract class 实例方法、工厂构造及参数表 super.key 等场景的类型展示
从父类字段解析 super.xxx 参数类型 无注释时说明列显示 -（符合预期）
同文件内自动收录 public 的 enum / typedef 也可在 --name 中显式指定枚举或别名名称
folder 模式下检测跨文件重复 enum/typedef 并告警 文档保留重复条目以暴露源码问题，工具不做 silent dedupe
Markdown 表格转义、方法参数格式化 无注释时说明列显示 -（符合预期）

原则： 注释不合规导致的文档问题，应在组件源码中补全/修正 /// 注释，而不是在工具里打补丁。

组件demo注释示例

/// demo名称（可以为空，为空的时候默认显示组件名称）
/// demo示例介绍（可以为空）

本地开发与测试

当 tdesign-component/pubspec.yaml 使用 path 依赖指向本仓库时，可在本地直接验证文档生成，无需发布到 git：

# 1. 确保 component 的 pubspec 已配置：
#    tdesign_flutter_tools:
#      path: ../tdesign-flutter-tools

# 2. 在 component 目录解析依赖（需要网络）
cd ../tdesign-component && dart pub get

# 3. 运行本地测试脚本（picker / calendar / dialog）
./scripts/local_test.sh picker

若 dart pub get 因网络不可用失败，可临时将 tdesign-component/.dart_tool/package_config.json 中 tdesign_flutter_tools 的 rootUri 指向本地路径，脚本会通过 --packages 跳过联网校验：

./scripts/local_test.sh calendar

组件库工具使用方法

初始化工具调用命令

dart bin/main.dart generate
    --file                相对ui_component目录的组件文件路径
    --folder              相对ui_component目录的组件文件夹路径
    --name                组件名，多个组件名之间用英文,分割
    --folder-name         [可选]生成的组件示例文件夹名称,默认生成的文件夹名称是第一个name参数的下划线表示
    --[no-]only-api       是否只更新api文件
    --[no-]use-grammar    是否采用语法分析器,默认采用词法分析

一、 初始化命令

初始化命令有以下 3 种使用方式：

1、初始化一个组件文件中的一个组件示例，没有--folder-name的时候，默认文件夹名称是第一个name的下划线表示，示例：

dart bin/main.dart generate --file lib/checkbox/custom_check_box.dart --name TECheckBox --folder-name checkbox

2、把一个文件中的多个组件合并生成一份示例数据（api说明生成在一个文件中），没有--folder-name的时候，默认文件夹名称是第一个name的下划线表示

dart bin/main.dart generate --file lib/checkbox/custom_check_box.dart --name SquareCheckbox,TECheckBox --folder-name checkbox2

3、把一个文件夹中的多个组件合并生成一份示例数据（api说明生成在一个文件中），没有--folder-name的时候，默认文件夹名称是第一个name的下划线表示

dart bin/main.dart generate --folder lib/setting --name SettingItemWidget,SettingTowRowCellWidget,SettingLeftTextCellWidget,SettingCheckBoxCellWidget,SettingTowTextCellWidget,SettingTowLineTextCellWidget,SettingGroupWidget,SettingGroupTextWidget --folder-name setting

如果想只更新API文档，那么在上述初始化的命令之后增加参数 --only-api 即可

默认采用词法分析，如果想采用语法分析的方式生成代码，那么在上述初始化的命令之后增加参数 --use-grammar 即可

二、更新组件示例命令

生成命令行工具

在根目录执行以下命令：

编译当前平台的二进制文件

dart compile exe bin/main.dart -o demo_tool

编译不同环境的二进制文件

# macOS (Intel)
dart compile exe bin/main.dart -o demo_tool_macos_intel

# macOS (Apple Silicon/M1/M2)
dart compile exe bin/main.dart -o demo_tool_macos_arm64

# Linux x64
dart compile exe bin/main.dart -o demo_tool_linux_x64

# Windows x64
dart compile exe bin/main.dart -o demo_tool_windows_x64.exe

注意：要编译其他平台的二进制文件，需要在对应的平台上运行编译命令，或者使用交叉编译工具。

附录：

生成代码文档

flutter pub global run dartdoc:dartdoc