set_screen_options()
云策文档标注
概述
set_screen_options() 函数用于保存 WordPress 后台列表页面(如文章、页面、评论等)的每页显示行数选项。它处理用户提交的屏幕选项数据,验证并存储到用户元数据中。
关键要点
- 函数主要处理 $_POST['wp_screen_options'] 数据,包含 option 和 value 字段。
- 通过 check_admin_referer() 验证安全 nonce,确保请求来自合法来源。
- 对 option 进行 sanitize_key() 清理,并映射标准选项如 edit_per_page、users_per_page 等。
- 值验证:标准选项的值被强制转换为整数,并限制在 1 到 999 之间。
- 支持过滤器:apply_filters('set-screen-option', ...) 和 apply_filters("set_screen_option_{$option}", ...) 允许自定义选项处理。
- 使用 update_user_meta() 保存选项到当前用户元数据,然后重定向回原页面。
代码示例
// 示例:标准选项处理流程
if ( isset( $_POST['wp_screen_options'] ) ) {
$option = $_POST['wp_screen_options']['option'];
$value = $_POST['wp_screen_options']['value'];
// 验证和保存逻辑
}注意事项
- 函数仅处理以 '_page' 结尾或 'layout_columns' 的选项时,会触发 set-screen-option 过滤器。
- 动态过滤器 set_screen_option_{$option} 允许针对特定选项进行更精细的控制。
- 返回 false 从过滤器将跳过当前选项的保存。
原文内容
Saves option for number of rows when listing posts, pages, comments, etc.
Source
function set_screen_options() {
if ( ! isset( $_POST['wp_screen_options'] ) || ! is_array( $_POST['wp_screen_options'] ) ) {
return;
}
check_admin_referer( 'screen-options-nonce', 'screenoptionnonce' );
$user = wp_get_current_user();
if ( ! $user ) {
return;
}
$option = $_POST['wp_screen_options']['option'];
$value = $_POST['wp_screen_options']['value'];
if ( sanitize_key( $option ) !== $option ) {
return;
}
$map_option = $option;
$type = str_replace( 'edit_', '', $map_option );
$type = str_replace( '_per_page', '', $type );
if ( in_array( $type, get_taxonomies(), true ) ) {
$map_option = 'edit_tags_per_page';
} elseif ( in_array( $type, get_post_types(), true ) ) {
$map_option = 'edit_per_page';
} else {
$option = str_replace( '-', '_', $option );
}
switch ( $map_option ) {
case 'edit_per_page':
case 'users_per_page':
case 'edit_comments_per_page':
case 'upload_per_page':
case 'edit_tags_per_page':
case 'plugins_per_page':
case 'export_personal_data_requests_per_page':
case 'remove_personal_data_requests_per_page':
// Network admin.
case 'sites_network_per_page':
case 'users_network_per_page':
case 'site_users_network_per_page':
case 'plugins_network_per_page':
case 'themes_network_per_page':
case 'site_themes_network_per_page':
$value = (int) $value;
if ( $value < 1 || $value > 999 ) {
return;
}
break;
default:
$screen_option = false;
if ( str_ends_with( $option, '_page' ) || 'layout_columns' === $option ) {
/**
* Filters a screen option value before it is set.
*
* The filter can also be used to modify non-standard `[items]_per_page`
* settings. See the parent function for a full list of standard options.
*
* Returning false from the filter will skip saving the current option.
*
* @since 2.8.0
* @since 5.4.2 Only applied to options ending with '_page',
* or the 'layout_columns' option.
*
* @see set_screen_options()
*
* @param mixed $screen_option The value to save instead of the option value.
* Default false (to skip saving the current option).
* @param string $option The option name.
* @param int $value The option value.
*/
$screen_option = apply_filters( 'set-screen-option', $screen_option, $option, $value ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores
}
/**
* Filters a screen option value before it is set.
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
* Returning false from the filter will skip saving the current option.
*
* @since 5.4.2
*
* @see set_screen_options()
*
* @param mixed $screen_option The value to save instead of the option value.
* Default false (to skip saving the current option).
* @param string $option The option name.
* @param int $value The option value.
*/
$value = apply_filters( "set_screen_option_{$option}", $screen_option, $option, $value );
if ( false === $value ) {
return;
}
break;
}
update_user_meta( $user->ID, $option, $value );
$url = remove_query_arg( array( 'pagenum', 'apage', 'paged' ), wp_get_referer() );
if ( isset( $_POST['mode'] ) ) {
$url = add_query_arg( array( 'mode' => $_POST['mode'] ), $url );
}
wp_safe_redirect( $url );
exit;
}
Hooks
- apply_filters( ‘set-screen-option’, mixed $screen_option, string $option, int $value )
-
Filters a screen option value before it is set.
- apply_filters( “set_screen_option_{$option}”, mixed $screen_option, string $option, int $value )
-
Filters a screen option value before it is set.
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |