Flutter 元件預覽器
瞭解如何使用 Flutter 元件預覽器,在獨立於完整應用程式的環境中即時渲染您的元件 (Widget)。
在本指南中,您將學習如何使用 Flutter 元件預覽器 (Flutter Widget Previewer)。
概述
#透過 Flutter 元件預覽器,您可以在 IDE 或瀏覽器中,即時渲染、檢查並迭代個別的 UI 元件,且獨立於完整應用程式之外。
以下各節將說明如何開啟預覽器、預覽您的元件 (Widget)、搜尋與篩選預覽,以及自訂預覽設定。
開啟預覽器
#IDE
#Android Studio、IntelliJ 以及 Visual Studio Code 會在啟動時自動開啟 Flutter Widget Previewer。
Android Studio 與 IntelliJ
#若要在 Android Studio 或 IntelliJ 中開啟 Widget Previewer,請在側邊欄開啟「Flutter Widget Preview」標籤頁:
Visual Studio Code
#若要在 Visual Studio Code 中開啟 Widget Previewer,請在側邊欄開啟「Flutter Widget Preview」標籤頁:
命令列
#若要從終端機啟動 Flutter Widget Previewer,請切換至 Flutter 專案的根目錄,並執行以下指令:
flutter widget-preview start
這會啟動一個本機伺服器,並在瀏覽器中開啟即時預覽環境。
為了縮短啟動時間,預覽器會自動將專案建置結果快取在專案根目錄的 .widget_preview/ 資料夾中。
預覽元件
#
啟動預覽器後,若要查看某個元件,您必須使用定義於 package:flutter/widget_previews.dart 中的 @Preview
標註。此標註可套用於:
- 最上層函式,其回傳值為
Widget或WidgetBuilder。 - 類別中的靜態方法,其回傳值為
Widget或WidgetBuilder。 - 公開的 Widget 建構子與工廠方法,且不需要任何必填引數。
以下是使用 @Preview 標註預覽 Text 元件的基本範例:
import 'package:flutter/widget_previews.dart';
import 'package:material_ui/material_ui.dart'; // For Material widgets
@Preview(name: 'My Sample Text')
Widget mySampleText() {
return const Text('Hello, World!');
}
每個預覽實例都提供各種控制項以與預覽中的元件互動。從左到右依序為:
放大: 放大預覽中的元件。
縮小: 縮小預覽中的元件。
重設縮放: 將元件預覽恢復至預設縮放等級。
切換淺色與深色模式: 在預覽的淺色與深色配色方案之間切換主題。
對單一預覽執行熱重啟: 僅重啟特定元件預覽,讓您能快速套用變更,而無需重啟整個應用程式。
當全域狀態已被修改(例如靜態初始化器已變更)時,您可以使用環境右下角的按鈕,讓整個 Widget Previewer 執行熱重啟。
搜尋與篩選預覽
#Widget Previewer 環境包含搜尋與篩選功能,協助您在擁有許多已標註預覽的專案中瀏覽。
搜尋列與篩選條件
#使用環境頂端的搜尋列即時篩選預覽。點擊搜尋欄位旁的篩選下拉選單,選擇要比對的條件:
-
Preview name:依
@Preview標註中設定的描述性名稱篩選。 - Group name:依
@Preview(group: ...)參數中指定的群組名稱篩選。 - Containing script:依包含該預覽的 Dart 檔案 URI 篩選。
- Containing package:依包含該預覽的套件名稱篩選。
例如,以下預覽標註中的參數會比對 Preview name('Submit Button')與 Group name('Form Controls')篩選條件:
@Preview(name: 'Submit Button', group: 'Form Controls')
Widget submitButtonPreview() => const SubmitButton();
在 IDE 中依選取的檔案篩選預覽
#在 IDE 中查看預覽時,Widget Previewer 也可以根據目前選取的檔案篩選預覽:
若要切換此行為,請選取環境底部的 Filter previews by selected file 選項。
自訂預覽
#
@Preview
標註有幾個參數可讓您自訂預覽:
name:預覽的描述性名稱。group:用來在 Widget Previewer 中將相關預覽分組的名稱。size:使用Size物件設定的人工尺寸限制。textScaleFactor:自訂字體縮放比例。-
wrapper:將預覽元件包裝在特定元件樹中的函式(例如,用InheritedWidget將應用程式狀態注入元件樹)。 -
theme:回傳PreviewThemeData實例的函式,用來提供自訂與通用的主題資料,並支援循序的主題分層,以進行複雜的矩陣測試。 brightness:初始主題亮度。localizations:套用本地化設定的函式。
建立自訂預覽標註
#
為了減少定義具有相同屬性組合之預覽所需的樣板程式碼,可以繼承 Preview
標註類別來建立專為您的專案量身打造的自訂預覽標註。
以下是一個為 Material 元件提供自訂主題資料的自訂預覽標註範例:
final class const MyCustomPreview({
super.name,
super.group,
super.size,
super.textScaleFactor,
super.wrapper,
super.brightness,
super.localizations,
}) extends Preview {
this : super(theme: PreviewMaterialThemeData.new);
}
final class const PreviewMaterialThemeData() extends PreviewThemeData {
@override
Widget apply(BuildContext context, Widget child) => Theme(
data: .from(colorScheme: .fromSeed(seedColor: Colors.lime)),
child: child,
);
}
繼承 Preview
標註類別還允許覆寫 Preview.transform()
方法。此方法由 Widget Previewer 調用,可用於在執行時期修改預覽,從而實現在 const 情境下無法完成的預覽設定:
final class const TransformativePreview({
super.name,
super.group,
super.size,
super.textScaleFactor,
super.wrapper,
super.brightness,
super.localizations,
}) extends Preview {
PreviewThemeData _themeBuilder() =>
PreviewMaterialThemeData(brightness: brightness);
@override
Preview transform() {
final originalPreview = super.transform();
final themeVariant = switch (brightness) {
null => 'Responsive',
final b => b.name,
};
// Creates a PreviewBuilder that can be used to modify
// the preview contents.
final builder = originalPreview.toBuilder();
builder
..name = 'Transformed - ${originalPreview.name}[$themeVariant]'
..theme = _themeBuilder;
// Returns the updated Preview instance.
return builder.build();
}
}
final class const PreviewMaterialThemeData({final Brightness? _brightness})
extends PreviewThemeData {
@override
Widget apply(BuildContext context, Widget child) {
return Theme(
data: .from(
colorScheme: .fromSeed(
seedColor: Colors.lime,
brightness: _brightness ?? MediaQuery.platformBrightnessOf(context),
),
),
child: child,
);
}
}
建立多個預覽設定
#
建立具有不同設定的多個預覽,只需將多個 @Preview
標註套用至單一函式或建構子即可:
@Preview(
group: 'Brightness',
name: 'Example - light',
brightness: Brightness.light,
)
@Preview(
group: 'Brightness',
name: 'Example - dark',
brightness: Brightness.dark,
)
Widget buttonPreview() => const ButtonShowcase();
若要簡化建立具有相同設定的多個預覽,您可以繼承 MultiPreview
來定義能產生多個預覽的自訂標註。以下 MultiPreview
建立與前一個範例相同的兩個預覽:
/// Creates light and dark mode previews.
final class MultiBrightnessPreview extends MultiPreview {
const MultiBrightnessPreview();
@override
List<Preview> get previews => const [
Preview(
group: 'Brightness',
name: 'Example - light',
brightness: Brightness.light,
),
Preview(
group: 'Brightness',
name: 'Example - dark',
brightness: Brightness.dark,
),
];
}
@MultiBrightnessPreview()
Widget buttonPreview() => const ButtonShowcase();
與 Preview
相同,MultiPreview
也提供 MultiPreview.transform()
方法,用於在執行時期對每個預覽執行轉換:
/// Creates light and dark mode previews.
final class MultiBrightnessPreview extends MultiPreview {
const MultiBrightnessPreview({required this.name});
final String name;
@override
List<Preview> get previews => const [
Preview(brightness: Brightness.light),
Preview(brightness: Brightness.dark),
];
@override
List<Preview> transform() {
final previews = super.transform();
return previews.map((preview) {
final builder = preview.toBuilder()
..group = 'Brightness'
// Building names based on values provided to the annotation
// isn't possible within a constant constructor. However,
// there's no such restriction when building a Preview at
// runtime.
..name = '$name - ${preview.brightness!.name}';
return builder.toPreview();
}).toList();
}
}
@MultiBrightnessPreview(name: 'Example')
Widget buttonPreview() => const ButtonShowcase();
限制與侷限
#Flutter Widget Previewer 有一些您應當注意的限制:
公開的回呼 (callback) 名稱:所有提供給預覽標註的回呼引數必須是公開且為常數。這是預覽器的程式碼產生實作正確運作的必要條件。
-
不支援的 API:原生插件 (plugin) 以及
dart:io或dart:ffi函式庫中的任何 API 皆不受支援。這是因為 Widget Previewer 是以 Flutter Web 建置的,無法存取底層原生平台 API。雖然 Web 插件在您的瀏覽器中可能可以運作,但不能保證它們在您的 IDE 中也能正常運作。對
dart:io或dart:ffi具有傳遞性相依的元件可以正常載入,但這些函式庫中的所有 API 在調用時都會拋出例外。請參閱 Dart 條件匯入文件,瞭解如何架構您的應用程式,以便在針對多個平台時能乾淨地支援特定平台函式庫。
-
資產路徑:使用
dart:ui中的fromAssetAPI 載入資源時,您必須使用以套件為基礎的路徑,而非直接的本機路徑。這可確保資源在預覽器的 Web 環境中能被正確找到並載入。例如,請使用'packages/my_package_name/assets/my_image.png',而非'assets/my_image.png'。預覽 Web 元件時,預覽器會自動同步您主機專案
web/目錄中的資產,並套用自訂主題或index.html的自訂內容。 -
無約束的元件:無約束的元件會自動被限制在 Widget Previewer 高度和寬度的大約一半。此行為未來可能會有所變更,因此建議盡可能使用
size參數來套用限制。 -
IDE 中的多專案支援:Widget Previewer 目前僅支援顯示單一專案或 Pub 工作區中的預覽。我們正積極研究支援包含多個 Flutter 專案的 IDE 工作階段的方案(#173550)。
Unless stated otherwise, the documentation on this site reflects Flutter 3.47. Page last updated on 2026-10-25. View source or report an issue.