云策 WordPress 开发者社区

函数文档

get_submit_button()

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

概述

get_submit_button() 函数用于生成并返回一个提交按钮的 HTML 字符串，允许自定义按钮文本、类型、名称等属性。它是 WordPress 核心函数，主要用于后台管理界面。

关键要点

  • 函数返回提交按钮的 HTML 字符串，而非直接输出。
  • 支持参数包括 $text（按钮文本，默认 'Save Changes'）、$type（按钮类型和 CSS 类，默认 'primary large'）、$name（按钮名称，默认 'submit'）、$wrap（是否包裹在段落标签中，默认 true）和 $other_attributes（其他 HTML 属性）。
  • $type 参数可以是单个值、空格分隔的列表或数组，用于生成 CSS 类，如 'primary' 对应 'button-primary'。
  • 默认情况下，按钮的 id 属性基于 $name 参数，除非在 $other_attributes 中指定。
  • 相关函数 submit_button() 直接输出按钮，而非返回字符串，且默认 $type 为 'primary'。
  • 此函数主要在 wp-admin 环境中使用，外部调用可能导致错误。

代码示例

// 基本用法：生成一个默认的提交按钮
$button_html = get_submit_button();

// 自定义文本和类型
$button_html = get_submit_button('更新设置', 'small', 'update-btn');

// 添加其他属性
$button_html = get_submit_button('删除', 'delete', 'delete-btn', false, array('id' => 'custom-id', 'data-action' => 'remove'));

注意事项

  • 函数依赖于 WordPress 环境，特别是后台相关函数，不建议在前端或非 WordPress 环境中直接调用。
  • 使用 $other_attributes 时，推荐使用数组格式以更好地控制属性输出。
  • 注意 $type 参数中 'secondary' 或 'button-secondary' 会被忽略，因为 'button' 类已包含相应样式。
📄 原文内容

Returns a submit button, with provided text and appropriate class.

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 large’.
$namestringoptional
The HTML name of the submit button. If no id attribute is given in the $other_attributes parameter, $name will be used as the button’s id. 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 as attribute="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.

Return

string Submit button HTML.

More Information

  • $type can be a single value, or a space separated list of values, or an array of values. The values determine the HTML classes of the button.
    • If $type is ‘delete’, the classes are ‘button delete’.
    • Otherwise the first class is ‘button’, followed by any of these in order of appearance:
      • type value ‘primary’ makes class ‘button-primary’
      • type value ‘small’ makes class ‘button-small’
      • type value ‘large’ makes class ‘button-large’
      • type value ‘secondary’ or ‘button-secondary’ is ignored (the ‘button’ class has the styling)
      • any other type value ‘foo’ makes the class ‘foo’
    • For example, the default $type ‘primary large’ results in a button with HTML classes ‘button button-primary button-large’.
  • The related function submit_button() echos the button instead of returning it as a string. It has a different default $type, ‘primary’, resulting in the HTML classes ‘button button-primary’.

Source

function get_submit_button( $text = '', $type = 'primary large', $name = 'submit', $wrap = true, $other_attributes = '' ) {
	if ( ! is_array( $type ) ) {
		$type = explode( ' ', $type );
	}

	$button_shorthand = array( 'primary', 'small', 'large' );
	$classes          = array( 'button' );

	foreach ( $type as $t ) {
		if ( 'secondary' === $t || 'button-secondary' === $t ) {
			continue;
		}

		$classes[] = in_array( $t, $button_shorthand, true ) ? 'button-' . $t : $t;
	}

	// Remove empty items, remove duplicate items, and finally build a string.
	$class = implode( ' ', array_unique( array_filter( $classes ) ) );

	$text = $text ? $text : __( 'Save Changes' );

	// Default the id attribute to $name unless an id was specifically provided in $other_attributes.
	$id = $name;
	if ( is_array( $other_attributes ) && isset( $other_attributes['id'] ) ) {
		$id = $other_attributes['id'];
		unset( $other_attributes['id'] );
	}

	$attributes = '';
	if ( is_array( $other_attributes ) ) {
		foreach ( $other_attributes as $attribute => $value ) {
			$attributes .= $attribute . '="' . esc_attr( $value ) . '" '; // Trailing space is important.
		}
	} elseif ( ! empty( $other_attributes ) ) { // Attributes provided as a string.
		$attributes = $other_attributes;
	}

	// Don't output empty name and id attributes.
	$name_attr = $name ? ' name="' . esc_attr( $name ) . '"' : '';
	$id_attr   = $id ? ' id="' . esc_attr( $id ) . '"' : '';

	$button  = '<input type="submit"' . $name_attr . $id_attr . ' class="' . esc_attr( $class );
	$button .= '" value="' . esc_attr( $text ) . '" ' . $attributes . ' />';

	if ( $wrap ) {
		$button = '<p class="submit">' . $button . '</p>';
	}

	return $button;
}

View all references View on Trac View on GitHub

Uses Description
__()wp-includes/l10n.php

Retrieves the translation of $text.
esc_attr()wp-includes/formatting.php

Escaping for HTML attributes.
Used by Description
submit_button()wp-admin/includes/template.php

Echoes a submit button, with provided text and appropriate class(es).
_list_meta_row()wp-admin/includes/template.php

Outputs a single row of public meta data in the Custom Fields meta box.
wp_media_insert_url_form()wp-admin/includes/media.php

Creates the form for external url.
get_media_item()wp-admin/includes/media.php

Retrieves HTML form for modifying the image attachment.

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes