云策 WordPress 开发者社区

函数文档

add_settings_error()

查看官方原文 ↗
💡 云策文档标注

概述

add_settings_error() 是 WordPress Settings API 的一部分，用于向用户显示设置相关的错误或消息。它通常在 register_setting() 的 $sanitize_callback 函数中调用，以提供提交反馈。

关键要点

  • 函数用于注册设置错误，消息会默认在提交后立即显示，也可通过 settings_errors() 在首次访问设置页面时展示。
  • 参数包括 $setting（设置标识）、$code（错误代码）、$message（消息文本）和 $type（消息类型，如 'error'、'success'、'warning'、'info'）。
  • 消息类型在 WordPress 5.3.0 中新增了 'warning' 和 'info' 选项。

代码示例

function change( $data ) {
    $message = null;
    $type = null;
    if ( null != $data ) {
        if ( false === get_option( 'myOption' ) ) {
            add_option( 'myOption', $data );
            $type = 'updated';
            $message = __( 'Successfully saved', 'my-text-domain' );
        } else {
            update_option( 'myOption', $data );
            $type = 'updated';
            $message = __( 'Successfully updated', 'my-text-domain' );
        }
    } else {
        $type = 'error';
        $message = __( 'Data can not be empty', 'my-text-domain' );
    }
    add_settings_error(
        'myUniqueIdentifyer',
        esc_attr( 'settings_updated' ),
        $message,
        $type
    );
    return $data;
}

注意事项

  • 在 $sanitize_callback 函数中调用 add_settings_error() 后，必须返回 $data，否则字段值不会显示。
📄 原文内容

Registers a settings error to be displayed to the user.

Description

Part of the Settings API. Use this to show messages to users about settings validation problems, missing settings or anything else.

Settings errors should be added inside the $sanitize_callback function defined in register_setting() for a given setting to give feedback about the submission.

By default messages will show immediately after the submission that generated the error.
Additional calls to settings_errors() can be used to show errors even when the settings page is first accessed.

Parameters

$settingstringrequired
Slug title of the setting to which this error applies.
$codestringrequired
Slug-name to identify the error. Used as part of 'id' attribute in HTML output.
$messagestringrequired
The formatted message text to display to the user (will be shown inside styled <div> and <p> tags).
$typestringoptional
Message type, controls HTML class. Possible values include 'error', 'success', 'warning', 'info'. Default 'error'.

Source

function add_settings_error( $setting, $code, $message, $type = 'error' ) {
	global $wp_settings_errors;

	$wp_settings_errors[] = array(
		'setting' => $setting,
		'code'    => $code,
		'message' => $message,
		'type'    => $type,
	);
}

View all references View on Trac View on GitHub

Used by Description
WP_Privacy_Requests_Table::process_bulk_action()wp-admin/includes/class-wp-privacy-requests-table.php

Process bulk actions.
_wp_personal_data_handle_actions()wp-admin/includes/privacy-tools.php

Handle list table actions.
sanitize_option()wp-includes/formatting.php

Sanitizes various option values based on the nature of the option.

Changelog

Version Description
5.3.0 Added warning and info as possible values for $type.
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Basic Example

    function change( $data ) {

    $message = null;
    $type = null;

    if ( null != $data ) {

        if ( false === get_option( 'myOption' ) ) {

            add_option( 'myOption', $data );
            $type = 'updated';
            $message = __( 'Successfully saved', 'my-text-domain' );

        } else {

            update_option( 'myOption', $data );
            $type = 'updated';
            $message = __( 'Successfully updated', 'my-text-domain' );

        }

    } else {

        $type = 'error';
        $message = __( 'Data can not be empty', 'my-text-domain' );

    }

    add_settings_error(
        'myUniqueIdentifyer',
        esc_attr( 'settings_updated' ),
        $message,
        $type
    );

}

You must log in before being able to contribute a note or feedback.