Flutter 小部件预览器

在本指南中，您将学习如何使用 Flutter Widget Previewer。

使用 Flutter Widget Previewer，您可以实时查看 Widget 在 Chrome 浏览器中渲染的效果，而无需一个完整的应用程序。要启动预览器、在其中显示 Widget 以及自定义预览，请参阅以下几部分。

要启动 Flutter Widget Previewer，请导航到您的 Flutter 项目的根目录，并在终端中运行以下命令。这将启动一个本地服务器，并在 Chrome 中打开一个 Widget Preview 环境，该环境会根据您项目中的更改自动更新。

flutter widget-preview start

启动预览器后，要查看 Widget，您必须使用在 package:flutter/widget_previews.dart 中定义的 @Preview 注解。此注解可以应用于

• 返回 Widget 或 WidgetBuilder 的 **顶层函数**。
• 类中返回 Widget 或 WidgetBuilder 的 **静态方法**。
• 没有必需参数的 **公共 Widget 构造函数和工厂函数**。

这是一个使用 @Preview 注解预览 Text Widget 的基本示例

import 'package:flutter/widget_previews.dart';
import 'package:flutter/material.dart'; // For Material widgets

@Preview(name: 'My Sample Text')
Widget mySampleText() {
  return const Text('Hello, World!');
}

每个预览实例都提供了各种控件用于与被预览 Widget 进行交互。从左到右

• 放大： 放大预览中的 Widget。

• 缩小： 减小预览中 Widget 的放大倍数。

• 重置缩放： 将 Widget 预览恢复到默认缩放级别。

• 切换浅色和深色模式： 在浅色和深色配色方案之间切换预览的主题。

• 对单个预览执行热重载： 仅重启特定的 Widget 预览，允许快速应用更改，而无需重启整个应用程序。

对于全局状态已被修改的情况（例如，已更改静态初始化程序），可以使用环境右上角的按钮让整个 Widget Previewer 进行热重载。

@Preview 注解有几个参数可用于自定义预览

• name：预览的描述性名称。

• size：使用 Size 对象设置的人工尺寸约束。

• textScaleFactor：自定义字体缩放比例。

• wrapper：一个将您被预览的 Widget 包装到特定 Widget 树中的函数（例如，使用 InheritedWidget 将应用程序状态注入 Widget 树）。

• theme：提供 Material 和 Cupertino 主题数据的函数。

• brightness：初始主题亮度。

• localizations：应用本地化配置的函数。

Flutter Widget Previewer 存在一些您应该注意的限制

• 公共常量：提供给 @Preview 注解的所有参数都必须是公共的且是常量。这是预览器的代码生成实现能够正确工作的必需条件。对公共变量名的要求将在未来的版本中放宽，但函数参数名称必须始终是公共的。

• 不支持的 API：原生插件以及 dart:io 库中的任何 API 均不受支持。这是因为 Widget Previewer 是使用 Flutter Web 构建的，它无法访问底层的原生平台 API。虽然在使用 Chrome 时 Web 插件可能有效，但不能保证它们在其他环境中也有效，例如嵌入在 IDE 中时。

• 资源路径：在使用 dart:ui 中的 fromAsset API 加载资源时，您必须使用 **基于包的路径** 而不是直接的本地路径。这确保了资源可以在预览器的 Web 环境中正确找到和加载。例如，使用 'packages/my_package_name/assets/my_image.png' 而不是 'assets/my_image.png'。

• 浏览器支持：目前，预览器仅在 Chrome 上受支持，因为它需要热重载支持。Web 服务器和 IDE 对此功能的支持计划在未来的版本中推出。

• 无约束的 Widget：无约束的 Widget 会被自动约束到 Widget Previewer 的高度和宽度的约一半。此行为未来可能会发生变化，因此如果可能，应使用 size 参数应用约束。