解析 WordPress `shortcode_atts` 过滤器源码：如何在短代码处理函数中修改默认属性。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众，早上/下午/晚上好！欢迎来到今天的“WordPress Shortcode魔法学院”。今天我们要扒一扒WordPress短代码（Shortcode）的内心世界，特别是那个名为shortcode_atts的神秘过滤器。它就像一个魔法棒，能让你在短代码处理函数中修改默认属性，让你的短代码更加灵活多变。

准备好了吗？让我们开始这场代码探险之旅吧！

Shortcode：WordPress的瑞士军刀

首先，咱们得简单回顾一下什么是Shortcode。你可以把它想象成WordPress的瑞士军刀，用简单的标签（例如[my_shortcode]）就能在文章、页面或者小工具中插入复杂的功能。WordPress会把这些标签替换成你定义的HTML、PHP代码，甚至是其他插件的内容。

shortcode_atts过滤器：属性修改的魔法棒

现在，让我们聚焦到今天的明星——shortcode_atts过滤器。这个过滤器允许你在短代码的属性被传递到处理函数之前，拦截并修改它们。这就像在快递包裹送到你家之前，你可以先打开看看，然后偷偷换掉里面的东西（当然，我们这里是合法操作）。

源码剖析：shortcode_atts的真面目

要理解shortcode_atts，最好的办法就是直接看它的源码。虽然WordPress内核代码比较复杂，但我们可以简化一下，抓住核心部分：

/**
 * Merges user defined attributes into defaults attributes array.
 *
 * This function is used to combine user defined shortcode attributes with
 * known attributes and fill in the defaults when needed.
 *
 * The resulting attributes are passed to the shortcode handler function.
 *
 * @since 2.5.0
 *
 * @param array  $pairs     Entire list of supported attributes and their defaults.
 * @param array  $atts      User defined attributes in shortcode tag.
 * @param string $shortcode Tag name of the shortcode.
 * @return array Merged and filtered attribute list.
 */
function shortcode_atts( $pairs, $atts, $shortcode = '' ) {
    $atts = (array) $atts;
    $out = array();
    $defaults = (array) $pairs;

    if ( isset( $atts['content'] ) ) {
        $out['content'] = trim( $atts['content'] );
    }

    if ( isset( $atts[0] ) && strlen($atts[0]) > 0 && strpos( $atts[0], '=' ) === false ) {
        if ( ! empty( $defaults['content'] ) && is_string( $defaults['content'] ) ) {
            $out['content'] = trim( $atts[0] );
        }
    }

    $atts = array_map( 'trim', $atts );

    foreach ( $defaults as $name => $default ) {
        if ( array_key_exists( $name, $atts ) ) {
            $out[$name] = $atts[$name];
        } else {
            $out[$name] = $default;
        }
    }

    /**
     * Filters the combined and filtered shortcode attributes.
     *
     * @since 2.5.0
     *
     * @param array  $out       The attribute array.
     * @param array  $pairs     The supported attributes and their defaults.
     * @param array  $atts      The user defined shortcode attributes.
     * @param string $shortcode The shortcode name.
     */
    $out = apply_filters( "shortcode_atts_{$shortcode}", $out, $pairs, $atts, $shortcode );

    return $out;
}

简单来说，shortcode_atts函数做了这些事情：

合并属性： 它将你定义的默认属性（$pairs）和用户在短代码中提供的属性（$atts）合并起来。如果用户提供了某个属性，就用用户的值；否则，就用默认值。
应用过滤器： 最关键的一步，它会应用一个过滤器shortcode_atts_{$shortcode}。这个{$shortcode}会被替换成你的短代码名称。这就是我们修改属性的入口。
返回结果： 它返回一个包含所有属性的数组，这个数组最终会被传递到你的短代码处理函数中。

实战演练：修改短代码属性

现在，让我们通过一个具体的例子来演示如何使用shortcode_atts过滤器。

假设我们有一个短代码[greeting name="World" salutation="Hello"]，它的作用是显示一句问候语。我们希望能够通过过滤器来修改默认的问候语。

1. 定义短代码处理函数：

function greeting_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'name'       => 'World',
            'salutation' => 'Hello',
        ),
        $atts,
        'greeting' // 短代码名称
    );

    return '<p>' . esc_html( $atts['salutation'] ) . ', ' . esc_html( $atts['name'] ) . '!</p>';
}
add_shortcode( 'greeting', 'greeting_shortcode' );

2. 添加过滤器：

add_filter( 'shortcode_atts_greeting', 'modify_greeting_attributes', 10, 4 );

function modify_greeting_attributes( $out, $pairs, $atts, $shortcode ) {
    // 检查是否传递了 'special' 属性
    if ( isset( $atts['special'] ) && $atts['special'] == 'true' ) {
        // 修改默认的 salutation
        $out['salutation'] = 'Greetings, esteemed';
    }

    return $out;
}

代码解释：

add_filter( 'shortcode_atts_greeting', 'modify_greeting_attributes', 10, 4 ); 这行代码告诉WordPress，当处理名为greeting的短代码的属性时，要调用modify_greeting_attributes函数。
modify_greeting_attributes函数接收四个参数：
- $out: 最终的属性数组，包含了合并后的属性。
- $pairs: 默认属性数组。
- $atts: 用户提供的属性数组。
- $shortcode: 短代码的名称（这里是greeting）。
在modify_greeting_attributes函数中，我们检查用户是否提供了special属性，并且它的值为true。如果是，我们就修改$out['salutation']的值，将其改为'Greetings, esteemed'。
最后，我们返回修改后的$out数组。

测试结果：

[greeting] 会显示 "Hello, World!"
[greeting name="Alice"] 会显示 "Hello, Alice!"
[greeting special="true"] 会显示 "Greetings, esteemed, World!"
[greeting name="Bob" special="true"] 会显示 "Greetings, esteemed, Bob!"

进阶技巧：更复杂的属性修改

上面的例子只是一个简单的演示。实际上，你可以用shortcode_atts做更多的事情。

1. 属性验证：

你可以检查用户提供的属性值是否符合你的要求。例如，你可以确保某个属性必须是数字：

function modify_greeting_attributes( $out, $pairs, $atts, $shortcode ) {
    if ( isset( $atts['age'] ) && ! is_numeric( $atts['age'] ) ) {
        // 如果 age 不是数字，就设置一个默认值
        $out['age'] = 18;
    }

    return $out;
}

2. 动态默认值：

你可以根据当前的环境（例如当前用户是否登录）来设置默认值：

function modify_greeting_attributes( $out, $pairs, $atts, $shortcode ) {
    if ( is_user_logged_in() ) {
        $current_user = wp_get_current_user();
        $out['name'] = $current_user->display_name; // 使用当前用户的显示名称作为默认值
    }

    return $out;
}

3. 属性转换：

你可以将用户提供的属性值转换成其他格式。例如，你可以将颜色值从十六进制转换为RGB：

function modify_greeting_attributes( $out, $pairs, $atts, $shortcode ) {
    if ( isset( $atts['color'] ) && preg_match( '/^#([0-9a-f]{3}){1,2}$/i', $atts['color'] ) ) {
        // 将十六进制颜色值转换为 RGB
        $hex = str_replace("#", "", $atts['color']);
        if(strlen($hex) == 3) {
            $r = hexdec(substr($hex,0,1).substr($hex,0,1));
            $g = hexdec(substr($hex,1,1).substr($hex,1,1));
            $b = hexdec(substr($hex,2,1).substr($hex,2,1));
        } else {
            $r = hexdec(substr($hex,0,2));
            $g = hexdec(substr($hex,2,2));
            $b = hexdec(substr($hex,4,2));
        }
        $out['color_rgb'] = array( 'r' => $r, 'g' => $g, 'b' => $b );
    }

    return $out;
}

最佳实践：让你的代码更优雅

明确的默认值： 在shortcode_atts中定义清晰的默认值，让你的短代码行为可预测。
参数验证： 验证用户提供的属性值，防止错误和安全问题。
代码注释： 编写清晰的代码注释，方便自己和他人理解你的代码。
避免过度使用： 不要为了修改属性而修改属性。只有在真正需要的时候才使用shortcode_atts过滤器。

案例研究：一个更复杂的例子

假设我们要创建一个短代码，用于显示产品信息。我们希望用户可以指定产品的ID、标题、价格和图片。但是，如果用户没有提供某些属性，我们就从数据库中读取默认值。

function product_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'id'    => 0, // 默认产品ID为0
            'title' => '',
            'price' => '',
            'image' => '',
        ),
        $atts,
        'product'
    );

    // 如果用户提供了产品ID，就从数据库中读取产品信息
    if ( ! empty( $atts['id'] ) ) {
        $product = get_post( $atts['id'] );
        if ( $product ) {
            // 如果用户没有提供标题，就使用产品标题
            if ( empty( $atts['title'] ) ) {
                $atts['title'] = get_the_title( $product );
            }

            // 如果用户没有提供价格，就从自定义字段中读取价格
            if ( empty( $atts['price'] ) ) {
                $price = get_post_meta( $product->ID, 'product_price', true );
                if ( ! empty( $price ) ) {
                    $atts['price'] = $price;
                }
            }

            // 如果用户没有提供图片，就使用特色图片
            if ( empty( $atts['image'] ) ) {
                $image_id = get_post_thumbnail_id( $product );
                if ( ! empty( $image_id ) ) {
                    $atts['image'] = wp_get_attachment_image_src( $image_id, 'medium' )[0];
                }
            }
        }
    }

    // 构建 HTML 输出
    $output = '<div class="product">';
    if ( ! empty( $atts['image'] ) ) {
        $output .= '<img src="' . esc_url( $atts['image'] ) . '" alt="' . esc_attr( $atts['title'] ) . '">';
    }
    $output .= '<h3>' . esc_html( $atts['title'] ) . '</h3>';
    $output .= '<p>Price: ' . esc_html( $atts['price'] ) . '</p>';
    $output .= '</div>';

    return $output;
}
add_shortcode( 'product', 'product_shortcode' );

在这个例子中，我们没有使用shortcode_atts过滤器，而是在短代码处理函数中直接修改属性。虽然这种方法也可以实现同样的效果，但使用shortcode_atts过滤器可以使代码更清晰、更模块化。你可以将从数据库中读取默认值的逻辑放在一个单独的函数中，并通过过滤器来修改属性。

总结：shortcode_atts的威力

shortcode_atts过滤器是WordPress短代码的一个强大工具。它可以让你在短代码处理函数中修改默认属性，实现更灵活、更可定制的短代码。通过合理地使用shortcode_atts过滤器，你可以编写出更优雅、更易于维护的WordPress插件和主题。

希望今天的讲座能够帮助你更好地理解和使用shortcode_atts过滤器。现在，去探索短代码的更多可能性吧！

祝你编程愉快！

发表回复 取消回复

发表回复取消回复