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 引數應用約束。