Skip to main content

棄用 onReorder 回呼（callback）

onReorder 回呼（callback）已被棄用， 改以新的回呼（callback）onReorderItem 取代。

摘要

#

ReorderableListView、ReorderableListView.builder、 ReorderableList 及 SliverReorderableList 元件 (Widget) 中的 onReorder 回呼（callback）已被新的回呼（callback）onReorderItem 取代， 後者為 newIndex 提供了更直覺的行為。

背景

#

ReorderableListView、ReorderableListView.builder、 ReorderableList 及 SliverReorderableList 元件中的 onReorder 回呼（callback）， 在 oldIndex 位於 newIndex 之前的情況下， 需要對第二個參數 newIndex 進行手動修正， 因為此時項目清單會縮短一個元素。

dart 
void handleReorder(int oldIndex, int newIndex) {
  if (oldIndex < newIndex) {
    // Removing the item at oldIndex shortens the list by 1.
    newIndex -= 1;
  }
​
  // Handle the actual reorder behavior...
}
​
ReorderableListView(
  onReorder: handleReorder,
)

新的回呼（callback）onReorderItem 透過自動進行修正來解決此問題。

dart 
void handleReorder(int oldIndex, int newIndex) {
  // Handle the actual reorder behavior...
}
​
ReorderableListView(
  onReorderItem: handleReorder,
)

遷移指南

#

ReorderableListView、ReorderableListView.builder、 ReorderableList 及 SliverReorderableList 元件 共用相同的排序邏輯。 相同的遷移步驟適用於上述每個元件。

本遷移指南以 ReorderableListView 作為範例。

情況一：簡單的回呼（callback）

#

遷移前的程式碼：

dart 
ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
    if (oldIndex < newIndex) {
      newIndex -= 1;
    }
​
    // Handle reorder ...
  }
)

遷移後的程式碼：

dart 
ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
    if (oldIndex < newIndex) {
      newIndex -= 1;
    }
​
  onReorderItem: (int oldIndex, int newIndex) {
    // Handle reorder ...
  }
)

情況二：針對複雜 onReorder 實作的退出方案

#

在某些情況下，例如所提供的回呼（callback）較為複雜時， 遷移至新的 onReorderItem 回呼（callback）可能並不直觀。

在這些情況下，若要退出新的行為， 請調整 newIndex 以符合舊有行為。

遷移前的程式碼：

dart 
void handleSomeComplexReorder(int oldIndex, int newIndex) {
  // Handle reorder ...
}
​
ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
    handleSomeComplexReorder(oldIndex, newIndex);
  }
)

遷移後的程式碼：

dart 
void handleSomeComplexReorder(int oldIndex, int newIndex) {
  // Handle reorder ...
}
​
ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
  onReorderItem: (int oldIndex, int newIndex) {
    // To get the equivalent of the old newIndex:
    if (oldIndex < newIndex) {
      newIndex += 1;
    }
​
    return handleSomeComplexReorder(oldIndex, newIndex);
  }
)

時間表

#

版本導入：3.41.0-1.0.pre-364
穩定版發布：3.44

參考資料

#

API 文件：

相關 Issue：

相關 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.