ente_components 组件目录Components Catalog实战指南用独立 Flutter Catalog 应用可视化验收 ente 设计系统【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente导读ente_components是 ente 移动端Photos / Locker / Auth共用的 Flutter 组件与设计系统包。仓库中的example目录提供了一个独立可运行的Components Catalog组件目录应用把包内所有 UI 组件按分类集中展示用于在开发过程中以可视化方式逐组件验收样式、状态与交互。本文以 example/README.md 为骨架结合 example/lib/main.dart约 4200 行的完整 Catalog 实现与组件包源码讲解如何运行该 Catalog、它覆盖了哪些组件分区、每个分区的验收要点以及背后依托的设计令牌Design Tokens与主题机制帮助你把它变成一套可复用的组件验收工作流。一、Components Catalog 是什么原文档对它的定位只有一句话Standalone Flutter catalog for visually checking the component package.翻译过来即一个独立的 Flutter Catalog 应用专门用于可视化检查组件包。它不依赖任何业务 App只依赖ente_components包本身因此可以脱离 Photos / Locker / Auth 任意一个具体产品独立构建、独立运行。它的用途是在组件开发过程中快速预览每个组件在不同状态下的表现默认、选中、加载、成功、错误、禁用等在同一块画布上并排对比同一组件的多个变体variants验证深浅色主题下的色彩与可读性作为新组件合入前的“人工冒烟测试”入口。从工程结构看Catalog 应用是一个标准的 Flutter 应用入口在 example/lib/main.dart工程声明在 example/pubspec.yaml并带有完整的 Androidexample/android/与 iOSexample/ios/宿主工程。二、工程结构与依赖配置Catalog 应用名为ente_components_catalog其 pubspec.yaml 核心配置如下name: ente_components_catalog description: Visual catalog for the mobile component package. resolution: workspace environment: sdk: 3.10.0 4.0.0 flutter: 3.44.0 dependencies: ente_components: path: .. flutter: sdk: flutter hugeicons: 1.1.7 dev_dependencies: flutter_lints: 6.0.0 flutter_test: sdk: flutter flutter: uses-material-design: true assets: - assets/warning-grey.png几点值得注意ente_components通过path: ..引用Catalog 与组件包位于同一仓库resolution: workspace表示它参与移动端 workspace 统一解析与 mobile/pubspec.yaml 对应。SDK 约束要求 Dart SDK3.10.0 4.0.0、Flutter3.44.0说明 Catalog 大量使用了较新的 Dart 语言特性如 record、pattern switch。图标依赖hugeicons: 1.1.7Catalog 里所有菜单、按钮、警示图标都来自 HugeIcons 图标集这也是ente_components组件对外部图标的唯一强依赖。唯一的资源文件assets/warning-grey.png它被用在错误 Bottom Sheet 的警示插画中见 main.dart而非业务资源进一步印证 Catalog 的“轻量独立”定位。运行方式与普通 Flutter 应用一致在example目录下执行flutter pub get flutter run # 选择 Android / iOS 设备或模拟器也可以直接用 IDE 打开example目录运行main()见 main.dart。三、应用骨架入口、主题与全局交互3.1 入口与主题接线main()直接运行ComponentsCatalogAppmain.dart。该组件通过MaterialApp同时注入浅色与深色两套主题并把主题模式提升到应用级状态main.dartreturn MaterialApp( debugShowCheckedModeBanner: false, title: Components, theme: ComponentTheme.lightTheme(app: _appTheme), darkTheme: ComponentTheme.darkTheme(app: _appTheme), themeMode: _themeMode, home: CatalogHome(...), );这里的ComponentTheme来自组件包 lib/theme/theme.dart它基于 Material 3 构建useMaterial3: true、ColorScheme.fromSeed(seedColor: colors.primary, ...)并把 ente 的自定义色板通过ThemeExtensionComponentColorTokens挂进ThemeData.extensions。业务代码可以通过扩展属性context.componentColors直接取色extension ThemeContext on BuildContext { ColorTokens get componentColors ComponentTheme.colorsOf(this); }3.2 快速切换主题AppBar 按钮与双击手势Catalog 提供了两种切换主题的交互这在验收深浅色样式时非常实用AppBar 右上角的主题循环按钮_CatalogThemeCycleButtonmain.dart在 Light / Dark以及 System 视为 Light之间循环按钮 tooltip 会同步提示当前与下一档模式。双击空白区域循环切换 App 主题main.dart通过全局GestureBinding.pointerRouter监听PointerUpEvent在 320ms 内、48 逻辑像素范围内连续两次抬起判定为双击然后按photos → locker → auth → photos的顺序切换ComponentApp。ComponentApp是组件包里的应用枚举enum ComponentApp { photos, auth, locker }见 lib/theme/colors.dart。也就是说同一个 Catalog 可以一键切换到 Photos、Locker、Auth 三套品牌色用来确认组件在各产品主题下的表现是否符合预期。3.3 列表主页与详情页主页CatalogHome用ListView.separated渲染所有组件分区每个分区是一张MenuComponent卡片main.dart。点击后通过MaterialPageRoute进入CatalogDetailPagemain.dart详情页复用AppBarComponent作为可折叠头部标题下方以逗号拼接该分区覆盖的所有用例名例如Menu Item Default, Selected, Loading, Success, Loading only, Display only, Leading icon, ...四、组件分区总览_sections()main.dart定义了 Catalog 的全部 15 个分区每个分区都带标题、图标、用例清单和预览构建器。汇总如下分区图标覆盖用例Menu ItemUserDefault / Selected / Loading / Success / Loading only / Display only / Leading icon / No leading icon / Subtitle / No subtitle / Trailing icon / Trailing toggle / No trailing / Async state / Destructive / Long textPopup menuMoreVerticalSort menu / Leading icons / Trailing icons / Label icon / Full combo / Active state / All casesBannerAlertCircleFailure / Informative / Success / Warning / Neutral / Custom leading / Custom trailingToastCheckmarkCircleStates / Title only / Custom leading / Custom trailing / Short vs longButtonsCursorPointerButton / Icon buttonFloating action buttonAdd01Primary / Secondary / Icon / Medium / Medium with iconBottom sheetsLayoutTableHeader / Default sheet / Choice sheet / Warning sheet / Error sheet / Custom contentText inputTypeCursor单行状态、多行状态、Label、Trailing icon、Clearable、Password、Warning message、Alert message、Read only、Max lengthPIN inputLockPasswordSix-digit OTP / Obscured PIN / Error stateSelection controlsSlidersCheckbox / Radio / Switch / Slider / StepperFilter chipsFilterSelected / Unselected / Disabled / Leading icon / Trailing icon / FaceHeader app barHeadingExpanded header / Collapsed app bar / Scroll animation / Long listTooltipHelpCircleTop pointer / Tap triggerAvatarUserSizes / Seed palette / Add contactText stylesTextFontH1 / H1-Bold / H2 / Large / Body / Mini下面选取几个代表性分区深入说明 Catalog 如何“可视化验收”每个组件。五、重点分区深度解读5.1 Menu Item行组件全状态矩阵_MenuItemPreviewmain.dart是 Catalog 中用例最多的分区。_MenuItemMatrix用三重嵌套循环生成组合矩阵main.dart有无副标题 × 有无前置图标 × 尾部类型icon / toggle / none再叠加selected选中态一次铺开十余种行变体。更关键的是它演示了MenuComponent的异步执行状态_MenuItemInteractionStatesPreviewmain.dart这与组件包中的执行状态模型 lib/models/component_execution_state.dart 一一对应shouldSurfaceExecutionStates: false→ 纯点击无加载/成功 UIshouldSurfaceExecutionStates: trueonTap返回 900ms 延迟的 Future → 展示加载态后回到空闲加shouldShowSuccessConfirmation: true 120ms 快速 Future → 快速成功确认对勾动画抛异常_failAfterDelay→ 错误态自动复位到 idle并弹 SnackBarshowOnlyLoadingState: true→ 只显示加载态、不显示成功对勾。这些用例实际上就是ButtonComponent/MenuComponent在真实产品里的典型场景保存、复制恢复密钥、同步备份、删除账号等Catalog 把它们抽象成可重复点击验证的最小样例。5.2 Popup menu选项丰富度验收_PopupMenuPreviewmain.dart围绕EntePopupMenuButton与EntePopupMenuOption展开覆盖了选项的几乎所有形态Sort menu带secondaryLabel如A-Z与次级尾部小图标Leading / trailing icons前置图标用IconSizes.small尾部辅助图标用IconSizes.tinyActive stateisActive: true的选项在activeTrailingWidget位置显示主色对勾/箭头colors.primary用于表达“当前排序/选中项”Destructive危险操作Delete通过labelColor: colors.warning 红色图标表达Divider 控制showDivider: false控制分组末尾是否画分隔线。该分区还带交互反馈——每次选择都会在预览区下方更新 “Last selected: ...”方便验证onSelected回调链路main.dart。5.3 Banner 与 Toast五态反馈体系BannerComponent与showToastComponent共享同一套语义状态枚举BannerComponentStatefailure / informative / success / warning / neutralmain.dart。Banner 分区顺序铺出五个状态的 Banner 样例并提供Custom leading如加载转圈与Custom trailing如关闭图标两个自定义插槽样例点击 Banner 会触发 SnackBar 回调。Toast 分区点击按钮实时弹出 toast验证标题/副标题组合、自定义 leading/trailing以及时长差异——duration: Duration(seconds: 2)为短 toast不传则用默认 4 秒main.dart。这两个分区证明了ente_components在“反馈型 UI”上的设计一致性同一套状态色在横幅和轻提示之间完全复用。5.4 Buttons变体 × 状态矩阵_ButtonMatrixmain.dart由三块组成State transition一个真实可点的主按钮onTap返回 900ms 延迟用于观察“点击 → 加载 → 恢复”的完整动画Async actions成功900ms 后完成、错误抛StateError并弹 SnackBar、快速成功确认shouldShowSuccessConfirmation: true 120ms、关闭执行态shouldSurfaceExecutionStates: false四类异步语义Default / Disabled两组矩阵完整展示六个变体primary / secondary / neutral / critical / tertiaryCritical / linkmain.dart以及传入onTap: null时的禁用态。Icon button则用“行变体、列状态”的二维矩阵_IconButtonMatrixmain.dart六种变体primary / critical / unfilled / secondary / green / circular× 五种状态Default / Disabled / Loading / Success / Error一次性比对全部 30 个组合。这种矩阵式预览正是 Catalog “可视化验收”的高价值场景。5.5 Floating action button独立演示页FAB 分区没有内联预览previewBuilder: SizedBox.shrink()而是通过routeBuilder跳转到独立演示页FABDemoPagemain.dart。演示页内列出六种组合主/次变体 × 纯图标 / 带标签 / 中等尺寸带图标点击后进入子页面在真实的Scaffold.floatingActionButtonFloatingActionButtonLocation.centerFloat环境中观察FABComponent的挂载效果main.dart。这提醒我们FAB 这类组件必须放在真实 Scaffold 语境中验收Catalog 为此类组件预留了 route 级演示的扩展点CatalogSectionRouteBuildermain.dart。5.6 Bottom sheets默认 / 选择 / 警告 / 错误 / 自定义_BottomSheetPreviewmain.dart同时提供“点击弹出”与“内联静态帧”两种查看方式交互验收五个按钮分别触发showBottomSheetComponent默认/选择/警告/自定义与showErrorBottomSheetComponent通用错误页带warning-grey.png插画、actionLabel: Contact support静态验收通过_InlineSheetFrameConstrainedBox(maxWidth: 375)模拟手机宽度把五种 Sheet 内联渲染在页面里无需交互即可逐像素检查。自定义内容样例是一个“Share link”分享链接卡片main.dart展示了BottomSheetComponent的content插槽与actions槽位如何自由组合ButtonComponent变体primary与tertiaryCritical。5.7 Text input近 30 种形态全覆盖_TextInputPreviewmain.dart是另一个高密度分区覆盖状态Normal / Focused / Error / Submit error / Success / Disabled / Read only结构Label / No label / RequiredisRequired: true/ Helper text普通message/ Alert messageTextInputComponentMessageType.alert插槽Prefix icon / Trailing icon / 前缀尾缀组合能力ClearableisClearable: true、PasswordisPasswordInput: trueautofillHints: [AutofillHints.password]、Max lengthmaxLength: 12 全大写textCapitalization: TextCapitalization.characters多行label trailing warning、label only、no label、focused、error、success、disabled 等七种多行组合。其中Submit error用例演示了submitNotifier: ValueNotifierint的外部提交机制点击外部 “Submit” 按钮递增 notifier 即可触发输入框的提交校验而onSubmit抛出异常则进入错误态main.dart——这正好对应真实登录/验证码场景的“提交失败保留输入”体验。5.8 PIN inputOTP 与 PIN 专项_PinInputPreviewmain.dart专项验收PinInputComponent六位 OTPautofocus: trueautofillHints: [AutofillHints.oneTimeCode] 语义标签四位混淆 PINlength: 4obscureText: true错误态isError: true用于验证输错 PIN 时输入框的警示表现。这个分区直接对应用户产品里 2FA 验证码、App 锁 PIN 的输入体验。5.9 Selection controlsCheckbox / Radio / Switch / Slider / Stepper_SelectionPreviewmain.dart用LabeledControlComponent包裹三种布尔控件并提供启用/禁用两套展示随后是连续值控件SliderComponent交互态与禁用态onChanged: nullStepperComponent支持min/max边界并在极限值0 和 5下验证按钮禁用逻辑。5.10 Filter chips选中 / 未选 / 禁用与 Face 头像_FilterChipPreviewmain.dart分为Editable可交互的 chips用SetString维护多选状态每个 chip 可带leading星标、trailing视频图标或avatar人脸头像StatesFilterChipComponentState.selected / unselected / disabled三态并排Icons前置图标Albums/Shared/Archived与尾部图标Recent/Places/Hidden两种插槽 × 三态Faces基于AvatarComponent.seeded的人脸头像 chips模拟相册人脸筛选的真实场景。5.11 Header app bar固定头部 长列表滚动HeaderAppBarDemoPagemain.dart构建了一个 48 行、带长标题一长串邮箱地址的演示页用于验证AppBarComponent的固定pinned动画头部展开 → 折叠的滚动动画长标题省略与“点击标题弹出完整内容”的 reveal 行为disableTitleTapReveal可关闭该行为用 FilterChip 切换列表行覆盖副标题有无、前置图有无、尾部按钮/箭头、主色标题titleColor: colors.primary等变体。5.12 Tooltip 与 AvatarTooltip 分区main.dart验证TooltipComponent的顶部指针气泡以及短/中/长文本的换行、maxWidth上限与超长省略三行后 ellipsizeAvatar 分区main.dart用“颜色 × 尺寸”表格验收 6 种尺寸xs / small / defaultSize / medium / large / contactHuge× 7 种颜色并展示AvatarComponent.seeded种子色板由avatarLight列表驱动与AvatarComponent.icon“添加联系人”加号头像。5.13 Text styles字阶验收_TextStylesPreviewmain.dart以统一文案 “Secure backup is ready” 顺序铺出TextStyles的六个字阶每个样例下方标注字号/行高/字重Token规格来自预览标注H120 / 28 / BoldH218 / 24 / Semi BoldLarge16 / 20 / Semi BoldBody14 / 20 / MediumMini12 / 16 / MediumTiny10 / 12 / Medium这些 token 与组件包 lib/theme/text_styles.dart 对应并被ComponentTheme._theme映射进 MaterialTextTheme见 lib/theme/theme.dart。六、内置“设置页” Demo组件在真实页面中的组合Catalog 还在抽屉CatalogSettingsDrawermain.dart里内置了一组仿真实 App 的设置页 Demo用于验证多个组件组合成完整页面时的表现Accountmain.dartChange email / Recovery key / Change password / Delete account红色警示行SecurityEmail verification带ToggleSwitchComponent实时切换、Passkey、App lock、Active sessionsAppearance三选一的主题选项选中项显示主色对勾GeneralLanguage 行、Show large icons、Compact mode、Hide codesToggleSwitch 组合Help and supportContact support / Help / Suggest features / Report a bugAboutOpen source / Privacy / Terms of service / Check for updates页脚显示 “Version 1.0.0”。这些页面全部复用AppBarComponentMenuComponentMenuGroupComponentToggleSwitchComponent是“组件如何组装成真实功能页”的现成参考样例。七、底层支撑组件包结构与设计令牌Catalog 只是入口被验收的组件都来自组件包ente_components。包内结构见 lib/按功能划分为components/30 余个组件实现包括menu_component.dart、banner_component.dart、toast_component.dart、buttons/button_component.dart、bottom_sheet/bottom_sheet_component.dart、text_input_component.dart、pin_input_component.dart、filter_chip_component.dart、app_bar_component.dart、avatar_component.dart、tooltip_component.dart、selection_controls/等统一由 lib/ente_components.dart 导出theme/设计令牌包括colors.dartColorTokensComponentApp枚举、text_styles.dart、spacing.dart、icon_sizes.dart、radii.dart、shadows.dart、motion.dart与theme.dartComponentThemeComponentColorTokensmodels/component_execution_state.dart异步执行状态模型驱动前面反复提到的 loading/success/error 表现。ColorTokens是一个近 70 个字段的色彩令牌集lib/theme/colors.dart覆盖主色系primaryLight→primaryDarker、功能色green*、blue*、purple*、warning*、caution*、文本色阶textLightest→textDarker、textReverse、背景填充backgroundBase、fillLight→fillDarkest、描边与特殊色specialWhite、specialScrim等。ComponentTheme.themeForApp(app, brightness:)会根据ComponentApp与明暗模式取出对应色板并生成 Material 3 主题——这正是 Catalog 双击切换三套产品主题的实现基础。八、把 Catalog 变成你的组件验收工作流结合以上分析可以把这套 Catalog 固化为日常开发习惯新增/修改组件后在对应分区确认所有状态尤其是 loading / success / error / disabled 四态与变体组合先在静态帧中检查再通过交互用例点击验证深浅色双验收使用 AppBar 主题按钮或双击手势分别以 light / dark 模式过一遍改动分区三产品主题覆盖双击循环切换photos / locker / auth三套ComponentApp主题确认品牌色替换如colors.primary、colors.warning没有破坏可读性页面级组合验收对涉及多组件拼装的改动参考内置 Settings / Header app bar / FAB 演示页验证组件在真实Scaffold、滚动与导航语境中的表现异步行为回归用shouldSurfaceExecutionStates/shouldShowSuccessConfirmation等开关组合回归按钮与菜单行的执行态动画。结语ente_components/example这个“仅有 3 行 README”的 Catalog 应用实际承载了 ente 设计系统最完整的可视化验收面15 个组件分区、数百个状态与变体用例、三套产品主题与深浅色全覆盖。对组件使用者而言它是学习每个组件 API 与最佳实践的活文档对组件维护者而言它是合并代码前的标准冒烟工具。结合组件包 lib/ 的设计令牌与执行状态模型开发者可以完全在 Flutter 本地工程中完成从“看效果”到“查实现”的闭环。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ente_components 组件目录（Components Catalog）实战指南：用独立 Flutter Catalog 应用可视化验收 ente 设计系统
ente_components 组件目录Components Catalog实战指南用独立 Flutter Catalog 应用可视化验收 ente 设计系统【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente导读ente_components是 ente 移动端Photos / Locker / Auth共用的 Flutter 组件与设计系统包。仓库中的example目录提供了一个独立可运行的Components Catalog组件目录应用把包内所有 UI 组件按分类集中展示用于在开发过程中以可视化方式逐组件验收样式、状态与交互。本文以 example/README.md 为骨架结合 example/lib/main.dart约 4200 行的完整 Catalog 实现与组件包源码讲解如何运行该 Catalog、它覆盖了哪些组件分区、每个分区的验收要点以及背后依托的设计令牌Design Tokens与主题机制帮助你把它变成一套可复用的组件验收工作流。一、Components Catalog 是什么原文档对它的定位只有一句话Standalone Flutter catalog for visually checking the component package.翻译过来即一个独立的 Flutter Catalog 应用专门用于可视化检查组件包。它不依赖任何业务 App只依赖ente_components包本身因此可以脱离 Photos / Locker / Auth 任意一个具体产品独立构建、独立运行。它的用途是在组件开发过程中快速预览每个组件在不同状态下的表现默认、选中、加载、成功、错误、禁用等在同一块画布上并排对比同一组件的多个变体variants验证深浅色主题下的色彩与可读性作为新组件合入前的“人工冒烟测试”入口。从工程结构看Catalog 应用是一个标准的 Flutter 应用入口在 example/lib/main.dart工程声明在 example/pubspec.yaml并带有完整的 Androidexample/android/与 iOSexample/ios/宿主工程。二、工程结构与依赖配置Catalog 应用名为ente_components_catalog其 pubspec.yaml 核心配置如下name: ente_components_catalog description: Visual catalog for the mobile component package. resolution: workspace environment: sdk: 3.10.0 4.0.0 flutter: 3.44.0 dependencies: ente_components: path: .. flutter: sdk: flutter hugeicons: 1.1.7 dev_dependencies: flutter_lints: 6.0.0 flutter_test: sdk: flutter flutter: uses-material-design: true assets: - assets/warning-grey.png几点值得注意ente_components通过path: ..引用Catalog 与组件包位于同一仓库resolution: workspace表示它参与移动端 workspace 统一解析与 mobile/pubspec.yaml 对应。SDK 约束要求 Dart SDK3.10.0 4.0.0、Flutter3.44.0说明 Catalog 大量使用了较新的 Dart 语言特性如 record、pattern switch。图标依赖hugeicons: 1.1.7Catalog 里所有菜单、按钮、警示图标都来自 HugeIcons 图标集这也是ente_components组件对外部图标的唯一强依赖。唯一的资源文件assets/warning-grey.png它被用在错误 Bottom Sheet 的警示插画中见 main.dart而非业务资源进一步印证 Catalog 的“轻量独立”定位。运行方式与普通 Flutter 应用一致在example目录下执行flutter pub get flutter run # 选择 Android / iOS 设备或模拟器也可以直接用 IDE 打开example目录运行main()见 main.dart。三、应用骨架入口、主题与全局交互3.1 入口与主题接线main()直接运行ComponentsCatalogAppmain.dart。该组件通过MaterialApp同时注入浅色与深色两套主题并把主题模式提升到应用级状态main.dartreturn MaterialApp( debugShowCheckedModeBanner: false, title: Components, theme: ComponentTheme.lightTheme(app: _appTheme), darkTheme: ComponentTheme.darkTheme(app: _appTheme), themeMode: _themeMode, home: CatalogHome(...), );这里的ComponentTheme来自组件包 lib/theme/theme.dart它基于 Material 3 构建useMaterial3: true、ColorScheme.fromSeed(seedColor: colors.primary, ...)并把 ente 的自定义色板通过ThemeExtensionComponentColorTokens挂进ThemeData.extensions。业务代码可以通过扩展属性context.componentColors直接取色extension ThemeContext on BuildContext { ColorTokens get componentColors ComponentTheme.colorsOf(this); }3.2 快速切换主题AppBar 按钮与双击手势Catalog 提供了两种切换主题的交互这在验收深浅色样式时非常实用AppBar 右上角的主题循环按钮_CatalogThemeCycleButtonmain.dart在 Light / Dark以及 System 视为 Light之间循环按钮 tooltip 会同步提示当前与下一档模式。双击空白区域循环切换 App 主题main.dart通过全局GestureBinding.pointerRouter监听PointerUpEvent在 320ms 内、48 逻辑像素范围内连续两次抬起判定为双击然后按photos → locker → auth → photos的顺序切换ComponentApp。ComponentApp是组件包里的应用枚举enum ComponentApp { photos, auth, locker }见 lib/theme/colors.dart。也就是说同一个 Catalog 可以一键切换到 Photos、Locker、Auth 三套品牌色用来确认组件在各产品主题下的表现是否符合预期。3.3 列表主页与详情页主页CatalogHome用ListView.separated渲染所有组件分区每个分区是一张MenuComponent卡片main.dart。点击后通过MaterialPageRoute进入CatalogDetailPagemain.dart详情页复用AppBarComponent作为可折叠头部标题下方以逗号拼接该分区覆盖的所有用例名例如Menu Item Default, Selected, Loading, Success, Loading only, Display only, Leading icon, ...四、组件分区总览_sections()main.dart定义了 Catalog 的全部 15 个分区每个分区都带标题、图标、用例清单和预览构建器。汇总如下分区图标覆盖用例Menu ItemUserDefault / Selected / Loading / Success / Loading only / Display only / Leading icon / No leading icon / Subtitle / No subtitle / Trailing icon / Trailing toggle / No trailing / Async state / Destructive / Long textPopup menuMoreVerticalSort menu / Leading icons / Trailing icons / Label icon / Full combo / Active state / All casesBannerAlertCircleFailure / Informative / Success / Warning / Neutral / Custom leading / Custom trailingToastCheckmarkCircleStates / Title only / Custom leading / Custom trailing / Short vs longButtonsCursorPointerButton / Icon buttonFloating action buttonAdd01Primary / Secondary / Icon / Medium / Medium with iconBottom sheetsLayoutTableHeader / Default sheet / Choice sheet / Warning sheet / Error sheet / Custom contentText inputTypeCursor单行状态、多行状态、Label、Trailing icon、Clearable、Password、Warning message、Alert message、Read only、Max lengthPIN inputLockPasswordSix-digit OTP / Obscured PIN / Error stateSelection controlsSlidersCheckbox / Radio / Switch / Slider / StepperFilter chipsFilterSelected / Unselected / Disabled / Leading icon / Trailing icon / FaceHeader app barHeadingExpanded header / Collapsed app bar / Scroll animation / Long listTooltipHelpCircleTop pointer / Tap triggerAvatarUserSizes / Seed palette / Add contactText stylesTextFontH1 / H1-Bold / H2 / Large / Body / Mini下面选取几个代表性分区深入说明 Catalog 如何“可视化验收”每个组件。五、重点分区深度解读5.1 Menu Item行组件全状态矩阵_MenuItemPreviewmain.dart是 Catalog 中用例最多的分区。_MenuItemMatrix用三重嵌套循环生成组合矩阵main.dart有无副标题 × 有无前置图标 × 尾部类型icon / toggle / none再叠加selected选中态一次铺开十余种行变体。更关键的是它演示了MenuComponent的异步执行状态_MenuItemInteractionStatesPreviewmain.dart这与组件包中的执行状态模型 lib/models/component_execution_state.dart 一一对应shouldSurfaceExecutionStates: false→ 纯点击无加载/成功 UIshouldSurfaceExecutionStates: trueonTap返回 900ms 延迟的 Future → 展示加载态后回到空闲加shouldShowSuccessConfirmation: true 120ms 快速 Future → 快速成功确认对勾动画抛异常_failAfterDelay→ 错误态自动复位到 idle并弹 SnackBarshowOnlyLoadingState: true→ 只显示加载态、不显示成功对勾。这些用例实际上就是ButtonComponent/MenuComponent在真实产品里的典型场景保存、复制恢复密钥、同步备份、删除账号等Catalog 把它们抽象成可重复点击验证的最小样例。5.2 Popup menu选项丰富度验收_PopupMenuPreviewmain.dart围绕EntePopupMenuButton与EntePopupMenuOption展开覆盖了选项的几乎所有形态Sort menu带secondaryLabel如A-Z与次级尾部小图标Leading / trailing icons前置图标用IconSizes.small尾部辅助图标用IconSizes.tinyActive stateisActive: true的选项在activeTrailingWidget位置显示主色对勾/箭头colors.primary用于表达“当前排序/选中项”Destructive危险操作Delete通过labelColor: colors.warning 红色图标表达Divider 控制showDivider: false控制分组末尾是否画分隔线。该分区还带交互反馈——每次选择都会在预览区下方更新 “Last selected: ...”方便验证onSelected回调链路main.dart。5.3 Banner 与 Toast五态反馈体系BannerComponent与showToastComponent共享同一套语义状态枚举BannerComponentStatefailure / informative / success / warning / neutralmain.dart。Banner 分区顺序铺出五个状态的 Banner 样例并提供Custom leading如加载转圈与Custom trailing如关闭图标两个自定义插槽样例点击 Banner 会触发 SnackBar 回调。Toast 分区点击按钮实时弹出 toast验证标题/副标题组合、自定义 leading/trailing以及时长差异——duration: Duration(seconds: 2)为短 toast不传则用默认 4 秒main.dart。这两个分区证明了ente_components在“反馈型 UI”上的设计一致性同一套状态色在横幅和轻提示之间完全复用。5.4 Buttons变体 × 状态矩阵_ButtonMatrixmain.dart由三块组成State transition一个真实可点的主按钮onTap返回 900ms 延迟用于观察“点击 → 加载 → 恢复”的完整动画Async actions成功900ms 后完成、错误抛StateError并弹 SnackBar、快速成功确认shouldShowSuccessConfirmation: true 120ms、关闭执行态shouldSurfaceExecutionStates: false四类异步语义Default / Disabled两组矩阵完整展示六个变体primary / secondary / neutral / critical / tertiaryCritical / linkmain.dart以及传入onTap: null时的禁用态。Icon button则用“行变体、列状态”的二维矩阵_IconButtonMatrixmain.dart六种变体primary / critical / unfilled / secondary / green / circular× 五种状态Default / Disabled / Loading / Success / Error一次性比对全部 30 个组合。这种矩阵式预览正是 Catalog “可视化验收”的高价值场景。5.5 Floating action button独立演示页FAB 分区没有内联预览previewBuilder: SizedBox.shrink()而是通过routeBuilder跳转到独立演示页FABDemoPagemain.dart。演示页内列出六种组合主/次变体 × 纯图标 / 带标签 / 中等尺寸带图标点击后进入子页面在真实的Scaffold.floatingActionButtonFloatingActionButtonLocation.centerFloat环境中观察FABComponent的挂载效果main.dart。这提醒我们FAB 这类组件必须放在真实 Scaffold 语境中验收Catalog 为此类组件预留了 route 级演示的扩展点CatalogSectionRouteBuildermain.dart。5.6 Bottom sheets默认 / 选择 / 警告 / 错误 / 自定义_BottomSheetPreviewmain.dart同时提供“点击弹出”与“内联静态帧”两种查看方式交互验收五个按钮分别触发showBottomSheetComponent默认/选择/警告/自定义与showErrorBottomSheetComponent通用错误页带warning-grey.png插画、actionLabel: Contact support静态验收通过_InlineSheetFrameConstrainedBox(maxWidth: 375)模拟手机宽度把五种 Sheet 内联渲染在页面里无需交互即可逐像素检查。自定义内容样例是一个“Share link”分享链接卡片main.dart展示了BottomSheetComponent的content插槽与actions槽位如何自由组合ButtonComponent变体primary与tertiaryCritical。5.7 Text input近 30 种形态全覆盖_TextInputPreviewmain.dart是另一个高密度分区覆盖状态Normal / Focused / Error / Submit error / Success / Disabled / Read only结构Label / No label / RequiredisRequired: true/ Helper text普通message/ Alert messageTextInputComponentMessageType.alert插槽Prefix icon / Trailing icon / 前缀尾缀组合能力ClearableisClearable: true、PasswordisPasswordInput: trueautofillHints: [AutofillHints.password]、Max lengthmaxLength: 12 全大写textCapitalization: TextCapitalization.characters多行label trailing warning、label only、no label、focused、error、success、disabled 等七种多行组合。其中Submit error用例演示了submitNotifier: ValueNotifierint的外部提交机制点击外部 “Submit” 按钮递增 notifier 即可触发输入框的提交校验而onSubmit抛出异常则进入错误态main.dart——这正好对应真实登录/验证码场景的“提交失败保留输入”体验。5.8 PIN inputOTP 与 PIN 专项_PinInputPreviewmain.dart专项验收PinInputComponent六位 OTPautofocus: trueautofillHints: [AutofillHints.oneTimeCode] 语义标签四位混淆 PINlength: 4obscureText: true错误态isError: true用于验证输错 PIN 时输入框的警示表现。这个分区直接对应用户产品里 2FA 验证码、App 锁 PIN 的输入体验。5.9 Selection controlsCheckbox / Radio / Switch / Slider / Stepper_SelectionPreviewmain.dart用LabeledControlComponent包裹三种布尔控件并提供启用/禁用两套展示随后是连续值控件SliderComponent交互态与禁用态onChanged: nullStepperComponent支持min/max边界并在极限值0 和 5下验证按钮禁用逻辑。5.10 Filter chips选中 / 未选 / 禁用与 Face 头像_FilterChipPreviewmain.dart分为Editable可交互的 chips用SetString维护多选状态每个 chip 可带leading星标、trailing视频图标或avatar人脸头像StatesFilterChipComponentState.selected / unselected / disabled三态并排Icons前置图标Albums/Shared/Archived与尾部图标Recent/Places/Hidden两种插槽 × 三态Faces基于AvatarComponent.seeded的人脸头像 chips模拟相册人脸筛选的真实场景。5.11 Header app bar固定头部 长列表滚动HeaderAppBarDemoPagemain.dart构建了一个 48 行、带长标题一长串邮箱地址的演示页用于验证AppBarComponent的固定pinned动画头部展开 → 折叠的滚动动画长标题省略与“点击标题弹出完整内容”的 reveal 行为disableTitleTapReveal可关闭该行为用 FilterChip 切换列表行覆盖副标题有无、前置图有无、尾部按钮/箭头、主色标题titleColor: colors.primary等变体。5.12 Tooltip 与 AvatarTooltip 分区main.dart验证TooltipComponent的顶部指针气泡以及短/中/长文本的换行、maxWidth上限与超长省略三行后 ellipsizeAvatar 分区main.dart用“颜色 × 尺寸”表格验收 6 种尺寸xs / small / defaultSize / medium / large / contactHuge× 7 种颜色并展示AvatarComponent.seeded种子色板由avatarLight列表驱动与AvatarComponent.icon“添加联系人”加号头像。5.13 Text styles字阶验收_TextStylesPreviewmain.dart以统一文案 “Secure backup is ready” 顺序铺出TextStyles的六个字阶每个样例下方标注字号/行高/字重Token规格来自预览标注H120 / 28 / BoldH218 / 24 / Semi BoldLarge16 / 20 / Semi BoldBody14 / 20 / MediumMini12 / 16 / MediumTiny10 / 12 / Medium这些 token 与组件包 lib/theme/text_styles.dart 对应并被ComponentTheme._theme映射进 MaterialTextTheme见 lib/theme/theme.dart。六、内置“设置页” Demo组件在真实页面中的组合Catalog 还在抽屉CatalogSettingsDrawermain.dart里内置了一组仿真实 App 的设置页 Demo用于验证多个组件组合成完整页面时的表现Accountmain.dartChange email / Recovery key / Change password / Delete account红色警示行SecurityEmail verification带ToggleSwitchComponent实时切换、Passkey、App lock、Active sessionsAppearance三选一的主题选项选中项显示主色对勾GeneralLanguage 行、Show large icons、Compact mode、Hide codesToggleSwitch 组合Help and supportContact support / Help / Suggest features / Report a bugAboutOpen source / Privacy / Terms of service / Check for updates页脚显示 “Version 1.0.0”。这些页面全部复用AppBarComponentMenuComponentMenuGroupComponentToggleSwitchComponent是“组件如何组装成真实功能页”的现成参考样例。七、底层支撑组件包结构与设计令牌Catalog 只是入口被验收的组件都来自组件包ente_components。包内结构见 lib/按功能划分为components/30 余个组件实现包括menu_component.dart、banner_component.dart、toast_component.dart、buttons/button_component.dart、bottom_sheet/bottom_sheet_component.dart、text_input_component.dart、pin_input_component.dart、filter_chip_component.dart、app_bar_component.dart、avatar_component.dart、tooltip_component.dart、selection_controls/等统一由 lib/ente_components.dart 导出theme/设计令牌包括colors.dartColorTokensComponentApp枚举、text_styles.dart、spacing.dart、icon_sizes.dart、radii.dart、shadows.dart、motion.dart与theme.dartComponentThemeComponentColorTokensmodels/component_execution_state.dart异步执行状态模型驱动前面反复提到的 loading/success/error 表现。ColorTokens是一个近 70 个字段的色彩令牌集lib/theme/colors.dart覆盖主色系primaryLight→primaryDarker、功能色green*、blue*、purple*、warning*、caution*、文本色阶textLightest→textDarker、textReverse、背景填充backgroundBase、fillLight→fillDarkest、描边与特殊色specialWhite、specialScrim等。ComponentTheme.themeForApp(app, brightness:)会根据ComponentApp与明暗模式取出对应色板并生成 Material 3 主题——这正是 Catalog 双击切换三套产品主题的实现基础。八、把 Catalog 变成你的组件验收工作流结合以上分析可以把这套 Catalog 固化为日常开发习惯新增/修改组件后在对应分区确认所有状态尤其是 loading / success / error / disabled 四态与变体组合先在静态帧中检查再通过交互用例点击验证深浅色双验收使用 AppBar 主题按钮或双击手势分别以 light / dark 模式过一遍改动分区三产品主题覆盖双击循环切换photos / locker / auth三套ComponentApp主题确认品牌色替换如colors.primary、colors.warning没有破坏可读性页面级组合验收对涉及多组件拼装的改动参考内置 Settings / Header app bar / FAB 演示页验证组件在真实Scaffold、滚动与导航语境中的表现异步行为回归用shouldSurfaceExecutionStates/shouldShowSuccessConfirmation等开关组合回归按钮与菜单行的执行态动画。结语ente_components/example这个“仅有 3 行 README”的 Catalog 应用实际承载了 ente 设计系统最完整的可视化验收面15 个组件分区、数百个状态与变体用例、三套产品主题与深浅色全覆盖。对组件使用者而言它是学习每个组件 API 与最佳实践的活文档对组件维护者而言它是合并代码前的标准冒烟工具。结合组件包 lib/ 的设计令牌与执行状态模型开发者可以完全在 Flutter 本地工程中完成从“看效果”到“查实现”的闭环。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考