快速标签

描述

Quicktags API 允许你在 WordPress 经典编辑器的文本（HTML）模式中包含额外的按钮。

历史

该 API 在 WordPress 3.3 中引入。

用法

QTags.addButton( id, display, arg1, arg2, access_key, title, priority, instance, object );

参数

• id (string) (required): 按钮的 HTML ID。默认值：无
• display (string) (required): 按钮的 HTML 值。默认值：无
• arg1 (string) (required): 要插入的开始标签，例如"<span>"，或者是点击按钮时执行的回调函数。默认值：无
• arg2 (string) (optional): 结束标签，例如"</span>"。如果标签不需要闭合（即"<hr />"），请留空。默认值：无
• access_key (string) (optional): 已弃用且不再使用。 按钮的快捷访问键。默认值：无
• title (string) (optional): 按钮的 HTML title 值。默认值：无
• priority (int) (optional): 表示按钮在工具栏中期望位置的数字。1 – 9 = 第一组，11 – 19 = 第二组，21 – 29 = 第三组，以此类推。默认值：无
• instance (string) (optional): 将按钮限制为特定的 Quicktags 实例，如果不存在则添加到所有实例。默认值：无
• object (attr) (optional): 用于传递额外属性。目前支持 ariaLabel 和 ariaLabelClose（用于“关闭标签”状态）

返回值

(mixed) Null 或用于向后兼容所需的按钮对象。

示例

以下示例将在文本编辑器的默认 Quicktags 中添加 HTML 按钮。

现代示例

此示例使用内联 JS API 在入队 quicktags 时添加 JavaScript。

/**
 * Add a paragraph tag button to the quicktags toolbar
 *
 * @return void
 */
function wporg_add_quicktag_paragraph() {
	wp_add_inline_script(
		'quicktags',
		"QTags.addButton( 'eg_paragraph_v2', 'p_v2', '<p>', '</p>', '', 'Paragraph tag v2', 2, '', { ariaLabel: 'Paragraph', ariaLabelClose: 'Close Paragraph tag' });"
	);
}
add_action( 'admin_enqueue_scripts', 'wporg_add_quicktag_paragraph' );

另一个现代示例

在此示例中，

1. 使用正确的 WordPress 函数 wp_enqueue_script 入队脚本。
2. 在 QuickTag 回调内部调用任何希望在点击 QuickTag 时或之后触发的 JavaScript。

入队脚本

将以下代码放入活动主题的 functions.php 中。

function enqueue_quicktag_script(){
	wp_enqueue_script( 'your-handle', get_template_directory_uri() . '/editor-script.js', array( 'jquery', 'quicktags' ), '1.0.0', true );
}
add_action( 'admin_enqueue_scripts', 'enqueue_quicktag_script' );

JavaScript 本身

创建新文件 editor-script 并保存在活动主题目录下。

QTags.addButton( 'eg_paragraph_v3', 'p_v3', my_callback, '', '', 'Prompted Paragraph tag', 3, '', { ariaLabel: 'Prompted Paragraph' } ); 

function my_callback(){
  var my_stuff = prompt( 'Enter Some Stuff:', '' );
  if ( my_stuff ) {
    QTags.insertContent( '<p>' + my_stuff + '</p>' );
  }
}

传统示例

此示例在 admin footer hook 上使用 wp_script_is 手动添加硬编码的 JavaScript。你应该考虑使用现代示例。见上文。

/**
 * Add more buttons to the quicktags HTML editor
 *
 * @return void
 */
function wporg_traditional_add_quicktags() {
	if ( ! wp_script_is( 'quicktags' ) ) {
		return;
	}

	?>
	<script type="text/javascript">
		QTags.addButton( 'eg_paragraph', 'p', '<p>', '</p>', '', 'Paragraph tag', 1, '', { ariaLabel: 'Paragraph', ariaLabelClose: 'Close Paragraph tag' } );
		QTags.addButton( 'eg_hr', 'hr', '<hr />', '', '', 'Horizontal rule line', 201, '', { ariaLabel: 'Horizontal' } );
		QTags.addButton( 'eg_pre', 'pre', '<pre lang="php">', '</pre>', '', 'Preformatted text tag', 111, '', { ariaLabel: 'Pre', ariaLabelClose: 'Close Pre tag' } );
	</script>
	<?php
}

add_action( 'admin_print_footer_scripts', 'wporg_traditional_add_quicktags', 11 );

注意：

• 为了避免 Reference Error，我们检查是否正在使用 'quicktags' 脚本。
• 自 WordPress 6.0 起，脚本加载顺序已更改，如果不提供 add_action() 的第 3 个参数，会出现"QTags is not defined"错误。此外，你必须指定大于 10 的数字（例如 11）。

"p"按钮的 HTML 如下所示：

<input type="button" id="qt_content_eg_paragraph" class="ed_button button button-small" title="Paragraph tag" aria-label="Paragraph" value="p">

每个按钮的 ID 值会自动前缀字符串 qt_content_。

以下是来自 quicktags.js 的 docblock 转储，它本身就很有用。

/**
 * Main API function for adding a button to Quicktags
 *
 * Adds qt.Button or qt.TagButton depending on the args. The first three args are always required.
 * To be able to add button(s) to Quicktags, your script should be enqueued as dependent
 * on "quicktags" and outputted in the footer. If you are echoing JS directly from PHP,
 * use add_action( 'admin_print_footer_scripts', 'output_my_js', 100 ) or add_action( 'wp_footer', 'output_my_js', 100 )
 *
 * Minimum required to add a button that calls an external function:
 *     QTags.addButton( 'my_id', 'my button', my_callback );
 *     function my_callback() { alert('yeah!'); }
 *
 * Minimum required to add a button that inserts a tag:
 *     QTags.addButton( 'my_id', 'my button', '<span>', '</span>' );
 *     QTags.addButton( 'my_id2', 'my button', '<br />' );
 */

默认 Quicktags

以下是 WordPress 添加到文本编辑器的默认 Quicktags 的值。ID 必须是唯一的。添加自己的按钮时，请勿使用这些值：

上述一些标签值使用了变量，如 URL 和 _datetime，由函数传递。

源文件

qt.addButton() 的源代码位于 js/_enqueues/lib/quicktags.js，构建过程中输出到 wp-incudes/js/quicktags.js 和 wp-includes/js/quicktags.min.js。