Skip to main content

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」標籤頁:

Flutter Widget Previewer in Android Studio

Visual Studio Code

#

若要在 Visual Studio Code 中開啟 Widget Previewer,請在側邊欄開啟「Flutter Widget Preview」標籤頁:

Flutter Widget Previewer in Visual Studio Code

命令列

#

若要從終端機啟動 Flutter Widget Previewer,請切換至 Flutter 專案的根目錄,並執行以下指令:

shell
flutter widget-preview start

這會啟動一個本機伺服器,並在瀏覽器中開啟即時預覽環境。

為了縮短啟動時間,預覽器會自動將專案建置結果快取在專案根目錄的 .widget_preview/ 資料夾中。

預覽元件

#

啟動預覽器後,若要查看某個元件,您必須使用定義於 package:flutter/widget_previews.dart 中的 @Preview 標註。此標註可套用於:

  • 最上層函式,其回傳值為 Widget 或 WidgetBuilder。
  • 類別中的靜態方法,其回傳值為 Widget 或 WidgetBuilder。
  • 公開的 Widget 建構子與工廠方法,且不需要任何必填引數。

以下是使用 @Preview 標註預覽 Text 元件的基本範例:

dart
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!');
}

Sample widget in Flutter Widget Previewer 每個預覽實例都提供各種控制項以與預覽中的元件互動。從左到右依序為:

  • 放大: 放大預覽中的元件。

  • 縮小: 縮小預覽中的元件。

  • 重設縮放: 將元件預覽恢復至預設縮放等級。

  • 切換淺色與深色模式: 在預覽的淺色與深色配色方案之間切換主題。

  • 對單一預覽執行熱重啟: 僅重啟特定元件預覽,讓您能快速套用變更,而無需重啟整個應用程式。

當全域狀態已被修改(例如靜態初始化器已變更)時,您可以使用環境右下角的按鈕,讓整個 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')篩選條件:

dart
@Preview(name: 'Submit Button', group: 'Form Controls')
Widget submitButtonPreview() => const SubmitButton();

在 IDE 中依選取的檔案篩選預覽

#

在 IDE 中查看預覽時,Widget Previewer 也可以根據目前選取的檔案篩選預覽:

Filter previews by selected file in Flutter Widget Previewer

若要切換此行為,請選取環境底部的 Filter previews by selected file 選項。

自訂預覽

#

@Preview 標註有幾個參數可讓您自訂預覽:

  • name:預覽的描述性名稱。

  • group:用來在 Widget Previewer 中將相關預覽分組的名稱。

  • size:使用 Size 物件設定的人工尺寸限制。

  • textScaleFactor:自訂字體縮放比例。

  • wrapper:將預覽元件包裝在特定元件樹中的函式(例如,用 InheritedWidget 將應用程式狀態注入元件樹)。

  • theme:回傳 PreviewThemeData 實例的函式,用來提供自訂與通用的主題資料,並支援循序的主題分層,以進行複雜的矩陣測試。

  • brightness:初始主題亮度。

  • localizations:套用本地化設定的函式。

建立自訂預覽標註

#

為了減少定義具有相同屬性組合之預覽所需的樣板程式碼,可以繼承 Preview 標註類別來建立專為您的專案量身打造的自訂預覽標註。

以下是一個為 Material 元件提供自訂主題資料的自訂預覽標註範例:

dart
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,
  );
}

Providing ThemeData using custom Preview annotation in Flutter Widget Previewer

繼承 Preview 標註類別還允許覆寫 Preview.transform() 方法。此方法由 Widget Previewer 調用,可用於在執行時期修改預覽,從而實現在 const 情境下無法完成的預覽設定:

dart
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,
    );
  }
}

Runtime transformations to Preview annotation in Flutter Widget Previewer

建立多個預覽設定

#

建立具有不同設定的多個預覽,只需將多個 @Preview 標註套用至單一函式或建構子即可:

dart
@Preview(
  group: 'Brightness',
  name: 'Example - light',
  brightness: Brightness.light,
)
@Preview(
  group: 'Brightness',
  name: 'Example - dark',
  brightness: Brightness.dark,
)
Widget buttonPreview() => const ButtonShowcase();

Multiple previews in Flutter Widget Previewer

若要簡化建立具有相同設定的多個預覽,您可以繼承 MultiPreview 來定義能產生多個預覽的自訂標註。以下 MultiPreview 建立與前一個範例相同的兩個預覽:

dart
/// 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() 方法,用於在執行時期對每個預覽執行轉換:

dart
/// 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 中的 fromAsset API 載入資源時,您必須使用以套件為基礎的路徑,而非直接的本機路徑。這可確保資源在預覽器的 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)。