submit_button()
云策文档标注
概述
submit_button() 是一个 WordPress 函数，用于在管理后台输出提交按钮，支持自定义文本、CSS 类和 HTML 属性。它直接输出 HTML 到浏览器，不返回值，适用于后台界面开发。
关键要点
- 函数直接输出提交按钮的 HTML，不返回字符串，适用于管理屏幕。
- 参数包括 $text（按钮文本，默认 'Save Changes'）、$type（按钮类型和 CSS 类，默认 'primary'）、$name（HTML name 属性，默认 'submit'）、$wrap（是否包裹在段落标签中，默认 true）和 $other_attributes（其他 HTML 属性）。
- $type 参数支持单个值、空格分隔列表或数组，用于生成 CSS 类，如 'primary' 对应 'button-primary'，'delete' 对应 'button-secondary delete'。
- 函数基于 get_submit_button() 实现，后者返回字符串而非直接输出，且默认 $type 为 'primary large'。
- 仅限后台使用，不能在前端调用。
代码示例
// 默认用法，输出 'Save Changes' 按钮
submit_button();
// 输出次要按钮
submit_button( __( 'Reset', 'textdomain' ), 'secondary' );
// 输出删除按钮
submit_button( __( 'Delete', 'textdomain' ), 'delete' );
// 自定义 name 和 id 属性
$other_attributes = array( 'id' => 'wpdocs-button-id' );
submit_button( __( 'Save Settings', 'textdomain' ), 'primary', 'wpdocs-save-settings', true, $other_attributes );
// 禁用段落包裹
submit_button( __( 'Submit', 'textdomain' ), 'primary', 'submit-form', false );
// 添加其他 HTML 属性
$other_attributes = array( 'tabindex' => '1' );
submit_button( __( 'Go!', 'textdomain' ), 'secondary', '', true, $other_attributes );注意事项
- 此函数仅适用于 WordPress 管理后台，调用前需确保在后台环境中。
- 使用 $type 参数时，注意 CSS 类的生成规则，例如 'secondary' 会被忽略，因为 'button' 类已包含样式。
- 如果未通过 $other_attributes 提供 id 属性，$name 参数将用作按钮的 id。
- 对于需要字符串返回的场景，应使用 get_submit_button() 函数。
原文内容
Echoes a submit button, with provided text and appropriate class(es).
Description
See also
Parameters
$textstringoptional-
The text of the button. Defaults to ‘Save Changes’.
$typestringoptional-
The type and CSS class(es) of the button. Core values include
'primary','small', and'large'. Default'primary'. $namestringoptional-
The HTML name of the submit button. If no
idattribute is given in the$other_attributesparameter,$namewill be used as the button’sid. Default'submit'. $wrapbooloptional-
True if the output button should be wrapped in a paragraph tag, false otherwise.
Default:
true $other_attributesarray|stringoptional-
Other attributes that should be output with the button, mapping attributes to their values, e.g.
array( 'id' => 'search-submit' ).
These key/value attribute pairs will be output asattribute="value", where attribute is the key. Attributes can also be provided as a string, e.g.id="search-submit", though the array format is generally preferred.
Default empty string.
Source
function submit_button( $text = '', $type = 'primary', $name = 'submit', $wrap = true, $other_attributes = '' ) {
echo get_submit_button( $text, $type, $name, $wrap, $other_attributes );
}
Changelog
| Version | Description |
|---|---|
| 3.1.0 | Introduced. |
Skip to note 9 content
Codex
Default Usage
This will output the following HTML, which will display a button with the text “Save Changes”.
<input type="submit" name="submit" id="submit" class="button button-primary" value="Save Changes" />Skip to note 10 content
Codex
Display a Secondary Button
WordPress styles secondary and primary buttons differently. Primary buttons are blue, and stand out more than secondary buttons, which are grey. By default,
submit_button()outputs a primary button. To display a secondary button instead, set the$typeparameter to'secondary':submit_button( __( 'Reset', 'textdomain' ), 'secondary' );Skip to note 11 content
Codex
Display a Delete Button
By default, WordPress doesn’t currently appear to have custom styling for delete buttons, but it does give them the
'delete'HTML class. However, it’s possible that could change in the future, so it’s a good idea to specify the$typeas'delete'when displaying a delete button:submit_button( __( 'Delete', 'textdomain' ), 'delete' );By default, delete buttons will be displayed as secondary buttons, not primary. If you want to display it as a primary button, you can do it like this:
submit_button( __( 'Delete', 'textdomain' ), 'delete button-primary' );Skip to note 12 content
Codex
Using the $name Parameter
The
$nameparameter may be used if you want to set the HTML name attribute for the button. By default, this will be'submit'.submit_button( __( 'Save Settings', 'textdomain' ), 'primary', 'wpdocs-save-settings' );By default, the
$nameis also used to fill out the button’sidattribute. To change this, you can pass anidvia the$other_attributesparameter:$other_attributes = array( 'id' => 'wpdocs-button-id' ); submit_button( __( 'Save Settings', 'textdomain' ), 'primary', 'wpdocs-save-settings', true, $other_attributes );Skip to note 13 content
Codex
Using the $wrap Parameter
The
$wrapparameter controls whether the button is wrapped in a paragraph tag, which it is by default. This can be a help or a hindrance depending on where an how you wish to display the button. To turn this behavior off, passfalsefor the fourth parameter:submit_button( __( 'Submit', 'textdomain' ), 'primary', 'submit-form', false );Skip to note 14 content
Codex
Specifying Other HTML Attributes
You can add any HTML attributes you chose to your button using the
$other_attributesparameter. For example:$other_attributes = array( 'tabindex' => '1' ); submit_button( __( 'Go!', 'textdomain' ), 'secondary', '', true, $other_attributes );Skip to note 15 content
Codex
Using Custom Text
To output a button with custom text, use the first parameter like this:
submit_button( 'Submit' );Skip to note 16 content
Cedric Moris Kelly
This example shows a plugin options page form with two submit buttons, each serving different purposes.
<form method="post"> 'wpdocs-field-id' ); /* Custom submit button */ submit_button( esc_html__( 'My action', 'text_domain' ), // Text of the button, localized 'primary', // CSS class for the button 'wpdocs-input-name', // 'name' attribute for the button to identify it in POST data true, // Wrap the button in a <p> tag $attributes // Additional attributes like 'id' ); ?> </form>