WordPress插件开发中的简码(Shortcodes)


什么是简码?

简码是一种在WordPress内容中插入动态内容的方式。简码的概念在WordPress 2.5版本中被引入,目的是让用户可以在文章中动态地添加相册、视频、表单等内容。

举例:就像在文档中插入一个占位符,简码可以在不插入PHP代码的情况下,动态地呈现内容。

速记句:简码是WordPress中动态插入内容的占位符。


为什么使用简码?

简码的主要优点是保持文章内容的干净和语义化。它避免了直接在文章中添加HTML标记,并且可以通过调整简码参数来修改内容的显示。

举例:想象一下,你在桌面上放置一个标签,而不是直接摆放物品,这样可以随时根据需要调整物品的排列。

速记句:使用简码,内容更干净,调整更灵活。


如何创建基本简码?

要创建一个基本简码,您可以使用 add_shortcode() 函数。这个函数接受两个参数:简码的名称和回调函数。

示例代码

function wporg_shortcode(atts = [],content = null) {
   return content; } add_shortcode('wporg', 'wporg_shortcode');</code></pre> <!-- /wp:code -->  <!-- wp:paragraph --> <strong>解析</strong>:在上面的示例中,<code>wporg</code> 是创建的简码名称,当用户在文章中使用 <!-- /wp:paragraph -->  <!-- wp:shortcode --> [wporg]</code> 时,WordPress会调用 <code>wporg_shortcode</code> 函数来处理内容。  <strong>速记句</strong>:使用 <code>add_shortcode()</code> 为WordPress创建自定义简码。  <hr />  <h2>自闭合简码与闭合简码</h2> 简码有两种形式:<strong>自闭合简码</strong>和<strong>闭合简码</strong>。自闭合简码类似于HTML中的 <code></code> 标签,不需要结束标记。而闭合简码则类似于 <code><div></div></code> 这样的标签,需要有开始和结束标记。  <strong>示例</strong>: <pre><code class="php language-php">[wporg]content[/wporg] <!-- /wp:shortcode -->  <!-- wp:paragraph --> // 闭合简码 <!-- /wp:paragraph -->  <!-- wp:shortcode --> [wporg]  // 自闭合简码</code>  <strong>解析</strong>:闭合简码允许您操作包裹在简码中的内容,而自闭合简码则不包含任何内容。  <strong>速记句</strong>:自闭合简码像 <code></code>,闭合简码像 <code><div></code>。  <hr />  <h2>带参数的简码</h2> 简码可以接受参数,这些参数就像HTML标签的属性,可以用于定制简码的输出内容。  <strong>示例</strong>: <pre><code class="php language-php">[wporg title="WordPress.org"]Content here.[/wporg] <!-- /wp:shortcode -->  <!-- wp:paragraph --> <strong>解析</strong>:在这个例子中,<code>title</code> 是简码的参数,开发者可以在简码的回调函数中通过 <code>atts 数组获取并使用这些参数。

速记句:简码参数像HTML属性,提供更多控制选项。


处理简码的属性

为了正确处理简码的属性,开发者通常会使用 shortcode_atts() 函数来设置默认值并解析用户传入的属性。

示例代码

atts = shortcode_atts([    'title' => 'WordPress.org', ],atts, tag);</code></pre> <!-- /wp:code -->  <!-- wp:paragraph --> <strong>解析</strong>:该代码确保即使用户未提供 <code>title</code> 参数,简码仍然会使用默认值 <code>WordPress.org</code>。 <!-- /wp:paragraph -->  <!-- wp:paragraph --> <strong>速记句</strong>:用 <code>shortcode_atts()</code> 解析简码属性,确保有默认值。 <!-- /wp:paragraph -->  <!-- wp:separator --> <hr class="wp-block-separator has-alpha-channel-opacity"/> <!-- /wp:separator -->  <!-- wp:heading --> <h2 class="wp-block-heading">嵌套简码</h2> <!-- /wp:heading -->  <!-- wp:paragraph --> 简码解析器默认只处理一次内容。如果简码的内容中包含另一个简码,您需要在回调函数中使用 <code>do_shortcode()</code> 来递归解析。 <!-- /wp:paragraph -->  <!-- wp:paragraph --> <strong>示例代码</strong>: <!-- /wp:paragraph -->  <!-- wp:code --> <pre class="wp-block-code"><code>function wporg_shortcode(atts = [], content = null) {content = do_shortcode(content);    returncontent;
}

解析:这段代码确保在处理内容时,嵌套的简码也会被解析。

速记句:用 do_shortcode() 解析嵌套简码。


删除简码

如果不再需要某个简码,可以使用 remove_shortcode() 来删除它。确保在删除之前已经正确注册过该简码。

示例代码

remove_shortcode('wporg');

解析:这段代码会从WordPress中移除 wporg 简码,确保该简码不再被解析。

速记句:用 remove_shortcode() 删除不需要的简码。


检查简码是否存在

在某些情况下,您可能需要检查简码是否已经注册过,可以使用 shortcode_exists() 来进行检查。

示例代码

if (shortcode_exists('wporg')) {
   // Do something
}

解析:这段代码会检查 wporg 简码是否存在,存在时执行相应操作。

速记句:用 shortcode_exists() 检查简码是否已存在。


简码的最佳实践

简码开发的最佳实践包括始终返回内容、为简码添加前缀以避免冲突、对输入进行消毒以及对输出进行转义。确保为用户提供所有简码属性的明确文档。

速记句:返回内容、加前缀、消毒输入、转义输出,简码更安全。


总结

本文介绍了WordPress简码的基本概念、创建方法、使用场景及一些最佳实践。通过简码,我们可以在文章中轻松插入动态内容,并通过参数灵活定制输出效果。记住,简码的关键在于保持代码简洁、安全,并确保用户使用时的便利性。

参考文献

  1. WordPress插件开发教程手册 — 简码
  2. WordPress插件开发文档
  3. WordPress Codex
  4. WordPress安全编码标准

<?php
function wporg_shortcode(atts = [],content = null, tag = '') {    // normalize attribute keys, lowercaseatts = array_change_key_case((array)atts, CASE_LOWER);     // override default attributes with user attributeswporg_atts = shortcode_atts([
      'title' => 'WordPress.org',
   ], atts,tag);

   // start output
   o = '';     // start boxo .= '<div class="wporg-box">';

   // title
   o .= '<h2>' . esc_html__(wporg_atts['title'], 'wporg') . '</h2>';

   // enclosing tags
   if (!is_null(content)) {       // secure output by executing the_content filter hook oncontent
      o .= apply_filters('the_content',content);

      // run shortcode parser recursively
      o .= do_shortcode(content);
   }

   // end box
   o .= '</div>';     // return output    returno;
}
 
function wporg_shortcodes_init() {
   add_shortcode('wporg', 'wporg_shortcode');
}
 
add_action('init', 'wporg_shortcodes_init');

代码解析

1. 定义简码的回调函数

function wporg_shortcode(atts = [],content = null, tag = '') {    // normalize attribute keys, lowercaseatts = array_change_key_case((array)atts, CASE_LOWER);</code></pre> <!-- /wp:code -->  <!-- wp:paragraph --> <strong>解析</strong>:<code>wporg_shortcode</code> 是简码的回调函数,接收三个参数: <!-- /wp:paragraph -->  <!-- wp:list --> <ul><!-- wp:list-item --> <li><code>atts:简码的属性数组。



  • content</code>:简码包裹的内容(如果有的话)。</li> <!-- /wp:list-item -->  <!-- wp:list-item --> <li><code>tag:简码的名称。
  • 首先,代码使用 array_change_key_case() 将属性数组的键名转换为小写,这是为了确保用户使用大小写不敏感的属性名。


    2. 设置默认属性

       // override default attributes with user attributes
       wporg_atts = shortcode_atts([       'title' => 'WordPress.org',    ],atts, tag);</code></pre> <!-- /wp:code -->  <!-- wp:paragraph --> <strong>解析</strong>:<code>shortcode_atts()</code> 函数用于将用户提供的属性与默认属性合并。在这个例子中,默认 <code>title</code> 属性的值为 ``WordPress.org'',用户可以通过简码修改这个值。 <!-- /wp:paragraph -->  <!-- wp:separator --> <hr class="wp-block-separator has-alpha-channel-opacity"/> <!-- /wp:separator -->  <!-- wp:heading {"level":3} --> <h3 class="wp-block-heading">3. 开始输出 HTML 代码</h3> <!-- /wp:heading -->  <!-- wp:code --> <pre class="wp-block-code"><code>   // start outputo = '';
    
       // start box
       o .= '<div class="wporg-box">';</code></pre> <!-- /wp:code -->  <!-- wp:paragraph --> <strong>解析</strong>:准备输出的内容。首先,代码初始化了一个空字符串 <code>o,然后开始构建 HTML 结构,在这里是一个 div 容器。


    4. 输出标题

       // title
       o .= '<h2>' . esc_html__(wporg_atts['title'], 'wporg') . '</h2>';

    解析:将简码的 title 属性值输出为标题(<h2> 标签)。esc_html__() 函数用于对标题文本进行安全处理,防止XSS攻击。


    5. 处理包裹的内容

       // enclosing tags
       if (!is_null(content)) {       // secure output by executing the_content filter hook oncontent
          o .= apply_filters('the_content',content);
    
          // run shortcode parser recursively
          o .= do_shortcode(content);
       }

    解析:如果简码是闭合简码且包裹了一些内容,则执行以下步骤:

    • 通过 apply_filters('the_content', content)</code> 处理内容,使其符合WordPress的内容过滤规则。</li> <!-- /wp:list-item -->  <!-- wp:list-item --> <li>通过 <code>do_shortcode(content) 递归解析内容中的其他简码。

    6. 结束 HTML 结构

       // end box
       o .= '</div>';</code></pre> <!-- /wp:code -->  <!-- wp:paragraph --> <strong>解析</strong>:结束 <code>div</code> 容器的 HTML 结构。 <!-- /wp:paragraph -->  <!-- wp:separator --> <hr class="wp-block-separator has-alpha-channel-opacity"/> <!-- /wp:separator -->  <!-- wp:heading {"level":3} --> <h3 class="wp-block-heading">7. 返回输出结果</h3> <!-- /wp:heading -->  <!-- wp:code --> <pre class="wp-block-code"><code>   // return output    returno;
    }

    解析:返回完整的 HTML 结构,WordPress会将其插入到文章内容中。


    8. 注册简码

    function wporg_shortcodes_init() {
       add_shortcode('wporg', 'wporg_shortcode');
    }

    解析wporg_shortcodes_init 函数使用 add_shortcode()wporg 简码与 wporg_shortcode 回调函数关联起来。


    9. 将函数挂载到 init 钩子

    add_action('init', 'wporg_shortcodes_init');

    解析:使用 add_action()wporg_shortcodes_init 函数挂载到 init 动作钩子上,确保简码在WordPress初始化完成后注册。


    总结

    这段代码展示了如何创建一个功能强大且安全的WordPress简码。它不仅支持自定义属性,还能够处理封闭简码中嵌套的内容,并且通过确保输出的安全性来防止潜在的安全问题。

    你可以通过在文章中使用 [wporg title="Your Title"]Content goes here[/wporg] 来调用这个简码,生成一个带有自定义标题和内容的盒子。

    评论

    发表回复

    人生梦想 - 关注前沿的计算机技术 acejoy.com