作为开发者，我们经常会遇到这样的需求：管理后台中的列表数据需要按照特定的顺序展示，而且这个顺序需要管理员能够随时调整。传统的做法是为每条数据添加一个“排序”字段，然后让管理员手动输入数字来调整。这种方式在数据量少时尚可接受，但一旦数据增多，手动调整就变得异常繁琐、效率低下，且极易出错，严重影响了后台管理体验。我们渴望一种更直观、更高效的方式，比如拖拽排序或简单的上下移动按钮。
幸运的是，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 [
// ...
Runroom\SortableBehaviorBundle\RunroomSortableBehaviorBundle::class => ['all' => true],
];2. 实体集成：让你的实体“可排序”
如果你已经使用了 Gedmo Sortable 并且你的实体中有一个名为 position 的字段来存储排序位置，那么恭喜你，几乎不需要额外配置。你只需要在实体中引入 Bundle 提供的 Sortable Trait：
// src/Entity/Example.php
namespace App\Entity;
use Runroom\SortableBehaviorBundle\Behaviors\Sortable;
use Doctrine\ORM\Mapping as ORM; // 如果是 Doctrine 实体
/**
* @ORM\Entity
*/
class Example
{
use Sortable; // 引入 Sortable Trait
/**
* @ORM\Id
* @ORM\GeneratedValue
* @ORM\Column(type="integer")
*/
private $id;
// ... 其他字段和方法
}这个 Sortable Trait 会自动为你的实体添加一个 position 字段，并与 Gedmo Sortable 配合，自动处理排序逻辑。
3. Admin 类集成：在后台添加排序操作
接下来，在你的 Sonata Admin 类中引入 SortableAdminTrait，并配置列表视图以显示排序操作：
// src/Admin/ExampleAdmin.php
namespace App\Admin;
use Runroom\SortableBehaviorBundle\Admin\SortableAdminTrait;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\ListMapper;
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: Runroom\SortableBehaviorBundle\Service\ORMPositionHandler # 如果不使用 Gedmo
position_field:
default: position # 默认字段名
entities:
App\Entity\Foobar: order # 为特定实体指定排序字段名
App\Entity\Baz: rang
sortable_groups: # 如果需要按组排序
entities:
App\Entity\Baz: [group]总结与实际应用效果
通过引入 runroom-packages/sortable-behavior-bundle，我彻底解决了后台列表手动排序的痛点，带来了以下显著优势：
- 极简集成：得益于 Composer 和 Bundle 机制，安装和配置都非常简单，几乎是“开箱即用”。
- 开发效率提升：无需编写复杂的排序逻辑、数据库更新代码和前端交互脚本，大大节省了开发时间。
- 用户体验优化：管理员可以直观地通过上下箭头或拖拽来调整列表顺序，操作更加便捷、高效，降低了学习成本和出错率。
- 灵活性：同时支持 Gedmo Sortable 和自定义 ORM 实现，并提供了两种排序 UI 模式（按钮/拖拽），满足不同项目需求。
- 维护成本降低：将排序逻辑交给成熟的第三方 Bundle 处理，减少了项目的自定义代码量，使得后期维护更加容易。
现在，我的后台管理效率得到了显著提升，管理员们对这种直观的排序方式赞不绝口。如果你也在为 Symfony/Sonata Admin 项目中的列表排序问题而烦恼，那么 runroom-packages/sortable-behavior-bundle 绝对值得你一试！
