咳咳，各位，话筒试音，喂喂？ 晚上好，欢迎来到今天的 WordPress 短代码“属性大改造”特别讲座！ 今天咱们不搞虚的，直接撸起袖子，把 WordPress 的 shortcode_atts 过滤器扒个精光，看看它到底是怎么工作的，以及咱们怎么利用它，把短代码的默认属性玩出花来。
一、短代码：WordPress 的“乐高积木”
首先，咱们得简单回顾一下短代码是个啥。 简单来说，短代码就像 WordPress 的“乐高积木”，允许你在文章、页面或者小工具里插入各种复杂的功能，而不用懂一大堆 PHP 代码。
举个栗子，假设你想在文章里放一个漂亮的按钮，你可以定义一个短代码 [my_button text="点击我！" url="https://example.com"]，然后 WordPress 会把它替换成实际的 HTML 按钮。
二、shortcode_atts：短代码属性的“变形金刚”
问题来了，如果用户没指定 text 或者 url 呢？ 这时候，咱们就需要设置默认值。 WordPress 提供了 shortcode_atts 过滤器，它就像一个“变形金刚”，允许咱们在短代码属性被提取出来之后、传给短代码处理函数之前，对属性进行修改和补充。
三、shortcode_atts 过滤器的“解剖”
咱们先看看 shortcode_atts 过滤器的原型：
apply_filters( 'shortcode_atts_{$shortcode}', $out, $pairs, $atts, $shortcode );参数解释：
| 参数 | 类型 | 描述 |
|---|---|---|
$out |
array | 包含合并后的属性数组。 这是咱们要修改的对象。 |
$pairs |
array | 包含默认属性和值的数组。 这个数组定义了短代码应该有哪些属性，以及它们的默认值。 |
$atts |
array | 用户在短代码里指定的属性数组。 例如，[my_button text="自定义文本"]，那么 $atts 就是 array('text' => '自定义文本')。 |
$shortcode |
string | 短代码的名称。 例如，my_button。 |
四、实战演练：改造 my_button 短代码
假设咱们要创建一个 my_button 短代码，默认文本是 "点击这里"，默认 URL 是 "#"。 如果用户指定了 text 或 url，就用用户指定的；否则，就用默认值。
- 定义短代码处理函数：
function my_button_shortcode( $atts ) {
$atts = shortcode_atts(
array(
'text' => '点击这里',
'url' => '#',
),
$atts,
'my_button'
);
$text = esc_attr( $atts['text'] );
$url = esc_url( $atts['url'] );
$output = '<a href="' . $url . '" class="my-button">' . $text . '</a>';
return $output;
}
add_shortcode( 'my_button', 'my_button_shortcode' );注意这里 shortcode_atts() 函数的使用，它会将默认值与用户传入的属性进行合并，保证 $atts 中包含所有需要的属性，并且用户传入的值会覆盖默认值。
- 使用
shortcode_atts过滤器（重点来了！）：
function modify_my_button_atts( $out, $pairs, $atts, $shortcode ) {
if ( 'my_button' === $shortcode ) {
// 检查 'color' 属性是否存在
if ( ! isset( $atts['color'] ) ) {
$out['color'] = 'blue'; // 如果用户没有指定颜色，默认设置为蓝色
}
}
return $out;
}
add_filter( 'shortcode_atts_my_button', 'modify_my_button_atts', 10, 4 );这段代码做了什么？
add_filter( 'shortcode_atts_my_button', ... ): 这行代码告诉 WordPress，咱们要对my_button短代码的属性进行过滤。 注意shortcode_atts_my_button这个钩子，它是shortcode_atts_{$shortcode}的具体化，{$shortcode}被替换成了my_button。if ( 'my_button' === $shortcode ): 这个判断确保咱们只修改my_button短代码的属性，不会影响其他短代码。 这是个好习惯，避免不必要的副作用。if ( ! isset( $atts['color'] ) ): 这里咱们检查用户是否在短代码里指定了color属性。$out['color'] = 'blue';: 如果用户没指定color，咱们就把它设置为 ‘blue’。 注意，咱们修改的是$out数组，因为$out最终会被传递给短代码处理函数。
- 测试：
[my_button text="点我" url="https://google.com"]-> 按钮文本是 "点我"，URL 是 "https://google.com”，颜色（如果按钮支持颜色）是蓝色（因为咱们在modify_my_button_atts函数里设置了默认值）。[my_button]-> 按钮文本是 "点击这里"，URL 是 "#"，颜色（如果按钮支持颜色）是蓝色。[my_button color="red"]-> 按钮文本是 "点击这里"，URL 是 "#"，颜色（如果按钮支持颜色）是红色。 （因为用户指定了颜色，所以覆盖了默认值）。
五、高级技巧：更灵活的属性控制
-
基于其他属性修改属性：
function modify_my_button_atts( $out, $pairs, $atts, $shortcode ) { if ( 'my_button' === $shortcode ) { if ( isset( $atts['type'] ) && 'primary' === $atts['type'] ) { $out['color'] = 'green'; // 如果 type 是 primary，设置颜色为绿色 } else { $out['color'] = 'gray'; // 否则，设置颜色为灰色 } } return $out; } add_filter( 'shortcode_atts_my_button', 'modify_my_button_atts', 10, 4 );现在，
[my_button type="primary"]会生成一个绿色的按钮，而[my_button]或者[my_button type="secondary"]会生成一个灰色的按钮。 -
验证属性值：
function modify_my_button_atts( $out, $pairs, $atts, $shortcode ) { if ( 'my_button' === $shortcode ) { if ( isset( $atts['size'] ) ) { $allowed_sizes = array( 'small', 'medium', 'large' ); if ( ! in_array( $atts['size'], $allowed_sizes, true ) ) { $out['size'] = 'medium'; // 如果 size 不是允许的值，设置为默认值 medium } } } return $out; } add_filter( 'shortcode_atts_my_button', 'modify_my_button_atts', 10, 4 );这段代码确保
size属性只能是small、medium或large，否则就设置为medium，防止用户输入非法值。
六、注意事项：代码的“卫生”
- 记得转义： 在短代码处理函数里，一定要对属性值进行转义，防止 XSS 攻击。
esc_attr()用于转义 HTML 属性，esc_url()用于转义 URL。 - 不要过度使用：
shortcode_atts过滤器很强大，但也容易滥用。 如果逻辑太复杂，考虑把逻辑放到短代码处理函数里，或者创建单独的函数。 - 优先级：
add_filter()的第三个参数是优先级（默认为 10）。 如果多个过滤器修改同一个短代码的属性，优先级决定了它们的执行顺序。 优先级数字越小，执行的越早。
七、总结
shortcode_atts 过滤器是 WordPress 短代码的瑞士军刀，允许咱们灵活地控制短代码的属性，设置默认值，验证用户输入，以及基于其他属性进行修改。 掌握它，你就能创建更强大、更灵活的短代码，让你的 WordPress 网站更加个性化。
记住，代码的艺术在于简洁和可维护性。 不要为了炫技而写出难以理解的代码。 保持代码的“卫生”，让你的代码像一件艺术品一样优雅。
好了，今天的讲座就到这里。 希望大家能从中学到一些东西，并在自己的 WordPress 项目中应用起来。 如果有什么问题，欢迎提问！ 咱们下次再见！