使用 Flutter 檢查器

有關如何在不同 IDE 中找到 DevTools 螢幕的資訊，請檢視 DevTools 概述。

Flutter Widget 檢查器是一個強大的工具，用於視覺化和探索 Flutter Widget 樹。Flutter 框架使用 Widget 作為構建任何內容的構建塊，從控制元件（如文字、按鈕和切換開關）到佈局（如居中、填充、行和列）。該檢查器可幫助您視覺化和探索 Flutter Widget 樹，並可用於以下目的

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

作為 Flutter 3.29 的一部分，新的 Flutter 檢查器預設啟用。但是，可以從 檢查器設定對話方塊 中停用它。

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

選擇 Widget 模式

啟用此按鈕以選擇裝置上的 Widget 進行檢查。要了解更多資訊，請檢視 檢查一個 Widget。

顯示實現 Widget

啟用此按鈕以在 Widget 樹中顯示實現 Widget。要了解更多資訊，請檢視 使用 Widget 樹。

重新整理樹

重新載入當前 Widget 資訊。

緩慢的動畫

以 5 倍的速度執行動畫，以幫助微調它們。

顯示引導線

覆蓋引導線以幫助修復佈局問題。

顯示基線

顯示基線，用於對齊文字。對於檢查文字是否對齊非常有用。

突出顯示重繪

顯示顏色會發生變化的邊框，以顯示元素重繪。對於查詢不必要的重繪非常有用。

突出顯示超大影像

透過反轉顏色和翻轉來突出顯示使用過多記憶體的影像。

您可以瀏覽互動式 Widget 樹以檢視附近的 Widget 並檢視它們的欄位值。

要定位 Widget 樹中的單個 UI 元素，請單擊工具欄中的 選擇 Widget 模式 按鈕。這將使裝置上的應用進入“Widget 選擇”模式。單擊應用 UI 中的任何 Widget；這將選擇應用螢幕上的 Widget，並滾動到 Widget 樹的相應節點。再次切換 選擇 Widget 模式 按鈕以退出 Widget 選擇模式。

在除錯佈局問題時，關鍵欄位是 size 和 constraints 欄位。約束從樹中向下流動，大小從樹中向上流動。有關其工作原理的更多資訊，請參閱 瞭解約束。

Flutter Widget 樹允許您視覺化、理解和導航應用的 Widget 樹。

預設情況下，Flutter Widget 樹包括在您的根專案目錄中建立的所有 Widget。

Widget 的父子關係由單條垂直線表示（如果父 Widget 只有一個子 Widget），或者透過縮排表示（如果父 Widget 有多個子 Widget）。

例如，對於 Widget 樹的以下部分

• Padding 具有單個子 Widget Row
• Row 有三個子 Widget：Icon、SizedBox 和 Flexible
• Flexible 具有單個子 Widget Column
• Column 有四個子 Widget：Text、Text、SizedBox 和 Divider

要改為檢視 Widget 樹中的所有 Widget，包括在您的專案外部建立的 Widget，請切換“顯示實現 Widget”。

實現 Widget 以較淺的字型顯示，從而在視覺上區分它們。它們也隱藏在可展開的組後面，可以透過內聯展開按鈕展開。

例如，以下是與實現 Widget 顯示相同的 Widget 樹部分

• Icon 具有五個摺疊在其下方的實現 Widget
• 兩個 Text Widget 都有 RichText 實現 Widget 子 Widget
• Divider 具有九個摺疊在其下方的實現 Widget

Flutter Widget 資源管理器可幫助您更好地理解被檢查的 Widget。

從 Flutter 檢查器中，選擇一個 Widget。Widget 資源管理器將顯示在視窗的右側。

根據所選 Widget，Widget 資源管理器將包括以下一個或多個選項卡

• Widget 屬性選項卡
• Flex 資源管理器選項卡
• Render 物件選項卡

屬性選項卡顯示您的 Widget 佈局的微型檢視，包括寬度、高度和填充，以及該 Widget 上的屬性列表。

這些屬性包括該值是否與屬性引數的預設值匹配。

Render 物件選項卡顯示設定在所選 Flutter Widget 的 Render 物件上的所有屬性。

當您選擇一個 Flex Widget（例如，Row、Column、Flex）或 Flex Widget 的直接子 Widget 時，Flex 資源管理器工具將出現在 Widget 資源管理器中。

Flex 資源管理器工具可視化了 Flex Widget 及其子 Widget 的佈局方式。資源管理器標識主軸和交叉軸，以及每個軸的當前對齊方式（例如，開始、結束和 spaceBetween）。它還顯示諸如 flex 係數、flex 擬合和佈局約束之類的詳細資訊。

此外，資源管理器顯示佈局約束違規和 Render 溢位錯誤。違反的佈局約束以紅色突出顯示，溢位錯誤以標準的“黃色膠帶”模式呈現，就像您在執行裝置上看到的那樣。這些視覺化旨在幫助理解溢位錯誤發生的原因以及如何修復它們。

單擊 Flex 資源管理器中的 Widget 會映象裝置上檢查器中的選擇。需要啟用“選擇 Widget 模式”才能實現這一點。要啟用它，請單擊檢查器中的 選擇 Widget 模式 按鈕。

對於某些屬性，例如 flex 係數、flex 擬合和對齊方式，您可以透過資源管理器中的下拉列表修改該值。修改 Widget 屬性時，您不僅會在 flex 資源管理器中看到新值，還會看到在執行 Flutter 應用的裝置上反映的新值。資源管理器會在屬性更改時進行動畫處理，以便清楚地瞭解更改的效果。從佈局資源管理器進行的 Widget 屬性更改不會修改您的原始碼，並且會在熱過載時還原。

Flex 資源管理器支援修改 mainAxisAlignment、crossAxisAlignment 和 FlexParentData.flex。將來，我們可能會新增對其他屬性的支援，例如 mainAxisSize、textDirection 和 FlexParentData.fit。

mainAxisAlignment

支援的值

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

crossAxisAlignment

支援的值

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

FlexParentData.flex

Flex 資源管理器在 UI 中支援 7 個 flex 選項（null、0、1、2、3、4、5），但從技術上講，flex Widget 子 Widget 的 flex 係數可以是任何 int。

Flexible.fit

Flex 資源管理器支援兩種不同型別的 FlexFit：loose 和 tight。

Flutter 檢查器提供了幾種用於以視覺方式除錯應用的選項。

啟用後，此選項以 5 倍的速度執行動畫，以便更輕鬆地進行視覺檢查。如果您想仔細觀察和調整看起來不太對勁的動畫，這將非常有用。

這也可以在程式碼中設定

import 'package:flutter/scheduler.dart';
​
void setSlowAnimations() {
  timeDilation = 5.0;
}

這會將動畫速度降低 5 倍。

以下連結提供更多資訊。

• Flutter 文件：timeDilation 屬性

以下螢幕錄影顯示了減慢動畫前後的情況。

此功能在您的應用上繪製引導線，顯示 Render 框、對齊方式、填充、滾動檢視、剪下和間隔。

此工具可用於更好地理解您的佈局。例如，透過查詢不需要的填充或瞭解 Widget 對齊方式。

您也可以在程式碼中啟用它

import 'package:flutter/rendering.dart';
​
void showLayoutGuidelines() {
  debugPaintSizeEnabled = true;
}

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

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

填充顯示為半透明的藍色背景

具有滾動內容的 Widget（例如列表檢視）顯示為綠色箭頭

例如，在使用 ClipRect Widget 時，剪下顯示為帶有剪刀圖示的虛線粉色線

間隔 Widget 顯示為灰色背景，例如此 SizedBox 沒有子 Widget

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

這對於檢查文字是否精確垂直對齊非常有用。例如，以下螢幕截圖中的文字基線略有錯位

可以使用 Baseline Widget 調整基線。

在任何具有設定基線的 Render 框 上繪製一條線；字母基線顯示為綠色，表意文字基線顯示為黃色。

您也可以在程式碼中啟用它

import 'package:flutter/rendering.dart';
​
void showBaselines() {
  debugPaintBaselinesEnabled = true;
}

此選項會在所有 渲染框周圍繪製邊框，每次該框重繪時邊框顏色都會改變。

這種旋轉的彩虹色對於查詢應用程式中重繪過於頻繁的部分，以及可能損害效能的部分非常有用。

例如，一個小動畫可能會導致整個頁面在每一幀都重繪。將動畫包裝在 RepaintBoundary 元件中，可以將重繪限制在該動畫內。

這裡進度指示器導致其容器重繪

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 元件具有權衡。它們可以幫助提高效能，但它們也具有建立新畫布的開銷，這會使用額外的記憶體。

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

import 'package:flutter/rendering.dart';
​
void highlightRepaints() {
  debugRepaintRainbowEnabled = true;
}

此選項透過反轉顏色和垂直翻轉來突出顯示尺寸過大的影像

突出顯示的影像使用的記憶體超過了實際需要的記憶體；例如，一個大型的 5MB 影像顯示為 100 畫素 x 100 畫素。

這些影像可能導致效能下降，尤其是在低端裝置上，並且當您有很多影像時（例如在列表檢視中），效能下降會累積。有關每個影像的資訊將在除錯控制檯中打印出來

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

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

您可以透過將 --no-track-widget-creation 傳遞給 flutter run 命令來停用此功能。

以下是啟用和停用跟蹤元件建立時您的元件樹可能看起來的示例。

啟用跟蹤元件建立（預設）

停用跟蹤元件建立（不推薦）

此功能可防止在除錯構建中將否則相同的 const 元件視為相等。有關更多詳細資訊，請參閱 除錯常見問題中的討論。

將滑鼠懸停在任何元件上都會顯示其屬性和值。

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

啟用後，元件樹將在熱過載或導航事件後自動重新整理。

啟用後，請使用 舊版 inspector 代替新的 inspector。

預設情況下，DevTools 將元件樹中顯示的元件限制為在專案根目錄中建立的元件。要檢視所有元件，包括在專案根目錄之外建立的元件，請開啟 顯示實現元件。

為了在預設元件樹中包含其他元件，必須將它們的父目錄新增到包目錄。

例如，考慮以下目錄結構

project_foo
  pkgs
    project_foo_app
    widgets_A
    widgets_B

從 project_foo_app 執行您的應用程式只會顯示 project_foo/pkgs/project_foo_app 中的元件在元件 inspector 樹中。

要在元件樹中顯示 widgets_A 中的元件，請將 project_foo/pkgs/widgets_A 新增到包目錄。

要在元件樹中顯示專案根目錄中的所有元件，請將 project_foo 新增到包目錄。

對您的包目錄所做的更改將在下次開啟應用程式的元件 inspector 時保留。

有關 inspector 可以實現的一般功能的演示，請參閱 2018 DartConf 演講，演示了 IntelliJ 版本 Flutter inspector。

要了解如何使用 DevTools 視覺除錯佈局問題，請檢視一個引導式的 Flutter Inspector 教程。