使用舊版 Flutter Inspector

以下是 Inspector 工具列中可用功能的導覽說明。當空間有限時，會以圖示作為標籤的視覺化版本。

選取元件模式（Select widget mode）

啟用此按鈕後，可以在裝置上選取元件進行檢查。欲了解更多，請參閱檢查元件。

重新整理樹狀結構（Refresh tree）

重新載入目前元件的資訊。

慢速動畫（Slow animations）

讓動畫以 5 倍慢速運行，方便微調動畫效果。

顯示輔助線（Show guidelines）

疊加輔助線，有助於修正版面配置問題。

顯示基線（Show baselines）

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

高亮重繪（Highlight repaints）

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

高亮超大圖片（Highlight oversized images）

反轉顏色並翻轉圖片，突顯佔用過多記憶體的圖片。

你可以瀏覽互動式元件樹（widget tree），以檢視附近的元件及其欄位值。

若要在元件樹中定位個別 UI 元素，請點擊工具列中的 選取元件模式（Select Widget Mode） 按鈕。這會讓裝置上的應用程式進入「元件選取」模式。點擊應用程式 UI 中的任一元件，即可選取該元件，並將元件樹自動捲動到對應的節點。再次切換 選取元件模式 按鈕即可離開元件選取模式。

在除錯版面配置問題時，關鍵要查看的欄位是 size 和 constraints。constraints（約束）會自樹狀結構向下傳遞，而 size（尺寸）則會向上回傳。欲了解此運作方式，請參閱理解 constraints（約束）。

Flutter Layout Explorer 可協助你更好地理解 Flutter 的版面配置。

想快速了解這個工具的功能，請參閱 Flutter Explorer 影片：

你也可以參考以下逐步說明的文章：

• 如何使用 Flutter Inspector 除錯版面配置問題

在 Flutter Inspector 中，選取一個元件。Layout Explorer 同時支援 flex 版面配置 與固定尺寸（fixed size）版面配置，並針對這兩種類型提供專屬工具。

當你選取一個 flex 元件（例如 Row、Column、Flex）或其直接子元件時，flex 版面配置工具會在 Layout Explorer 中顯示。

Layout Explorer 會視覺化 Flex 元件及其子元件的版面配置情形。Explorer 會標示主軸（main axis）與交錯軸（cross axis），以及各自目前的對齊方式（例如 start、end、spaceBetween）。同時也會顯示如 flex factor、flex fit 與 layout constraints（版面配置約束）等細節。

此外，Explorer 會顯示版面配置約束違規（constraint violations）及 render overflow（渲染溢位）錯誤。違規的版面配置約束會以紅色標示，溢位錯誤則會以標準的「黃色警示條」圖樣呈現，就像你在實機上看到的一樣。這些視覺化效果旨在幫助你理解溢位錯誤發生的原因，以及如何修正。

在 Layout Explorer 中點擊某個元件，會同步選取裝置上的 Inspector。此功能需啟用 選取元件模式（Select Widget Mode）。如需啟用，請點擊 Inspector 中的 選取元件模式 按鈕。

對於某些屬性（如 flex factor、flex fit 與 alignment），你可以透過 Explorer 中的下拉選單修改其值。當你修改元件屬性時，變更會即時反映在 Layout Explorer 及執行中的 Flutter 應用程式裝置上。Explorer 會針對屬性變更進行動畫顯示，讓變化效果更加明顯。透過 Layout Explorer 修改的元件屬性不會變更你的原始程式碼，並會在 hot reload 時還原。

Layout Explorer 支援修改 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

Layout Explorer 在 UI 中支援 7 種 flex 選項（null、0、1、2、3、4、5），但技術上 flex 元件子項的 flex factor 可以是任意整數。

Layout Explorer 支援兩種不同的 FlexFit：loose 與 tight。

當你選取一個不是 flex 元件子項的固定尺寸元件時，Layout Explorer 會顯示固定尺寸版面配置資訊。你可以查看所選元件及其最近的上游 RenderObject 的尺寸、約束與內距（padding）資訊。

Flutter Inspector 提供多種選項，協助你以視覺化方式除錯應用程式。

啟用此選項時，動畫會以 5 倍慢速運行，方便進行視覺檢查。 如果你想仔細觀察並微調動畫效果，這會非常有用。

你也可以在程式碼中設定：

import 'package:flutter/scheduler.dart';

void setSlowAnimations() {
  timeDilation = 5.0;
}

這會將動畫（Animation）速度減慢 5 倍。

以下連結提供更多資訊。

• Flutter 文件：timeDilation 屬性

以下螢幕錄影分別展示了動畫速度變慢前後的效果。

此功能會在您的應用程式上繪製輔助線，顯示 render boxes、對齊（alignments）、間距（paddings）、滾動視圖（scroll views）、裁剪（clippings）以及 spacer。

這個工具可協助您更好地理解版面配置。例如，可以用來找出不必要的間距，或了解元件（Widget）的對齊方式。

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

import 'package:flutter/rendering.dart';

void showLayoutGuidelines() {
  debugPaintSizeEnabled = true;
}

會在螢幕上繪製的元件（Widgets）會建立一個 render box，這是 Flutter 版面配置的基礎組件。這些 render box 會以亮藍色邊框顯示：

對齊會以黃色箭頭顯示。這些箭頭表示元件相對於其父元件的垂直與水平偏移量。 例如，下方這個按鈕的圖示，透過四個箭頭顯示其已置中：

Padding 會以半透明藍色背景顯示：

具有可捲動內容的元件（例如 ListView）會以綠色箭頭顯示：

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

Spacer 元件會以灰色背景顯示， 例如這個沒有 child 的 SizedBox：

啟用此選項後，所有基線（baseline）都會顯示出來。 基線是用來定位文字的水平線。

這對於檢查文字是否垂直精確對齊很有幫助。 例如，下方螢幕截圖中的文字基線就有些微不對齊：

你可以使用 Baseline 元件來調整基線。

任何有設定基線的 render box 都會畫出一條線； 字母基線（alphabetic）以綠色顯示，表意基線（ideographic）則以黃色顯示。

你也可以在程式碼中啟用這個功能：

import 'package:flutter/rendering.dart';

void showBaselines() {
  debugPaintBaselinesEnabled = true;
}

此選項會在所有 render boxes 周圍繪製一個邊框，並且每當該區塊重繪時，邊框顏色都會改變。

這種不斷變換的彩虹色邊框，有助於你找出應用程式中過於頻繁重繪、可能影響效能的部分。

舉例來說，一個小型動畫（Animation）可能導致整個頁面在每一幀都被重繪。
將動畫包裹在 RepaintBoundary widget 中，可以將重繪範圍限制在動畫本身。

以下範例中，進度指示器會導致其容器（Container）被重繪：

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 元件（Widgets）有其取捨。它們有助於提升效能， 但同時也會產生建立新 canvas 的額外負擔， 這會佔用更多記憶體。

你也可以在程式碼中啟用這個選項：

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 documentation: debugInvertOversizedImages

選擇 Widget Details Tree 分頁，可以顯示所選元件（Widget）的詳細樹。你可以在這裡取得該元件的屬性、Render Object 以及子元件（children）的相關資訊。

Flutter Inspector 的部分功能是透過插裝（instrumenting）應用程式程式碼，以更好地了解元件（Widgets）建立時的原始碼位置。這種原始碼插裝讓 Flutter Inspector 能以接近你在原始碼中定義 UI 的方式來顯示元件樹。若未啟用此功能，元件樹中的節點會更深，且較難理解執行時的元件階層與應用程式 UI 的對應關係。

你可以在 flutter run 指令中傳入 --no-track-widget-creation 來停用這個功能。

以下是啟用與未啟用追蹤元件建立時，元件樹可能呈現的範例：

啟用追蹤元件建立（預設）：

停用追蹤元件建立（不建議）：

此功能會讓在 debug 模式下，原本相同的 const 元件（Widgets）不會被視為相等。更多細節請參考 common problems when debugging 的討論。

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

切換此選項可啟用或停用滑鼠懸停檢查功能。

預設情況下，DevTools 僅顯示來自專案根目錄和 Flutter 的元件（Widgets）於元件樹中。這個篩選僅適用於 Inspector Widget Tree（Inspector 左側的元件樹），不影響 Widget Details Tree（Inspector 右側，與 Layout Explorer 同一分頁視圖）。在 Widget Details Tree 中，你可以看到所有套件中的所有元件。

若要顯示其他元件，必須將其父目錄加入到 Package Directories 中。

例如，考慮以下目錄結構：

project_foo
  pkgs
    project_foo_app
    widgets_A
    widgets_B

從 project_foo_app 執行您的應用程式時，元件檢查器（Widget Inspector）樹中只會顯示來自 project_foo/pkgs/project_foo_app 的元件（Widgets）。

若要在元件樹中顯示來自 widgets_A 的元件，請將 project_foo/pkgs/widgets_A 新增至套件目錄（package directories）。

若要在元件樹中從您的專案根目錄顯示 所有 元件，請將 project_foo 新增至套件目錄（package directories）。

對套件目錄（package directories）的變更會在下次為該應用程式開啟元件檢查器時持續生效。

若想了解元件檢查器（Inspector）的一般功能，請參考 DartConf 2018 talk，該影片展示了 IntelliJ 版本的 Flutter Inspector。

若想學習如何使用 DevTools 以視覺化方式除錯版面配置問題，請參考導覽式的 Flutter Inspector 教學。