manage_{$this->screen->id}_sortable_columns
云策文档标注
概述
manage_{$this->screen->id}_sortable_columns 是一个 WordPress 过滤器钩子，用于自定义特定屏幕（如文章列表页）中表格列的可排序行为。它允许开发者通过动态钩子名称（基于屏幕 ID）添加、移除或修改可排序列。
关键要点
- 这是一个动态钩子，名称中的 $this->screen->id 指代当前屏幕的 ID，例如 edit-post 对应文章列表页。
- 参数 $sortable_columns 是一个数组，用于定义可排序列；从 WordPress 6.3.0 起，该数组支持多维结构，可指定缩写、排序文本和初始排序顺序。
- 常用于 WP_List_Table::get_column_info() 方法中，应用于后台列表表格的列信息处理。
- 钩子自 WordPress 3.1.0 引入，适用于自定义文章类型、多站点网络等场景。
代码示例
// 移除文章列表页的标题列排序功能
add_filter( 'manage_edit-post_sortable_columns', 'slug_title_not_sortable' );
function slug_title_not_sortable( $cols ) {
unset( $cols['title'] );
return $cols;
}
// 为自定义文章类型 'flowers' 添加 menu_order 列排序（WordPress 6.3.0+ 格式）
$my_post_type = 'flowers';
$menu_order_sortable_on_screen = 'edit-' . $my_post_type;
add_filter(
'manage_' . $menu_order_sortable_on_screen . '_sortable_columns',
function ( $columns ) {
$columns['menu_order'] = array(
'menu_order',
true,
__( 'Menu Order' ),
__( 'Table ordered by menu order.' ),
'asc'
);
return $columns;
}
);
// 多站点网络中站点列表页的排序钩子示例
add_filter('manage_sites-network_sortable_columns', ...);注意事项
- 钩子名称需根据屏幕 ID 动态构建，例如 edit-post 对应文章列表，edit-flowers 对应自定义文章类型 flowers 的列表页。
- 从 WordPress 6.3.0 开始，$sortable_columns 参数变为多维数组，支持更详细的排序配置，如初始排序方向（asc/desc）。
- 在多站点网络中，站点列表页的钩子应为 manage_sites-network_sortable_columns，而非 manage_sites_sortable_columns。
- 使用匿名函数时，注意参数传递和返回值，确保数组结构正确。
原文内容
Filters the list table sortable columns for a specific screen.
Description
The dynamic portion of the hook name, $this->screen->id, refers to the ID of the current screen.
Parameters
$sortable_columnsarray-
An array of sortable columns.
Source
$_sortable = apply_filters( "manage_{$this->screen->id}_sortable_columns", $sortable_columns );
Changelog
| Version | Description |
|---|---|
| 3.1.0 | Introduced. |
Skip to note 5 content
websupporter
As an example. When you see the table with the posts in the admin screen, you can sort the posts by title. If you wanted to remove the ability to sort by the title you could do the following:
The screen ID for the posts overview page in the admin is
edit-post, so the filter would be “manage_edit-post_sortable_columns”.add_filter( 'manage_edit-post_sortable_columns', 'slug_title_not_sortable' ); function slug_title_not_sortable( $cols ) { unset( $cols['title'] ); return $cols; }Skip to note 6 content
jave.web
For the list of custom type, the hook name is a COMBINATION of edit and the custom post type, so let’s say you have custom post type
flowersand you want to add sorting by e.g.menu_orderyou’ve added before, the hook would be called “manage_edit-flowers_sortable_columns’ – the hook code could look something like:$my_post_type = 'flowers'; // actually a screen name of the LIST page of posts $menu_order_sortable_on_screen = 'edit-' . $my_post_type; add_filter( 'manage_' . $menu_order_sortable_on_screen . '_sortable_columns', function( $columns ) { $columns['menu_order'] = 'menu_order'; return $columns; } );If you are interested how would you add the
menu_ordersupport to a post type in the first place:// the basic support add_post_type_support( $my_post_type, 'page-attributes' ); // add a column to the post type's admin add_filter( 'manage_' . $my_post_type . '_posts_columns', function( $columns ) { $columns['menu_order'] = __( 'Order', 'textdomain' ); return $columns; } ); // display the column value add_action( 'manage_' . $my_post_type . '_posts_custom_column', function( $column_name, $post_id ) { if ( 'menu_order' === $column_name ) { echo __( get_post( $post_id )->menu_order, 'textdomain' ); } }, 10, 2 ); // priority, number of args - MANDATORY HERE! // ... and make it sortable with the code from the startSkip to note 7 content
Tessa (they/them), AuRise Creative
As of WordPress version 6.3.0, the
$sortable_columnsparameter is now a multidimensional array where you can also now specify abbreviations, orderby text, and the initial sorting order. For example, this is what is dumped for theedit-postscreen:array (size=4) 'title' => array (size=4) 0 => string 'title' (length=5) 1 => boolean false 2 => string 'Title' (length=5) 3 => string 'Table ordered by Title.' (length=23) 'parent' => array (size=2) 0 => string 'parent' (length=6) 1 => boolean false 'comments' => array (size=4) 0 => string 'comment_count' (length=13) 1 => boolean false 2 => string 'Comments' (length=8) 3 => string 'Table ordered by Comments.' (length=26) 'date' => array (size=5) 0 => string 'date' (length=4) 1 => boolean true 2 => string 'Date' (length=4) 3 => string 'Table ordered by Date.' (length=22) 4 => string 'desc' (length=4)Ignoring the
parentcolumn, bothtitleandcommentsdemonstrate what a standard sortable column looks like. Thedatecolumn is initialised to display the posts in descending order.Using jave.web’s example from 4 years ago, the code could now look like this:
$my_post_type = 'flowers'; // actually a screen name of the LIST page of posts $menu_order_sortable_on_screen = 'edit-' . $my_post_type; add_filter( 'manage_' . $menu_order_sortable_on_screen . '_sortable_columns', function ( $columns ) { $columns['menu_order'] = array( 'menu_order', // Menu's internal name, same as key in array true, // Initialise with my specified order, false to disregard __( 'Menu Order' ), // Short column name (abbreviation) for `abbr` attribute __( 'Table ordered by menu order.' ), // Translatable string of a brief description to be used for the current sorting 'asc' // Initialise in ascending order, can also be 'desc', false, or omitted to default to false ); return $columns; } );Skip to note 8 content
Nagmay
Looking to sort the columns for the “sites” page in a multisite network? The following does not work as expected:
add_filter('manage_sites_sortable_columns', ...Instead, try:
add_filter('manage_sites-network_sortable_columns', ...