README_zh_CN.md

English | 简体中文

TDesign Flutter 是基于腾讯设计体系的跨平台 UI 组件库，使用 Flutter 框架开发，可快速构建美观、一致的移动端/Web 应用，提供丰富的预制组件和主题定制能力，支持 iOS、Android、Web 多端运行。

🎉 特性

• 提供遵循 TDesign 设计规范的 Flutter UI 组件库
• 支持根据 App 设计风格自定义主题
• 提供常用图标库，支持自定义替换
• 根据 TDesign 规范定义颜色组（可在 TColors 中查看）
• 通过颜色值声明类实时预览默认颜色效果

📱 预览

Android：扫描二维码下载预览应用

下载链接：tdesign-flutter-0.2.7-314.apk

iOS：运行项目预览

https://github.com/Tencent/tdesign-flutter/tree/main/tdesign-component

🔨 安装

SDK 版本要求

dart: ">=3.2.6 <4.0.0"
flutter: ">=3.16.0"

添加依赖

在 pubspec.yaml 中添加以下内容：

dependencies:
  tdesign_flutter: ^0.2.7

引入

import 'package:tdesign_flutter/tdesign_flutter.dart';

📖 使用方法

主题配置

可通过 JSON 文件配置主题样式（颜色、字体尺寸、字体样式、圆角、阴影）。通过 TTheme.of(context) 或 TTheme.defaultData() 获取主题数据。

建议：组件都使用 TTheme.of(context)。不需要跟随局部主题的组件，才可以使用 TTheme.defaultData()。

// 颜色
TTheme.of(context).brandNormalColor

// 字体
TTheme.defaultData().fontBodyLarge

图标

TDesign 图标为 TTF 格式，不跟随主题：

Icon(TIcons.activity)

🎨 自定义主题

TDesign Flutter 提供两种灵活的主题定制方式：

方式一：JSON 配置

直接使用 JSON 格式定义主题属性：

String themeConfig = '''
{
  "myTheme": {
    "color": {
      "brandNormalColor": "#D7B386"
    },
    "font": {
      "fontBodyMedium": {
        "size": 40,
        "lineHeight": 55
      }
    }
  }
}
''';

MaterialApp(
  theme: ThemeData(
    extensions: [TThemeData.fromJson('myTheme', themeConfig)!],
  ),
  // ...
)

所有可用的主题键值请参考 t_default_theme.dart

方式二：主题生成器（推荐）

如果你不想自定义太多颜色，但是想要拥有好看的自定义主题，"主题生成器"是个不错的选择。

注意：v0.2.6 版本开始，主题生成器已支持"深色模式"，具体可参考深色模式。

1. 生成：进入 TDesign 主题生成器，点击下方的主题生成器，在右边生成器里选择想要的颜色，点击下载。

2. 转换：此时你得到一个 theme.css 文件，将该文件放到 tdesign-component/example/shell/theme/ 文件夹下，修改该文件夹下的 css2JsonTheme.dart 为你自己的文件名、主题名和输出路径，即可得到一个 theme.json 文件。

3. 应用：将主题 JSON 加载进 TTheme，美观的自定义主题就设置完成了。

// 开启多套主题功能
TTheme.needMultiTheme();

var jsonString = await rootBundle.loadString('assets/theme.json');
var _themeData = TThemeData.fromJson('green', jsonString);
// ...
MaterialApp(
  title: 'TDesign Flutter Example',
  theme: ThemeData(
    extensions: [_themeData]
  ),
  home: MyHomePage(title: 'TDesign Flutter 组件库'),
);

深色模式

通过"主题生成器"生成的主题配置文件，默认支持暗色模式相关色值。

// 开启多套主题功能
TTheme.needMultiTheme();
// ...
// MaterialApp 中设置三个属性如下，如果有自定义主题属性，可以通过 copyWith() 方法修改。
// 注：主题切换需要业务自己实现，比如使用 Provider，具体可参考 tdesign-flutter/tdesign-component/example/lib/component_test/dark_test.dart
MaterialApp(
  theme: _themeData.systemThemeDataLight,
  darkTheme: _themeData.systemThemeDataDark,
  themeMode: themeModeProvider.themeMode,
  // ...
)

🌍 国际化

TDesign Flutter 组件库内部不内置国际化语言，但支持与 Flutter 的国际化能力搭配使用。可以继承 TResourceDelegate 类，该类抽离了组件内部所有文字资源，重写获取文字的方法进行国际化处理，并通过 TTheme.setResourceBuilder 注入。

快速配置

1. 重写 TResourceDelegate 类：

/// 国际化资源代理
class IntlResourceDelegate extends TResourceDelegate {
  IntlResourceDelegate(this.context);

  BuildContext context;

  /// 国际化需要每次更新 context
  updateContext(BuildContext context) {
    this.context = context;
  }

  @override
  String get cancel => AppLocalizations.of(context)!.cancel;

  @override
  String get confirm => AppLocalizations.of(context)!.confirm;
}

2. 注入 TResourceDelegate 类：

var delegate = IntlResourceDelegate(context);
return MaterialApp(
  home: Builder(
    builder: (context) {
      // 设置文案代理，国际化需要在 MaterialApp 初始化完成之后才生效，而且需要每次更新 context
      TTheme.setResourceBuilder((context) => delegate..updateContext(context), needAlwaysBuild: true);
      return MyHomePage(
        title: AppLocalizations.of(context)?.components ?? '',
      );
    },
  ),
  // 设置国际化处理
  locale: locale,
  supportedLocales: AppLocalizations.supportedLocales,
  localizationsDelegates: AppLocalizations.localizationsDelegates,
);

3. Flutter 国际化配置方法，请参阅官方文档：Flutter 应用里的国际化

❓ 常见问题

文本居中

• v0.1.4 版本：Flutter 3.16 之后，修改了渲染引擎，导致启用 forceVerticalCenter 参数的组件字体偏移更多，不再居中。可以通过设置 kTextForceVerticalCenterEnable=false 来禁用字体居中功能，让组件显示与官方 Text 一致。

• v0.1.5 版本：适配了 Android 和 iOS 双端基础系统字体的中文居中，其他语言的字体，可以通过重写 TTextPaddingConfig 的 paddingRate 和 paddingExtraRate 进行自定义适配，TTextPaddingConfig 使用方法可参考 TTextPage。

🔗 更多示例

更多使用示例请参考 example/lib/page/

🌐 TDesign 组件库

TDesign 还提供其他平台和框架的组件库：

平台	仓库
Vue 2.x	tdesign-vue
Vue 3.x	tdesign-vue-next
React	tdesign-react
Vue 3.x 移动端	tdesign-mobile-vue
React 移动端	tdesign-mobile-react
微信小程序	tdesign-miniprogram

🤝 参与贡献

欢迎贡献代码！请在提交 Pull Request 前阅读贡献指南。

💬 交流反馈

创建 GitHub Issues 或扫描二维码加入用户群：

🙏 致谢

TDesign Flutter 依赖以下组件库，感谢作者的开源贡献：

• easy_refresh
• flutter_swiper
• flutter_slidable
• image_picker

📄 开源协议

TDesign Flutter 遵循 MIT 协议。