FlutterKit

外观

TDesign Flutter ​

FlutterKit 使用 TDesign Flutter 官方文档 作为基础组件 API 的权威来源。项目不复制官方的组件文档，而是约定如何把 TDesign、FlutterKit 主题与 Feature 业务组件正确组合。

三层边界 ​

层级内容查阅位置
官方组件层TDButton、TDCell、TDNavBar、TDTabBar、TDEmpty 等 APITDesign 官方文档
本地参考层当前依赖版本的组件资料与示例仓库 docs/tdesign-flutter/
项目规范层AppTheme、尺寸/形状、BaseView、链式扩展、业务 Widgetlib/core/ 与本帮助文档

遇到“某个 TD* 属性怎么传”先看官方或本地参考；遇到“页面该如何统一样式、加载状态和导航结构”看 FlutterKit 文档。不要为了填补官方 API 文档而在 Feature 中复制一份组件封装。

接入规则 ​

dart
/// 使用 TDesign Cell 组成项目设置项。
Widget buildSettingsCell(BuildContext context, SettingsLogic logic) {
  final AppTheme theme = AppTheme.of(context);

  return TDCellGroup(
    // 卡片主题由 TDesign 组件负责具体视觉结构。
    theme: TDCellGroupTheme.cardTheme,
    cells: [
      TDCell(
        title: '通知设置',
        description: '管理消息提醒方式',
        arrow: true,
        // 点击只转交 Logic，业务跳转不写在 Widget 内。
        onClick: (_) => logic.openNotificationSettings(),
      ),
    ],
  ).backgroundColor(theme.backgroundContainer);
}

常用组件的项目位置 ​

需求优先组件或封装补充说明
页面导航栏BaseView.head() → TDNavBar普通页面无需手写 AppBar
加载、空、错误BaseNetworkView → TDLoading / TDEmpty用状态机，不在每页重复判断
设置列表TDCellGroup、TDCellThemeDemoView 是现有示例
底部导航TDBottomTabBarMainView 处理响应式位置
TabBaseTabView → TDTabBar处理 Tab / PageView 同步
主操作TDButton、TDFab颜色通过主题或官方主题参数表达
弹窗BaseDialog 或 TDesign 对话框底部业务弹窗优先 BaseDialog

主题接入 ​

TDesign JSON 被解析为 TDThemeData 后同时放入 ThemeData.extensions。因此 TDesign 组件与 AppTheme 可在同一次主题切换中更新：TDesign 组件读取自身 token，业务自定义部分读取 AppTheme 的语义色。详见 主题系统。

注意事项 ​

  • TDTheme.of(context)、AppTheme.of(context) 与尺寸 getter 都要求组件位于初始化后的应用树中；不要在全局静态初始化阶段读取。
  • 新组件先查看当前 tdesign_flutter 版本的官方 API，再在项目中组合；不要按 Web、Vue 或 React 的 TDesign API 猜测 Dart 参数。
  • 组件预览使用 Widget Preview，网络页面预览必须注入静态数据。

关联阅读 ​