简单Wordpress小工具开发

同步发布在个人笔记简单Wordpress小工具开发

小工具简介

Wordpress 中的小工具（Widget）是一个很好用的工具，一般可以显示在侧边栏、顶栏、底栏等区域。虽然官方的小工具已经很丰富了，但是有时我们还是希望能够实现一个更符合自己需求的小工具。
笔记就以最简单的功能——把设置的文本显示在页面上，为例，介绍一个简单但完整的编写 wordpress 小工具的过程。

搭建小工具框架并注册

首先我们需要决定我们希望以何种形式引入我们的小工具。这里记录三种：

• function.php
  如果代码量很小，且不会怎么更新，就可以把代码布置在 wordpress 的 function.php 文件中，注意事项可以阅读一些修改 funct.php 的文章；
• 布置在官方小工具区
  wordpress 官方的小工具有一个专门的文件夹，位置在 wordpress/wp-includes/widgets/。可以把代码文件也放在此处。
• 插件形式引入
  如果想方便的激活/禁用自己的小工具，推荐以插件的形式引入。wordpress 插件也有一个自己的文件夹 wordpress/wp-content/plugins/。在此路径下新建一个文件夹，并把代码放在此文件夹下，就可以在插件页面发现新插件。注意只有激活此插件后才会使得代码有效。

笔记采用的是第三种，以插件形式引入小工具。创建文件夹 wordpress/wp-content/plugins/Quote 并在路径下新建文件 wordpress/wp-content/plugins/Quote/Quote.php。

小工具框架

在文件中加入如下代码，这样小工具的代码框架就搭好了。

<?php
class YourWidget extends WP_Widget {    // YourWidget 是小工具的类名，编写时依照功能自己决定。

    function __construct() {        // 构造函数。在这个函数里可以做出一些定义，比如WordPress小工具的ID、标题和说明。
     
    }

    function form($instance) {  // 创建小工具表单
        
    }

    function update( $new_instance, $old_instance ) {  //  允许表单更新

    }

    function widget( $args, $instance ) {  // 核心功能函数

    }
}
?>

<?php
function register_yourwidget() {  // 注册小工具，使得可以在小工具面板看见
 
    register_widget( '' );   // // register_widget()函数是一个WordPress函数，它唯一的参数就是你刚刚创建的类的命名。
 
}
add_action( 'widgets_init', 'register_yourwidget' );  // 将你创建的函数挂入 widgets_init 钩子，确保它可以被WordPress拾起。
?>

可见整个代码分为5个大模块，前4个属于一个新类，第5部分是注册部分：

• function __construct()
  构造一个函数。在这个函数里做出一些定义，比如WordPress小工具的ID、标题和说明。
• function form($instance)
  在WordPress小工具界面创建表单，让用户来对小工具进行设置与激活。
• function update( $new_instance, $old_instance )
  确保WordPress能及时更新用户在WordPress小工具界面输入的任何设置。
• function widget( $args, $instance )
  定义了在页面上显示的内容（或完成的任务）。即小工具的功能代码区。
• function register_yourwidget()
  只有注册了这个新类，小工具才能正常工作。

注册小工具

上面已经把注册的框架搭好了，此处展示具体例子：

<?php
function register_Quote() {  // 注册小工具，使得可以在小工具面板看见
 
    register_widget( 'Quote' );   // // register_widget()函数是一个WordPress函数，它唯一的参数就是你刚刚创建的类的命名。
 
}
add_action( 'widgets_init', 'register_Quote' );  // 将你创建的函数挂入 widgets_init 钩子，确保它可以被WordPress拾起。
?>

创建小工具“构造函数”

在构造函数区，我们需要定义

• WordPress小工具的唯一ID
• WordPress小工具在其界面上的名称
• 一系列在WordPress小工具界面显示的选项，包括选项说明。

具体的代码可以是这样

    function __construct() {        // 构造函数。在这个函数里可以做出一些定义，比如WordPress小工具的ID、标题和说明。
        parent::__construct(
            
            // 小工具ID  WordPress小工具的唯一ID
            'Quote',
            
            // 小工具名称  WordPress小工具在其界面上的名称
            __('UQuote', 'UQuote' ),
            
            // 小工具选项  一系列在WordPress小工具界面显示的选项，包括选项说明。
            array (
                'description' => __( 'Say somting about this Widget', 'UQuote' )
            )         
        );     
    }

保存文件并且去 wordpress 插件区激活这一插件，你就能在小工具区里找到自己的小工具了，只是现阶段只有一个图标，并不能实现任何功能，后面我们继续完善代码便可一步步实现功能。

创建表单并允许表单更新参数

创建表单

表单就是我们在小工具区，对小工具进行设置的功能。以笔记为例，我们希望能够输入一个语句，让小工具展示在页面上，那么我们就需要在表单函数里面，定义输入语句的方式，和输入内容的存储。
代码如下：

    function form($instance) {  // 创建小工具表单
        
        $quotetext = $instance[ 'quotetext' ];      // 要填写并传递的参数，此例为要展示的语句。

        //定义表单的样式，并且存储用户设置/输入内容
        ?>
        <p>
        <label for="<?php echo $this->get_field_id('quotetext'); ?>">填写文本</label>
        <input id="<?php echo $this->get_field_id('quotetext'); ?>" name="<?php echo $this->get_field_name('quotetext'); ?>" type="text" value="<?php echo esc_attr($quotetext); ?>" />
        </p>

        <?php
    }

显然代码以文本框输入的形式实现用户输入，并把输入内容存储在参数 $instance[ 'quotetext' ] 中。

使得表单更新

允许用户在表单设置小程序后，还需要时刻把用户的表单内容更新到小工具中去，更新代码如下：

    function update( $new_instance, $old_instance ) {  //  允许表单更新
        // 保存小工具选项
        $instance = $old_instance;
        $instance[ 'quotetext' ] = strip_tags( $new_instance[ 'quotetext' ] );  // 上述代码用新值（$new_instance)代替了depth字段的旧值（$old_instance），并采用strip_tags进行消毒。
        return $instance;
    }

现在再去 wordpress 小工具区，就可以发现我们的小工具已经可以进行设置了（可以输入自定义文本了）。

编写小工具功能实现代码

此处是小工具的关键，即核心功能代码区。在这里我们主要实现表单设置内容的传入与获取、以及功能代码编写。
以 Quote 为例，我们需要实现自定义文本的传入，以及在页面上的显示，这两部分。
代码如下：

    function widget( $args, $instance ) {  // 核心功能函数
        // 小工具输出
        // kick things off
        extract( $args );
        //echo $before_widget;        
        //echo $before_title . 'Set title here:' . $after_title;

        $textdispaly = $instance[ 'quotetext' ];        // 获取输入的参数

        // 在侧边栏显示获得的参数，此例为语句。
        ?>
        <pre class="wp-block-verse has-medium-font-size"><font size="3"><?php echo $textdispaly; ?></font></pre>
        <?php

    }

我们去小工具区，输入文本，保存小工具更改，最后回到主页面。终于我们的文本以小工具的形式成功显示在主页上啦！

全部代码

<?php 
/*Plugin Name: Quote
Description: This function works as wordpress widget. It shows a quote set by the user.
Version: 1.0
Author: XXXXXXXXXXX
Author URI: XXXXXXXXXXXXX
License: GPLv2
*/
?>

<?php
class Quote extends WP_Widget {    // Quote 是小工具的类名

    function __construct() {        // 构造函数。在这个函数里可以做出一些定义，比如WordPress小工具的ID、标题和说明。
        parent::__construct(
            
            // 小工具ID  WordPress小工具的唯一ID
            'Quote',
            
            // 小工具名称  WordPress小工具在其界面上的名称
            __('UQuote', 'UQuote' ),
            
            // 小工具选项  一系列在WordPress小工具界面显示的选项，包括选项说明。
            array (
                'description' => __( 'Say somting about this Widget', 'UQuote' )
            )         
        );     
    }


    function form($instance) {  // 创建小工具表单
        
        $quotetext = $instance[ 'quotetext' ];      // 要填写并传递的参数，此例为要展示的语句。

        //后台选项
        ?>
        <p>
        <label for="<?php echo $this->get_field_id('quotetext'); ?>">填写文本</label>
        <input id="<?php echo $this->get_field_id('quotetext'); ?>" name="<?php echo $this->get_field_name('quotetext'); ?>" type="text" value="<?php echo esc_attr($quotetext); ?>" />
        </p>

        <?php
    }


    function update( $new_instance, $old_instance ) {  //  允许表单更新
        // 保存小工具选项
        $instance = $old_instance;
        $instance[ 'quotetext' ] = strip_tags( $new_instance[ 'quotetext' ] );  // 上述代码用新值（$new_instance)代替了depth字段的旧值（$old_instance），并采用strip_tags进行消毒。
        return $instance;
    }


    function widget( $args, $instance ) {  // 核心功能函数
        // 小工具输出
        // kick things off
        extract( $args );
        //echo $before_widget;        
        //echo $before_title . 'Set title here:' . $after_title;

        $textdispaly = $instance[ 'quotetext' ];        // 获取输入的参数

        // 在侧边栏显示获得的参数，此例为语句。
        ?>
        <pre class="wp-block-verse has-medium-font-size"><font size="3"><?php echo $textdispaly; ?></font></pre>
        <?php

    }



}
?>

<?php
function register_Quote() {  // 注册小工具，使得可以在小工具面板看见
 
    register_widget( 'Quote' );   // // register_widget()函数是一个WordPress函数，它唯一的参数就是你刚刚创建的类的命名。
 
}
add_action( 'widgets_init', 'register_Quote' );  // 将你创建的函数挂入 widgets_init 钩子，确保它可以被WordPress拾起。
?>

常用小工具 API

首先，四个常用小工具函数:

• is_active_widget():一个条件标签，用来检查一个单独的小工具是否是活跃的。不要将它与用来检查小工具是否已经添加到一个特定的小工具区的函数 is_active_sidebar() 混淆。
• the_widget():一个模板标签，用来在小工具区域外显示小工具。
• register_widget():用来注册一个小工具的函数，我将在后面的文章中用到。
• unregister_widget():注销一个小工具，这意味着用户将无法在小工具界面使用它。

还有五个内部函数:

• wp_register_widget_control():在小工具界面上创建控制选项，以便用户可以修改小工具的设置。
• wp_unregister_widget_control():取消注册通过wp_register_widget_control()注册的小工具控制选项。
• wp_convert_widget_settings():转换小工具的设置从单一实例到成多实例。
• wp_get_widget_defaults():核心函数，不能被插件或者主题开发者使用。
• wp_widget_description():创建一个可以在小工具屏幕上显示的小工具描述。

要访问这些内部函数，你将使用WP_Widget这类。这是一个构造函数类，它可以扩展来创建额外的小工具。
链接：https://www.wpdaxue.com/creat-your-first-wordpress-widget.html.