AppFlowy UIAppFlowy 的 Flutter 设计系统组件库与主题架构实践【免费下载链接】AppFlowyBring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.项目地址: https://gitcode.com/GitHub_Trending/ap/AppFlowyAppFlowy UIappflowy_ui是 AppFlowy 前端仓库中的一个独立 Flutter 包它把 AppFlowy 客户端的视觉语言沉淀为一套可复用的设计系统组件与主题数据模型。本文以 appflowy_ui 包 README 为主线结合其源码实现讲清楚这个组件库包含哪些组件、主题数据如何组织与分发以及如何从设计 Tokens 自动生成主题代码帮助你在 AppFlowy 之外复用它、或者理解 AppFlowy 客户端 UI 一致性的底层保障。包定位与安装方式README 对包的定位非常明确AppFlowy UI 是一个 Flutter package提供遵循 AppFlowy 设计系统的一组成可复用组件目标是保持一致consistent、可访问accessible且易用easy to use。两大核心特性Design System ComponentsButton、TextField 等遵循 AppFlowy 设计系统的组件Theming所有组件共享一致的主题能力支持亮色与暗色模式。安装在 Flutter 工程的pubspec.yaml中加入依赖即可dependencies: appflowy_ui: ^1.0.0对照 pubspec.yaml包当前版本正是1.0.0环境要求为 Dart SDK^3.6.2、Flutter1.17.0。它的运行依赖很轻量cached_network_image头像等网络图片、flutter_animate动画其余均来自 Flutter SDK。组件支持清单README 用 checklist 的形式列出了规划中的组件范围其中已交付的勾选与规划中的未勾选一目了然ButtonTextFieldAvatarCheckboxGridLinkLoading Progress IndicatorMenuMessage BoxNavigation BarPopoverScroll BarTab BarToggleTooltip值得注意的一点是从源码结构看实际交付的组件已经超出 README 勾选范围。component.dart 所在目录 下不仅有button、textfield还有avatar、dropdown_menu、menu、modal、popover、separator等实现目录——也就是说 Avatar、Menu、Popover 在代码中已有对应实现README 的清单更多反映的是“设计系统组件化进度”的口径。包的全部公开 API 通过 appflowy_ui.dart 统一导出仅三行export src/component/component.dart; export src/theme/data/appflowy_default/primitive.dart; export src/theme/theme.dart;即对外只暴露组件、Primitive 色板和主题三大入口实现细节全部内聚在src下。README 末尾还给出了 Figma 设计源文件的参考链接组件的视觉规格可对照设计稿理解。主题系统AppFlowyThemeData 的数据模型README 提到的 “Consistent theming across all components” 在源码中落为三层结构Token 定义 → 主题数据对象 → 继承式主题分发。AppFlowyThemeData一份完整的设计令牌集合theme_data.dart 中的AppFlowyThemeData定义了设计系统的数据结构也是所有子组件可访问的数据源。它有 14 个必填字段覆盖文本textColorScheme颜色、textStyle字体样式图标iconColorScheme边框borderColorScheme背景/填充/表面backgroundColorScheme、fillColorScheme、surfaceColorScheme几何与投影borderRadius、spacing、shadow品牌与语义色brandColorScheme、surfaceContainerColorScheme、badgeColorScheme、otherColorsColorScheme颜色方案按语义维度拆分为 10 个 Scheme见 color_scheme.dart 的导出清单backgroundColorScheme、badgeColorScheme、borderColorScheme、brandColorScheme、fillColorScheme、iconColorScheme、otherColorScheme、surfaceColorScheme、surfaceContainerColorScheme、textColorScheme。这种命名方式让组件代码里出现的是“语义”而不是具体色值。类还提供了静态lerp方法对各颜色方案做逐字段插值textStyle、borderRadius、spacing、shadow在过渡中直接取目标值这是主题切换动画的基础。AppFlowyThemeInheritedTheme 式分发appflowy_theme.dart 中的AppFlowyTheme是主题在 widget 树上的入口仿照 Flutter 官方Theme的实现模式AppFlowyTheme(data: ..., child: ...)将主题数据注入子树内部通过AppFlowyInheritedTheme一个InheritedTheme实现继承分发updateShouldNotify依据themeData ! oldWidget.themeData决定子树是否刷新AppFlowyTheme.of(context)同步获取主题找不到祖先时抛出带详细指引的FlutterErrorAppFlowyTheme.maybeOf(context)可空版本AnimatedAppFlowyTheme配合AppFlowyThemeDataTween做隐式动画默认过渡时长为kThemeAnimationDuration即亮/暗模式切换时颜色可以逐帧插值。AppFlowyThemeBuilder亮暗双主题的抽象AppFlowyThemeData文件末尾定义了抽象类AppFlowyThemeBuilder要求实现light({String? fontFamily})与dark({String? fontFamily})两个方法——每个内置主题必须成对提供亮暗两套数据且支持按品牌覆盖字体族。内置默认主题由脚本从 Tokens 自动生成内置主题入口是 built_in_themes.dart它只有一行导出指向AppFlowyDefaultThemesemantic.dart。该文件头部有明确的注释// AUTO-GENERATED - DO NOT EDIT DIRECTLY // This file is auto-generated by the generate_theme.dart script // To modify these colors, edit the source JSON files and run the script: // dart run script/generate_theme.dart也就是说默认主题不是手写的而是从设计 Tokens 生成。生成链路涉及 script 目录 下的三个 W3C Design Tokens 格式 JSONPrimitive.Mode 1.tokens.json、Semantic.Light Mode.tokens.json、Semantic.Dark Mode.tokens.json。生成产物分两层AppFlowyPrimitiveTokensprimitive.dart原子色板如neutral1000、blue600、red700AppFlowyDefaultTheme语义映射层在light()中把语义槽位绑定到原子色板。例如亮色模式下AppFlowyTextColorScheme的映射为final textColorScheme AppFlowyTextColorScheme( primary: AppFlowyPrimitiveTokens.neutral1000, secondary: AppFlowyPrimitiveTokens.neutral600, tertiary: AppFlowyPrimitiveTokens.neutral500, action: AppFlowyPrimitiveTokens.blue600, actionHover: AppFlowyPrimitiveTokens.blue700, success: AppFlowyPrimitiveTokens.green600, warning: AppFlowyPrimitiveTokens.orange600, error: AppFlowyPrimitiveTokens.red600, // ... 其余语义槽位 );这套 “Primitive → Semantic → ThemeData” 的三层 Tokens 架构是典型的设计系统工程实践设计师改 JSON、跑dart run script/generate_theme.dart重新生成组件代码永远只引用语义名无需改动。此外custom_theme.dart 提供了CustomTheme支持从 JSON 数据构造自定义主题供白牌white-label或品牌定制场景使用——这与 AppFlowy 仓库中 white_label 脚本 的产品线相呼应。组件实现以 Button 与 TextField 为例ButtonBase 工厂方法的家族结构Button 在 button 目录 下按视觉变体分子目录base_button、filled_button、ghost_button、outlined_button每个变体又细分为图标文字按钮与纯文字按钮如filled_icon_text_button.dart、ghost_text_button.dart。以 filled_button.dart 为例AFFilledButton采用私有构造函数 命名工厂的模式把“视觉变体”固化为 API 语义typedef AFFilledButtonWidgetBuilder Widget Function( BuildContext context, bool isHovering, bool disabled, ); class AFFilledButton extends StatelessWidget { const AFFilledButton._({ ... }); /// Primary text button. factory AFFilledButton.primary({ required AFFilledButtonWidgetBuilder builder, required VoidCallback onTap, AFButtonSize size AFButtonSize.m, EdgeInsetsGeometry? padding, double? borderRadius, bool disabled false, }) { return AFFilledButton._( // ... backgroundColor: (context, isHovering, disabled) { if (disabled) return AppFlowyTheme.of(context).fillColorScheme.contentHover; if (isHovering) return AppFlowyTheme.of(context).fillColorScheme.themeThickHover; return AppFlowyTheme.of(context).fillColorScheme.themeThick; }, ); } /// Destructive text button. factory AFFilledButton.destructive({ ... }) { /* errorThick / errorThickHover */ } }三个值得注意的设计点背景色是函数而非常量backgroundColor是(context, isHovering, disabled)三元回调把 disabled/hover/normal 三态颜色决策写进工厂方法且三态颜色全部来自fillColorScheme的语义槽位themeThick/themeThickHover/contentHover主题切换时自动跟随无需组件感知亮暗模式尺寸与几何从主题取padding ?? size.buildPadding(context)、borderRadius ?? size.buildBorderRadius(context)即AFButtonSize的默认内边距与圆角由主题数据推导最终都收敛到AFBaseButton统一处理点击、hover、边框与内容构建变体之间只贡献颜色策略。TextField内置校验、错误态与密文切换textfield.dart 中的AFTextField在 Flutter 原生TextField之上封装了完整的状态能力尺寸枚举AFTextFieldSize提供m、l两档各自的contentPadding与borderRadius由主题数据计算如m档圆角取theme.borderRadius.ml档固定 10.0 并配 10.0 垂直内边距校验协议validator返回(bool result, String errorText)记录状态类监听 controller 变化自动触发_validate出错时把边框切到borderColorScheme.errorThick并在字段下方用caption文本样式 textColorScheme.error显示错误信息错误与密文的外部同步 APIAFTextFieldState是抽象基类暴露syncError、clearError、syncObscured三个无默认副作用的方法宿主如登录表单拿到 State 后可主动设置错误态或切换密码可见性完整边框状态机border/enabledBorder/focusedBorder/errorBorder/focusedErrorBorder五态边框逐一构造聚焦色取borderColorScheme.themeThickhover 背景取borderColorScheme.primaryHovermaxLength使用MaxLengthEnforcement.truncateAfterCompositionEnds保证中文等组合字符输入不被截断。在示例工程中查看组件包内自带一个 macOS 桌面示例工程 example/其lib/src下按组件分目录组织展示页buttons/buttons_page.dart、textfield/textfield_page.dart、avatar/avatar_page.dart、menu/menu_page.dart、dropdown_menu/dropdown_menu_page.dart、modal/modal_page.dart。运行示例工程是快速查看各组件在各状态正常、hover、禁用、错误下视觉表现的最低成本方式cd frontend/appflowy_flutter/packages/appflowy_ui/example flutter pub get flutter run -d macos小结与延伸阅读AppFlowy UI 的 README 虽然篇幅不长但它勾勒出的“组件清单 主题化”两条主线在源码中都有扎实的工程支撑三层 Tokens 自动生成主题script/generate_theme.dart、语义色板驱动的组件实现button 家族、AFTextField、InheritedThemelerp的平滑主题切换appflowy_theme.dart。如果你要在 AppFlowy 主工程中新增 UI优先复用此包的组件与AppFlowyTheme.of(context)的语义令牌若要做品牌定制则可以从CustomTheme与 White Label 脚本入手。README 中标记为未勾选的 Checkbox、Menu、Popover 等组件中部分已在 component 源码目录 中落地可作为继续补齐设计系统覆盖度的起点。【免费下载链接】AppFlowyBring projects, wikis, and teams together with AI. AppFlowy is the AI collaborative workspace where you achieve more without losing control of your data. The leading open source Notion alternative.项目地址: https://gitcode.com/GitHub_Trending/ap/AppFlowy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考