使用 Flutter 檢測器

Flutter Widget 檢測器是強大的工具，可視覺化和探索 Flutter Widget 樹狀結構。Flutter 框架使用 Widget 作為核心建構區塊，從控制項（例如文字、按鈕和切換開關）到佈局（例如置中、邊距、列和欄）。檢測器可協助您視覺化和探索 Flutter Widget 樹狀結構，並可用於下列用途

• 了解現有的佈局
• 診斷佈局問題

若要偵錯佈局問題，請在偵錯模式中執行應用程式，然後按一下 DevTools 工具列上的 Flutter 檢測器標籤，開啟檢測器。

以下是檢測器工具列中可用功能的指南。當空間有限時，會使用圖示作為標籤的視覺版本。

選取 Widget 模式

啟用此按鈕以選取裝置上的 Widget 來檢視它。若要了解更多資訊，請參閱檢視 Widget。

重新整理樹狀結構

重新載入目前的 Widget 資訊。

慢速動畫

以 5 倍慢速執行動畫，以協助微調它們。

顯示輔助線

覆蓋輔助線以協助修正佈局問題。

顯示基準線

顯示基準線，用於對齊文字。可用於檢查文字是否對齊。

醒目提示重繪

顯示元素重繪時會變色的邊框。可用於尋找不必要的重繪。

醒目提示過大的圖片

反轉顏色並翻轉它們，以醒目提示使用過多記憶體的圖片。

您可以瀏覽互動式 Widget 樹狀結構，以檢視附近的 Widget 並查看其欄位值。

若要在 Widget 樹狀結構中找到個別的 UI 元素，請按一下工具列中的 選取 Widget 模式 按鈕。這會將裝置上的應用程式置於「Widget 選取」模式。按一下應用程式 UI 中的任何 Widget；這會選取應用程式螢幕上的 Widget，並將 Widget 樹狀結構捲動到對應的節點。再次切換 選取 Widget 模式 按鈕以結束 Widget 選取模式。

偵錯佈局問題時，要查看的關鍵欄位是 size 和 constraints 欄位。約束條件會向下流動到樹狀結構，而大小會向上流動。如需有關其運作方式的詳細資訊，請參閱了解約束條件。

Flutter 佈局檢視器可協助您更深入了解 Flutter 佈局。

如需有關此工具可以做什麼的概述，請參閱 Flutter 檢視器影片

DevTools 佈局檢視器

您可能也會發現下列逐步文章很有用

• 如何使用 Flutter 檢測器偵錯佈局問題

從 Flutter 檢測器中，選取一個 Widget。佈局檢視器支援彈性佈局和固定大小佈局，並為這兩種佈局提供特定的工具。

當您選取彈性 Widget (例如 Row、Column、Flex) 或彈性 Widget 的直接子項時，彈性佈局工具將會出現在佈局檢視器中。

佈局檢視器可視覺化Flex Widget 及其子項的配置方式。檢視器會識別主軸和交叉軸，以及每個軸的目前對齊方式 (例如，開始、結束和 spaceBetween)。它也會顯示諸如彈性係數、彈性擬合和佈局約束條件等詳細資訊。

此外，檢視器會顯示佈局約束條件違規和轉譯溢位錯誤。違反的佈局約束條件會以紅色標示，而溢位錯誤會以標準的「黃色膠帶」模式呈現，如同您在執行裝置上看到的模式。這些視覺化旨在增進對溢位錯誤發生原因以及如何修正的理解。

按一下佈局檢視器中的 Widget 會鏡射裝置上檢測器中的選取項目。必須啟用 選取 Widget 模式。若要啟用它，請按一下檢測器中的 選取 Widget 模式 按鈕。

對於某些屬性 (例如彈性係數、彈性擬合和對齊方式)，您可以透過檢視器中的下拉式清單修改值。修改 Widget 屬性時，您不僅會在佈局檢視器中看到新的值反映，也會在執行 Flutter 應用程式的裝置上看到。檢視器會在屬性變更時產生動畫，以便清楚顯示變更的效果。從佈局檢視器變更的 Widget 屬性不會修改您的原始碼，而且會在熱重載時還原。

佈局檢視器支援修改 mainAxisAlignment、crossAxisAlignment 和 FlexParentData.flex。未來，我們可能會新增對其他屬性的支援，例如 mainAxisSize、textDirection 和 FlexParentData.fit。

支援的值

• MainAxisAlignment.start
• MainAxisAlignment.end
• MainAxisAlignment.center
• MainAxisAlignment.spaceBetween
• MainAxisAlignment.spaceAround
• MainAxisAlignment.spaceEvenly

支援的值

• CrossAxisAlignment.start
• CrossAxisAlignment.center
• CrossAxisAlignment.end
• CrossAxisAlignment.stretch

佈局檢視器在 UI 中支援 7 個彈性選項 (null、0、1、2、3、4、5)，但在技術上，彈性 Widget 子項的彈性係數可以是任何 int。

佈局檢視器支援兩種不同的 FlexFit 類型：loose 和 tight。

當您選取不是彈性 Widget 子項的固定大小 Widget 時，固定大小佈局資訊將會出現在佈局檢視器中。您可以查看所選 Widget 及其最接近上游 RenderObject 的大小、約束條件和邊距資訊。

Flutter 檢測器提供數個選項，可視覺化偵錯您的應用程式。

啟用時，此選項會以 5 倍慢速執行動畫，以便更容易進行視覺檢查。如果您想要仔細觀察和調整看起來不太正確的動畫，這會很有用。

這也可以在程式碼中設定

import 'package:flutter/scheduler.dart';

void setSlowAnimations() {
  timeDilation = 5.0;
}

這會將動畫減慢 5 倍。

下列連結提供更多資訊。

• Flutter 文件：timeDilation 屬性

下列螢幕錄製顯示了減慢動畫之前和之後的情況。

此功能會在您的應用程式上繪製輔助線，以顯示轉譯框、對齊方式、邊距、捲動檢視、裁剪和間隔符。

此工具可用於更好地了解您的佈局。例如，藉由尋找不必要的邊距或了解 Widget 對齊方式。

您也可以在程式碼中啟用此功能

import 'package:flutter/rendering.dart';

void showLayoutGuidelines() {
  debugPaintSizeEnabled = true;
}

繪製到螢幕的 Widget 會建立一個 轉譯框，這是 Flutter 佈局的建構區塊。它們會以亮藍色邊框顯示

對齊方式會以黃色箭頭顯示。這些箭頭會顯示 Widget 相對於其父項的垂直和水平偏移量。例如，此按鈕的圖示顯示為由四個箭頭置中

邊距會以半透明的藍色背景顯示

具有捲動內容 (例如清單檢視) 的 Widget 會以綠色箭頭顯示

裁剪，例如使用 ClipRect Widget 時，會以帶有剪刀圖示的粉紅色虛線顯示

間隔符 Widget 會以灰色背景顯示，例如這個沒有子項的 SizedBox

此選項會讓所有基準線可見。基準線是用於定位文字的水平線。

這可用於檢查文字是否精確地垂直對齊。例如，下列螢幕擷取畫面中的文字基準線稍微未對齊

可以使用 Baseline Widget 來調整基準線。

會在設定基準線的任何 轉譯框上繪製一條線；字母基準線會顯示為綠色，而表意基準線會顯示為黃色。

您也可以在程式碼中啟用此功能

import 'package:flutter/rendering.dart';

void showBaselines() {
  debugPaintBaselinesEnabled = true;
}

此選項會在每個 轉譯框周圍繪製邊框，該邊框會在每次該框重繪時變更顏色。

此旋轉的彩虹顏色可用於尋找應用程式中重繪頻率過高且可能損害效能的部分。

例如，一個小型動畫可能會導致整個頁面在每個影格上重繪。將動畫包裝在 RepaintBoundary Widget 中，可將重繪限制為僅限動畫。

此處的進度指示器會導致其容器重繪

class EverythingRepaintsPage extends StatelessWidget {
  const EverythingRepaintsPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Repaint Example')),
      body: const Center(
        child: CircularProgressIndicator(),
      ),
    );
  }
}

將進度指示器包裝在 RepaintBoundary 中，只會導致螢幕的該區段重繪

class AreaRepaintsPage extends StatelessWidget {
  const AreaRepaintsPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Repaint Example')),
      body: const Center(
        child: RepaintBoundary(
          child: CircularProgressIndicator(),
        ),
      ),
    );
  }
}

RepaintBoundary Widget 有取捨。它們可以協助提升效能，但它們也會因為建立新畫布而產生額外負荷，進而使用額外的記憶體。

您也可以在程式碼中啟用此選項

import 'package:flutter/rendering.dart';

void highlightRepaints() {
  debugRepaintRainbowEnabled = true;
}

此選項會透過反轉其顏色並垂直翻轉它們來醒目提示過大的圖片

醒目提示的圖片會使用比所需更多的記憶體；例如，以 100 x 100 像素顯示的 5MB 大型圖片。

這類圖片可能會導致效能不佳，尤其是在低階裝置上，而且當您有許多圖片時 (如同在清單檢視中)，此效能降低可能會加劇。每個圖片的相關資訊會列印在偵錯主控台中

dash.png has a display size of 213×392 but a decode size of 2130×392, which uses an additional 2542KB.

如果圖片使用的記憶體比所需至少多 128KB，則會將其視為過大。

在可能的情況下，修正此問題的最佳方法是調整圖片資產檔案的大小，使其更小。

如果無法這樣做，您可以在 Image 建構函式上使用 cacheHeight 和 cacheWidth 參數

class ResizedImage extends StatelessWidget {
  const ResizedImage({super.key});

  @override
  Widget build(BuildContext context) {
    return Image.asset(
      'dash.png',
      cacheHeight: 213,
      cacheWidth: 392,
    );
  }
}

這會讓引擎以指定的大小解碼此圖片，並減少記憶體使用量 (解碼和儲存仍然比縮小圖片資產本身更昂貴)。無論這些參數為何，圖片都會以佈局或寬度和高度的約束條件轉譯。

也可以在程式碼中設定此屬性

void showOversizedImages() {
  debugInvertOversizedImages = true;
}

您可以在以下連結了解更多資訊

• Flutter 文件：debugInvertOversizedImages

選取 Widget 詳細資訊樹狀圖 標籤，以顯示所選 Widget 的詳細資訊樹狀圖。從這裡，您可以收集有關 Widget 的屬性、渲染物件和子項的有用資訊。

Flutter Inspector 的部分功能是基於對應用程式程式碼進行檢測，以便更好地了解 Widget 的建立來源位置。來源檢測允許 Flutter Inspector 以類似於 UI 在您的原始碼中定義的方式呈現 Widget 樹狀結構。如果沒有它，Widget 樹狀結構中的節點會更深層，並且可能更難理解執行時 Widget 階層結構如何對應於您的應用程式 UI。

您可以使用 flutter run 命令並傳遞 --no-track-widget-creation 來停用此功能。

以下範例說明啟用和停用追蹤 Widget 建立時，您的 Widget 樹狀結構可能會是什麼樣子。

已啟用追蹤 Widget 建立 (預設)

已停用追蹤 Widget 建立 (不建議)

此功能會防止在偵錯版本中將其他相同的 const Widget 視為相等。如需更多詳細資訊，請參閱關於偵錯時常見問題的討論。

將滑鼠懸停在任何 Widget 上，會顯示其屬性和值。

切換此值可啟用或停用懸停檢測功能。

預設情況下，DevTools 會將 Widget 樹狀結構中顯示的 Widget 限制為來自專案根目錄的 Widget，以及來自 Flutter 的 Widget。此篩選僅適用於 Inspector Widget 樹狀結構中的 Widget (Inspector 的左側) — 而不適用於 Widget 詳細資訊樹狀圖 (Inspector 的右側，與版面配置瀏覽器位於相同的標籤視圖中)。在 Widget 詳細資訊樹狀圖中，您可以查看樹狀結構中來自所有套件的所有 Widget。

為了顯示其他 Widget，必須將它們的父目錄新增至「套件目錄」。

例如，考慮以下目錄結構

project_foo
  pkgs
    project_foo_app
    widgets_A
    widgets_B

從 project_foo_app 執行您的應用程式時，只會在 Widget Inspector 樹狀結構中顯示來自 project_foo/pkgs/project_foo_app 的 Widget。

若要在 Widget 樹狀結構中顯示來自 widgets_A 的 Widget，請將 project_foo/pkgs/widgets_A 新增至套件目錄。

若要在 Widget 樹狀結構中顯示來自專案根目錄的所有 Widget，請將 project_foo 新增至套件目錄。

對您的套件目錄所做的變更會在下次為應用程式開啟 Widget Inspector 時持續保留。

如需示範 Inspector 的一般功能，請參閱DartConf 2018 演講，其中展示了 IntelliJ 版本的 Flutter Inspector。

若要了解如何使用 DevTools 以視覺化方式偵錯版面配置問題，請查看導覽式Flutter Inspector 教學。

除非另有說明，本網站上的文件反映了 Flutter 的最新穩定版本。頁面最後更新於 2024-10-14。 檢視原始碼或回報問題。