WordPress 短代码(Shortcode) API 详解

在上一篇文章——《WordPress 短代码(shortcode) 简略介绍》, Kayo 简略的介绍了 WordPress 的短代码(shortcode) 功能,主要是介绍了 shortcode 的主要概念和使用方法。在本文中, Kayo 将会更加详细的介绍一下 shortcode 中较为重要的 API ,希望有助于各位开发较为复杂的 shortcode 。

一.函数 add_shortcode

该函数用于注册一个 shortcode ,它有两个参数:短代码名与 shortcode 处理函数名,引用上文的例子:

function myshortcode_function($atts, $content = null){ // $atts 代表了 shortcode 的各个参数,$content 为标签内的内容

	extract(shortcode_atts(array( // 使用 extract 函数解析标签内的参数
	"title" => '标题' // 给参数赋默认值,下面直接调用 $ 加上参数名输出参数值
	), $atts));
	// 返回内容
	return '<div class="myshortcode">
				<h3>'. $title .'</h3>
				<p>
					'. $content .'
				</p>
			</div>';
}

add_shortcode("msc", "myshortcode_function"); // 注册该 shortcode,以后使用 [msc] 标签调用该 shortcode

msc 即为短代码名,以后在写文章或页面时可以直接使用 [msc][/msc] 标签调用该短代码,而 "myshortcode_function" 即为例子中的短代码处理函数的名称。下面重点分析短代码处理函数。

二.短代码处理函数

shortcode 处理函数是一个 shortcode 的核心, shortcode 处理函数类似于 Flickr(WordPress 过滤器),它们都接受特定参数,并返回一定的结果。 shortcode 处理器接受两个参数, $attr 和 $content , $attr 代表 shortcode 的各个属性参数,从本质上来说是一个关联数组,而 $content 代表 shortcode 标签中的内容。

如上面的例子,若在文章内作出调用,输出一段欢迎语句:

[msc title="欢迎"]这是独立博客 Kayo's Melody ,欢迎来到本博客[/msc]

当文章显示时, WordPress 会注册所有的 shortcode ,如上面的 [msc] ,若 shortcode 中有属性参数和内容, WordPress 会把它们分离出来并解析,然后传递给该 shortcode 的短代码处理函数,处理后以处理函数输出的结果代替短代码原本的内容显示在文章内。

这时属性参数会并解析会关联数组并传递给 $attr ,如上面的例子中 $attr 的值为如下的一个关联数组:

array( 'title' => '欢迎')

在输出结果时,可以直接使用 $参数名 的形式进行输出,如例子中的情况即以 $title 输出该属性值。

三.shortcode_atts

shortcode_atts 是一个很实用的函数,它可以为你需要的属性参数设置默认值,并且删除一些不需要的参数。

shortcode_atts() 包含两个参数 $defaults_array 与 $atts , $attr 即为属性参数集合, $defaults_array 是代表需要设置的属性默认值,举个例子:

$result = shortcode_atts( array(
	'title' => '新标题',
	'description' => '描述内容'
), $atts );

$attr 依然为

array( 'title' => '欢迎')

这时 $result 的结果为

array( 'title' => '新标题', 'description' => '描述标题')

'title' 由于在 $defaults_array 有不同的值,因此以这个新的值为准更新了 'title' ,同时也增加了 'description' 这个值。值得注意的是, shortcode_atts() 会过滤 $defaults_array 中没有的属性,假如 $attr 中还有一个 'ohter' 的属性,那么 $result 的结果仍然是上面的结果,因为 $defaults_array 中并没有 'other' 这个属性。当然,这里说的值只是属性的默认值,真正输出的值还是 shortcode 调用时填写的值。

四.进一步解析属性与设置属性默认值

extract() 函数用于进一步解析属性并设置属性默认值,其中一个功能是把各属性参数值赋予给一个形如 "$参数名" 的变量保存起来(如例子中的 $title ),方便调用,使用该函数配合 shortcode_atts() 就可以很安全的输出结果。这点的具体使用可以参见本文第一点“一.函数 add_shortcode”的例子。

另外,属性名中的大写字母在传递给处理函数前会先转化为小写字母,因此建议在编写属性名时直接使用小写字母。

本文由 Kayo Lee 发表,本文链接:https://kayosite.com/wordpress-shortcode-api.html

评论列表

  • 评论者头像
    回复

    还是没理解这个究竟有什么作用.
    如果
    [msc title=”欢迎”]这是独立博客 Kayo’s Melody ,欢迎来到本博客[/msc]
    这样写了,会在页面中输出什么呢?

    • 评论者头像
      回复

      @潜行者m 会输出例子中处理函数myshortcode_function返回的那段HTML,代替原本的标签内容显示在文章中,给.myshortcode 添加样式(如背景)的话,就可以做出很酷的欢迎条。
      这只是一个简单的例子,说明了 shortcode 的用途,发挥一下想象,就可以做出功能强大的 shortcode 。

  • 评论者头像
    回复

    短代码 是个好东东。

  • 评论者头像
    回复

    很详细的教学贴,赞!

  • 评论者头像
    回复

    不由自主的点了图片进来看了 :idea:

  • 评论者头像
    回复

    这个主题我喜欢。。可惜我代码不太会。

  • 评论者头像
    回复

    利用这个貌似可以投放Google广告。

  • 评论者头像
    回复

    继续潜入学习~ :wink:

  • 评论者头像
    回复

    这个是不错 呵呵 ~ 不过考虑到兼容性问题,我尽可能的让博客保持原汁原味 哈哈 ~!

    • 评论者头像
      回复

      @in1874 这个主要是为了让需要在文章内使用一些格式的童鞋准备的,我也不赞成使用太多的短代码!

  • 评论者头像
    回复

    我也想把这个短代码功能集成到其他主题,目前正在研究,还有,赞一下你的主题啊,很清爽,大气 :idea:

    • 评论者头像
      回复

      @IT自习室 嗯嗯,谢谢支持!
      这个短代码通用性好,集成一次基本日后开发新主题都可以直接把代码拿来用,所以还是值得集成的!

  • 评论者头像
    回复

    :roll: 不错,拼命看懂中……
    不过内容错别字较多,应该是手误

  • 评论者头像
    回复

    看了之后受益匪浅,有个问题想请教,WP自带了[audio][/audio]短代码,如果传入mp3地址,可以正常解析,但如果mp3后面带参数的话,就解析不了,不知道有没有办法让它支持带参数的地址,如:[audio mp3="http://localhost/123.mp3?key=123"][/audio],我本来想修改media.php,让它不去验证媒体类型,但没成功~所以过来请求帮助~~ :mrgreen:

  • 评论者头像
    回复

    博客很不错啊 学到很多东西

回复

你正在以游客身份访问网站,请输入你的昵称和 E-mail