需要为 Flutter 组件添加可交互预览时：用…

在 Flutter 项目中为 UI 组件创建实时、隔离的交互式预览，以便统一设计并快速迭代测试。

适用场景

解决思路

1. 导入 package:flutter/widget_previews.dart 以获取预览注解。
2. 选择合法的预览目标：无必需参数的顶层函数、类中的静态方法，或返回 Widget/WidgetBuilder 的公共构造函数/工厂。
3. 在目标上应用 @Preview 注解，并按需配置参数（name、group、size、theme、brightness 等）。
4. 若多个组件需要相同配置，可继承 Preview 类创建自定义注解，注入通用属性（如主题、包装器）。
5. 对同一目标应用多个 @Preview 注解可生成多个预览实例；也可继承 MultiPreview 封装常见的多预览配置。
6. 在自定义 Preview 或 MultiPreview 类中重写 transform() 方法，在运行时动态修改预览配置（如根据动态值生成名称，这在 const 上下文中无法实现）。
7. 避免使用原生插件或 dart:io、dart:ffi 中的 API，因为预览器运行在 Web 环境；如有传递依赖，用条件导入在预览模式下模拟或绕过。
8. 通过 dart:ui 的 fromAsset API 加载资源时，使用基于包的路径（如 packages/my_package_name/assets/my_image.png 而非 assets/my_image.png）。
9. 确保传给预览注解的所有回调参数都是 public 且 const，以满足代码生成要求。
10. 若组件无约束，在 @Preview 注解中用 size 参数显式指定约束，因为预览器默认将其限制在约半个视口。
11. 使用支持的 IDE（Android Studio、IntelliJ、Flutter 3.38+ 的 VS Code）时，启动 IDE 后预览器自动开启；在侧边栏打开 “Flutter Widget Preview” 标签页；如需查看当前文件之外的预览，切换左下角的 “Filter previews by selected file”。
12. 使用命令行时，进入 Flutter 项目根目录，运行 flutter widget-preview start，查看自动打开的 Chrome 环境。
13. 迭代反馈循环：修改组件代码或预览配置后观察预览器自动更新；若修改了全局状态（如静态初始化器），点击右下角的全局热重启按钮；若只需重置局部组件状态，点击对应预览卡片上的单独热重启按钮；在 IDE/CLI 控制台查看错误并修复后重复。
14. 基础预览示例：import 'package:flutter/widget_previews.dart'; import 'package:flutter/material.dart'; @Preview(name: 'My Sample Text', group: 'Typography') Widget mySampleText() { return const Text('Hello, World!'); }
15. 自定义运行时转换预览示例：定义 final class TransformativePreview extends Preview，重写 transform() 方法，通过 originalPreview.toBuilder() 修改 name 和 theme 后返回 builder.toPreview()。
16. MultiPreview 实现示例：定义 final class MultiBrightnessPreview extends MultiPreview，在 previews getter 中返回亮/暗两个 Preview，并在 transform() 中为每个预览设置 group 和 name。

适用边界 · 注意事项

• 组件依赖原生插件或 dart:io、dart:ffi 的 API 时，预览会抛出异常，需改用条件导入模拟。
• 预览注解的回调参数非 public 或非 const 时，无法满足代码生成要求。
• 组件无约束且未通过 size 参数指定约束时，预览器会将其限制在约半个视口，可能无法正确展示。