settings_errors()
概述
settings_errors() 是 WordPress Settings API 的一部分，用于显示通过 add_settings_error() 注册的设置错误信息。它通常在基于 Settings API 的设置页面提交后自动调用，输出由 get_settings_errors() 获取的错误消息。
关键要点
- 函数属于 Settings API，用于输出设置错误，每个错误包装在 div 中。
- 错误应在 register_setting() 定义的设置验证回调函数中添加。
- 支持可选参数：$setting 指定特定设置的错误，$sanitize 控制是否重新清理设置值，$hide_on_update 控制更新后是否隐藏错误。
- 内部处理错误类型映射，如将 'updated' 映射为 'success'，并添加 CSS 类如 'notice-error'。
- 从 WordPress 3.0.0 版本引入，5.3.0 版本更新了 CSS 类映射。
代码示例
/**
* Displays all messages registered to 'your-settings-error-slug'
*/
function wpdocs_your_admin_notices_action() {
settings_errors( 'your-settings-error-slug' );
}
add_action( 'admin_notices', 'wpdocs_your_admin_notices_action' );Displays settings errors registered by add_settings_error() .
Description
Part of the Settings API. Outputs a div for each error retrieved by get_settings_errors() .
This is called automatically after a settings page based on the Settings API is submitted. Errors should be added during the validation callback function for a setting defined in register_setting() .
The $sanitize option is passed into get_settings_errors() and will re-run the setting sanitization on its current value.
The $hide_on_update option will cause errors to only show when the settings page is first loaded. if the user has already saved new values it will be hidden to avoid repeating messages already shown in the default error reporting after submission. This is useful to show general errors like missing settings when the user arrives at the settings page.
Parameters
$settingstringoptional-
Optional slug title of a specific setting whose errors you want.
$sanitizebooloptional-
Whether to re-sanitize the setting value before returning errors.
Default:
false $hide_on_updatebooloptional-
If set to true errors will not be shown if the settings page has already been submitted.
Default:
false
Source
function settings_errors( $setting = '', $sanitize = false, $hide_on_update = false ) {
if ( $hide_on_update && ! empty( $_GET['settings-updated'] ) ) {
return;
}
$settings_errors = get_settings_errors( $setting, $sanitize );
if ( empty( $settings_errors ) ) {
return;
}
$output = '';
foreach ( $settings_errors as $key => $details ) {
if ( 'updated' === $details['type'] ) {
$details['type'] = 'success';
}
if ( in_array( $details['type'], array( 'error', 'success', 'warning', 'info' ), true ) ) {
$details['type'] = 'notice-' . $details['type'];
}
$css_id = sprintf(
'setting-error-%s',
esc_attr( $details['code'] )
);
$css_class = sprintf(
'notice %s settings-error is-dismissible',
esc_attr( $details['type'] )
);
$output .= "<div id='$css_id' class='$css_class'> n";
$output .= "<p><strong>{$details['message']}</strong></p>";
$output .= "</div> n";
}
echo $output;
}
Skip to note 2 content
Codex
Example
/** * Displays all messages registered to 'your-settings-error-slug' */ function wpdocs_your_admin_notices_action() { settings_errors( 'your-settings-error-slug' ); } add_action( 'admin_notices', 'wpdocs_your_admin_notices_action' );