描述
应注意通过前缀或其他方式确保添加的短代码标签是唯一的,并且不会与其他已添加的短码标签冲突。如果标签重复,则以最后加载的标签为准。
参数
- $tag
-
(string)(必填) 要在文章内容中搜索的短码标签。
- $callback
-
(callable)(必填) 找到短码时要运行的回调函数。默认情况下,每个短代码回调都会传递三个参数,包括一个属性数组(
$atts
)、短码内容,如果未设置则为null($content
),最后是短码标签本身($shortcode_tag
)。
更多信息
短代码回调将传递三个参数:短代码属性、短代码内容(如果有)和短代码名称。
每个短代码只能有一个钩子。这意味着,如果另一个插件具有类似的短代码,它将覆盖您的短代码或者被您覆盖,这取决于插件的引入顺序。
在将短代码属性名称传递到处理程序函数之前,它们始终转换为小写。值未被触及。
请注意,由短码调用的函数不应产生任何类型的输出。短代码函数应返回用于替换短码的文本。直接生成输出将导致意外结果。这类似于过滤器函数的行为方式,因为它们不应在调用中产生意外的副作用,因为您无法控制从何时何地调用它们。
源码
更新日志
版本 | 描述 |
---|---|
2.5.0 | 开始引入 |
使用示例
举例
使用API的短代码标签的最简单示例:
[footag foo="bar"]
add_shortcode( 'footag', 'wpdocs_footag_func' ); function wpdocs_footag_func( $atts ) { return "foo = {$atts['foo']}"; }
具有良好属性默认值的示例:
[bartag foo="bar"]
add_shortcode( 'bartag', 'wpdocs_bartag_func' ); function wpdocs_bartag_func( $atts ) { $atts = shortcode_atts( array( 'foo' => 'no foo', 'baz' => 'default baz' ), $atts, 'bartag' ); return "foo = {$atts['foo']}"; }
包含封闭内容的示例:
[baztag]content[/baztag]
add_shortcode( 'baztag', 'wpdocs_baztag_func' ); function wpdocs_baztag_func( $atts, $content = "" ) { return "content = $content"; }
如果插件设计为类,请编写如下代码:
add_shortcode( 'baztag', array( 'MyPlugin', 'wpdocs_baztag_func' ) ); class MyPlugin { public static function wpdocs_baztag_func( $atts, $content = "" ) { return "content = $content"; } }
在插件中添加`add_shortcode()`函数时,最好将其添加到一个连接到`init`钩子的函数中,以便WordPress有时间正确初始化。
add_action( 'init', 'wpdocs_add_custom_shortcode' ); function wpdocs_add_custom_shortcode() { add_shortcode( 'footag', 'wpdocs_footag_func' ); }
如插件手册中所述。
对于wppb插件样板,我将代码添加到define_public_hooks()
$this->loader->add_action( 'init', $plugin_public, 'register_shortcodes' );
然后在公用文件夹class_public文件中,我添加了:
public function register_shortcodes(){ add_shortcode( 'sample-shortcode','shortcode_function' ); function shortcode_function( ) { return "Hello Shortcode"; } }
使用
get_template_part
函数包含模板的add_shortcode
函数示例。function wpdocs_the_shortcode_func( $atts ) { $attributes = shortcode_atts( array( 'title' => false, 'limit' => 4, ), $atts ); ob_start(); // include template with the arguments (The $args parameter was added in v5.5.0) get_template_part( 'template-parts/wpdocs-the-shortcode-template', null, $attributes ); return ob_get_clean(); } add_shortcode( 'wpdocs_the_shortcode', 'wpdocs_the_shortcode_func' );
注意,如果短代码中没有设置属性,则传递给回调的第一个参数是空字符串。因此类型声明将失败:
“致命错误:未捕获错误:传递给shortcode_callback()的参数1必须是数组类型,给定字符串”
使用检查
$arguments
是否是数组,如果不是,则用空数组替换它:function shortcode_callback( $attributes, string $content, string $shortcode ) { if ( ! is_array( $attributes ) ) { $attributes = []; } // do stuff }
$atts: 属性的关联数组,你可以在任何地方访问该关联数组。
$content: 封闭的内容(如果短码以其封闭的形式使用)/** * Appends a <a> tag with URL to the content. * * @param array $atts the shortcode attributes. * @param sring $content the editor enclosed content. * @return string */ function button_callback( $atts, $content ) { // It's a default value. $default = array( 'url' => '', ); // You will pass default value after that user define values. $button_attrs = shortcode_atts( $default, $atts ); return sprintf( '<a href="%s">%s</a>', $button_attrs['url'], do_shortcode( $content ) ); } add_shortcode( 'test-button', 'button_callback' );