Skip to main content

將 MaterialState 重新命名為 WidgetState

MaterialState 及其相關 API 已移出 Material 函式庫， 並重新命名為 WidgetState。

摘要

#

MaterialState 及其相關 API 已從 Material 函式庫中移除， 並重新命名為 WidgetState。

背景

#

過去，MaterialState 提供了處理元件（Widget）可擁有的多種不同狀態的邏輯， 例如「滑鼠懸停（hovered）」、「獲得焦點（focused）」以及「已停用（disabled）」等。 由於這項功能在 Material 函式庫之外也很有用， 特別是在基礎 Widgets 層和 Cupertino， 因此決定將其移出 Material 函式庫。 作為這次調整的一部分，並為了避免未來產生混淆， 不同的 MaterialState 類別已重新命名為 WidgetState。 兩者的行為完全相同。

調整前調整後
MaterialStateWidgetState
MaterialStatePropertyResolverWidgetStatePropertyResolver
MaterialStateColorWidgetStateColor
MaterialStateMouseCursorWidgetStateColorMouseCursor
MaterialStateBorderSideWidgetStateBorderSide
MaterialStateOutlinedBorderWidgetStateOutlinedBorder
MaterialStateTextStyleWidgetStateTextStyle
MaterialStatePropertyWidgetStateProperty
MaterialStatePropertyAllWidgetStatePropertyAll
MaterialStatesControllerWidgetStatesController

MaterialStateOutlineInputBorder 和 MaterialStateUnderlineInputBorder 這兩個類別仍保留在 Material 函式庫中， 且沒有對應的 WidgetState，因為它們是 Material Design 專屬的。

遷移指南

#

提供了一個 Flutter fix，可協助將 MaterialState 類別遷移至 WidgetState。

若要遷移，請將 MaterialState 替換為 WidgetState。

遷移前的程式碼：

dart 
MaterialState selected = MaterialState.selected;
​
final MaterialStateProperty<Color> backgroundColor;
​
class _MouseCursor extends MaterialStateMouseCursor{
  const _MouseCursor(this.resolveCallback);
​
  final MaterialPropertyResolver<MouseCursor?> resolveCallback;
​
  @override
  MouseCursor resolve(Set<MaterialState> states) => resolveCallback(states) ?? MouseCursor.uncontrolled;
}
​
BorderSide side = MaterialStateBorderSide.resolveWith((Set<MaterialState> states) {
  if (states.contains(MaterialState.selected)) {
    return const BorderSide(color: Colors.red);
  }
  return null;
});

遷移後的程式碼：

dart 
WidgetState selected = WidgetState.selected;
​
final WidgetStateProperty<Color> backgroundColor;
​
class _MouseCursor extends WidgetStateMouseCursor{
  const _MouseCursor(this.resolveCallback);
​
  final WidgetPropertyResolver<MouseCursor?> resolveCallback;
​
  @override
  MouseCursor resolve(Set<WidgetState> states) => resolveCallback(states) ?? MouseCursor.uncontrolled;
}
​
BorderSide side = WidgetStateBorderSide.resolveWith((Set<WidgetState> states) {
  if (states.contains(WidgetState.selected)) {
    return const BorderSide(color: Colors.red);
  }
  return null;
});

時程

#

合併於版本：3.21.0-11.0.pre
進入穩定版：3.22.0

參考資料

#

相關議題（issues）：

相關 PR：

Unless stated otherwise, the documentation on this site reflects Flutter 3.44.0. Page last updated on 2026-06-14. View source or report an issue.