作為開發者，我們經常會遇到這樣的需求：管理后臺中的列表數據需要按照特定的順序展示，而且這個順序需要管理員能夠隨時調整。傳統的做法是為每條數據添加一個“排序”字段，然后讓管理員手動輸入數字來調整。這種方式在數據量少時尚可接受，但一旦數據增多，手動調整就變得異常繁瑣、效率低下，且極易出錯，嚴重影響了后臺管理體驗。我們渴望一種更直觀、更高效的方式，比如拖拽排序或簡單的上下移動按鈕。
幸運的是，php 生態系統中的 composer 和其豐富的包管理能力，總能為我們帶來驚喜。今天我們要介紹的，正是這樣一個能徹底解決 Sonata Admin 列表排序痛點的利器——runroom-packages/sortable-behavior-bundle。
遇到的痛點：手動排序的困境
想象一下，你正在為一個內容管理系統開發后臺，其中包含新聞列表、產品列表、FAQ 等多個模塊。每個模塊的條目都需要按照特定的優先級展示。如果只是簡單地通過修改數據庫中的 sort_order 字段來調整，管理員需要：
- 記住當前條目的排序值。
- 找到目標位置條目的排序值。
- 計算并輸入新的排序值，同時可能需要調整其他條目的值以避免沖突。
- 在數據量大時，這個過程簡直是噩夢。
這不僅耗時耗力，而且用戶體驗極差，很容易讓人產生抵觸情緒。作為開發者，我們深知這種重復且低效的操作會大大降低工作效率。
Composer 帶來的解決方案：runroom-packages/sortable-behavior-bundle
當我在為 Sonata Admin 尋找一個優雅的排序解決方案時，runroom-packages/sortable-behavior-bundle 進入了我的視野。它提供了一種開箱即用的方式，能夠輕松地為 Sonata Admin 的列表視圖添加排序功能，無論是簡單的上下移動按鈕，還是更高級的拖拽排序，都能通過簡單的配置實現。
這個 Bundle 的核心思想是與 Gedmo Sortable 行為（一個流行的 Doctrine 擴展，用于處理實體排序）無縫集成。即使你沒有使用 Gedmo，它也提供了默認的 ORM 實現，兼容性非常好。
如何使用 runroom-packages/sortable-behavior-bundle
使用這個 Bundle 來解決排序問題，流程非常清晰和簡單：
1. 安裝 Bundle
首先，通過 Composer 將其添加到你的項目中：
composer require runroom-packages/sortable-behavior-bundle
然后，在 config/bundles.php 中啟用它：
// config/bundles.php return [ // ... RunroomSortableBehaviorBundleRunroomSortableBehaviorBundle::class => ['all' => true], ];
2. 實體集成：讓你的實體“可排序”
如果你已經使用了 Gedmo Sortable 并且你的實體中有一個名為 position 的字段來存儲排序位置，那么恭喜你，幾乎不需要額外配置。你只需要在實體中引入 Bundle 提供的 Sortable Trait：
// src/Entity/Example.php namespace AppEntity; use RunroomSortableBehaviorBundleBehaviorsSortable; use DoctrineORMMapping as ORM; // 如果是 Doctrine 實體 /** * @ORMEntity */ class Example { use Sortable; // 引入 Sortable Trait /** * @ORMId * @ORMGeneratedValue * @ORMColumn(type="integer") */ private $id; // ... 其他字段和方法 }
這個 Sortable Trait 會自動為你的實體添加一個 position 字段，并與 Gedmo Sortable 配合，自動處理排序邏輯。
3. Admin 類集成：在后臺添加排序操作
接下來，在你的 Sonata Admin 類中引入 SortableAdminTrait，并配置列表視圖以顯示排序操作：
// src/Admin/ExampleAdmin.php namespace AppAdmin; use RunroomSortableBehaviorBundleAdminSortableAdminTrait; use SonataAdminBundleAdminAbstractAdmin; use SonataAdminBundleDatagridListMapper; class ExampleAdmin extends AbstractAdmin { use SortableAdminTrait; // 引入 SortableAdminTrait protected function configureListFields(ListMapper $list): void { $list // ... 你其他的列表字段 ->add(ListMapper::NAME_ACTIONS, ListMapper::TYPE_ACTIONS, [ 'actions' => [ // ... 你其他的操作按鈕 'move' => [ 'template' => '@RunroomSortableBehavior/sort.html.twig', // 默認的上下移動按鈕模板 ], ], ]); } }
完成這些步驟后，刷新你的 Sonata Admin 頁面，你就會在列表的“操作”列中看到上下移動的箭頭按鈕了！點擊這些按鈕，即可輕松調整條目的顯示順序。
4. 進階：實現拖拽排序
如果你想要更現代、更直觀的拖拽排序體驗，runroom-packages/sortable-behavior-bundle 也提供了支持。只需將 move 操作的模板改為 @RunroomSortableBehavior/sort_drag_drop.html.twig 即可：
// src/Admin/ExampleAdmin.php protected function configureListFields(ListMapper $list): void { $list // ... 其他列表字段 ->add(ListMapper::NAME_ACTIONS, ListMapper::TYPE_ACTIONS, [ 'actions' => [ // ... 其他操作按鈕 'move' => [ 'template' => '@RunroomSortableBehavior/sort_drag_drop.html.twig', // 拖拽排序模板 'enable_top_bottom_buttons' => true, // 可選：是否同時顯示置頂/置底按鈕 ], ], ]); }
現在，你的列表條目就可以通過拖拽來調整順序了，這無疑大大提升了管理員的操作效率和體驗。
5. 配置（非 Gedmo 用戶或自定義字段）
如果你沒有使用 Gedmo Sortable，或者你的排序字段名稱不是 position，你可以在 config/packages/runroom_sortable_behavior.yaml 中進行配置：
# config/packages/runroom_sortable_behavior.yaml runroom_sortable_behavior: position_handler: RunroomSortableBehaviorBundleServiceORMPositionHandler # 如果不使用 Gedmo position_field: default: position # 默認字段名 entities: AppEntityFoobar: order # 為特定實體指定排序字段名 AppEntityBaz: rang sortable_groups: # 如果需要按組排序 entities: AppEntityBaz: [group]
總結與實際應用效果
通過引入 runroom-packages/sortable-behavior-bundle，我徹底解決了后臺列表手動排序的痛點，帶來了以下顯著優勢：
- 極簡集成：得益于 Composer 和 Bundle 機制，安裝和配置都非常簡單，幾乎是“開箱即用”。
- 開發效率提升：無需編寫復雜的排序邏輯、數據庫更新代碼和前端交互腳本，大大節省了開發時間。
- 用戶體驗優化：管理員可以直觀地通過上下箭頭或拖拽來調整列表順序，操作更加便捷、高效，降低了學習成本和出錯率。
- 靈活性：同時支持 Gedmo Sortable 和自定義 ORM 實現，并提供了兩種排序 UI 模式（按鈕/拖拽），滿足不同項目需求。
- 維護成本降低：將排序邏輯交給成熟的第三方 Bundle 處理，減少了項目的自定義代碼量，使得后期維護更加容易。
現在，我的后臺管理效率得到了顯著提升，管理員們對這種直觀的排序方式贊不絕口。如果你也在為 symfony/Sonata Admin 項目中的列表排序問題而煩惱，那么 runroom-packages/sortable-behavior-bundle 絕對值得你一試！
