Widgets · WordPress開發手冊

小部件將內容和功能添加到小部件區域（也稱為側邊欄）。小部件區域為用戶定制其網站提供了一種方式。窗口小部件區域可以顯示在多個頁面上或僅在一個頁面上。您的主題可能只有一個小部件區域或其中許多。可以使用小部件區域的一些示例如下： - 使用小部件布置首頁。這允許網站所有者決定在其主頁的每個部分應該出現什么。 - 創建一個頁腳，用戶可以使用自己的內容進行自定義。 - 向博客添加可自定義的側邊欄。 - 小部件是輸出一些HTML的PHP對象。相同類型的小部件可以在同一頁面上多次使用（例如，文本小部件）。小部件可以將數據保存在數據庫中（在選項表中）。當您創建一種新的小部件時，它將顯示在用戶的“管理屏幕”的“外觀”>“小部件”中。用戶可以將窗口小部件添加到窗口小部件區域，并從WordPress管理員自定義窗口小部件設置。 ## 內置和獨立的小部件默認WordPress安裝包含一組小部件。除了這些標準的小部件，主題或插件可以包含額外的小部件。內置在主題或插件中的小部件的優點是提供額外的功能并增加小部件的數量。缺點是，如果主題已更改或插件被停用，插件或主題小部件的功能將會丟失。但是，如果重新激活主題或插件，則小部件的數據和首選項將保存到選項表，并恢復。如果您的主題包含小部件，則只有在該主題處于活動狀態時才能使用。如果用戶決定改變他們的主題，他們將無法訪問該小部件。但是，如果插件包含插件，則用戶可以更改其主題，而不會失去對窗口小部件功能的訪問。 ## 小部件解剖視覺上，一個小部件包括兩個方面： - 標題區 - 小部件選項例如，這里是管理員和前端內置文本小部件的布局： - 示例可編輯小部件 - 管理區域中的小部件表單。一個小部件，因為它可以訪問一個網站訪問者。網站訪問者看到的小部件。此小部件的HTML輸出如下所示： ``` <div id="text-7" class="widget widget_text">  <div class="widget-wrap"> <h4 class="widgettitle">This is a text widget</h4>  <div class="textwidget">  I can put HTML in here. <a href="http://google.com">Search me!</a> </div> </div> </div> ``` 每個小部件都有自己的方式輸出與正在顯示的數據相關的HTML。小部件的包裝器標簽由其正在顯示的小部件區域定義。 PHP需要創建一個內置的文本小部件，如下所示： ``` class My_Widget extends WP_Widget { function __construct() { parent::__construct( 'my-text', // Base ID 'My Text' // Name ); add_action( 'widgets_init', function() { register_widget( 'My_Widget' ); }); } public $args = array( 'before_title' => '<h4 class="widgettitle">', 'after_title' => '</h4>', 'before_widget' => '<div class="widget-wrap">', 'after_widget' => '</div></div>' ); public function widget( $args, $instance ) { echo $args['before_widget']; if ( ! empty( $instance['title'] ) ) { echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title']; } echo '<div class="textwidget">'; echo esc_html__( $instance['text'], 'text_domain' ); echo '</div>'; echo $args['after_widget']; } public function form( $instance ) { $title = ! empty( $instance['title'] ) ? $instance['title'] : esc_html__( '', 'text_domain' ); $text = ! empty( $instance['text'] ) ? $instance['text'] : esc_html__( '', 'text_domain' ); ?> <p> <label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>"><?php esc_attr_e( 'Title:', 'text_domain' ); ?></label> <input class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>"> </p> <p> <textarea class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'text' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'text' ) ); ?>" type="text" cols="30" rows="10"><?php echo esc_attr( $text ); ?></textarea> </p> <?php } public function update( $new_instance, $old_instance ) { $instance = array(); $instance['title'] = ( !empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : ''; $instance['text'] = ( !empty( $new_instance['text'] ) ) ? $new_instance['text'] : ''; return $instance; } } $my_widget = new My_Widget(); ``` 上面的代碼將在后面的文章中詳細解釋。 ## 開發小部件要創建和顯示窗口小部件，您需要執行以下操作： - 通過擴展標準的WP_Widget類及其一些功能來創建小部件的類。 - 注冊您的小部件，以便它可以在Widgets屏幕中使用。 - 確保您的主題至少有一個小部件區域添加小部件。 ## 你的小部件類 WP_Widget類位于wp-includes / widgets.php中 ``` class My_Widget extends WP_Widget { public function __construct() { // actual widget processes } public function widget( $args, $instance ) { // outputs the content of the widget } public function form( $instance ) { // outputs the options form in the admin } public function update( $new_instance, $old_instance ) { // processes widget options to be saved } } ``` 每個這些功能的文檔可以在窗口小部件類代碼中找到： - `__construct`：在管理員中設置具有說明，名稱和顯示寬度的小部件。 - `widget`：處理小部件選項并在頁面上顯示HTML。 $ args參數提供了HTML可以用來顯示窗口小部件標題類和窗口小部件內容類。 - `form`：顯示用于設置窗口小部件選項的窗體。如果您的窗口小部件沒有任何選項，則可以跳過此功能（盡管即使空白也是最佳做法）。 - `update`：將小部件選項保存到數據庫。如果您的窗口小部件沒有任何選項，則可以跳過此功能（盡管即使空白也是最佳做法）。 ## 注冊小部件 register_widget()函數用于注冊一個小部件。使用widgets_init鉤子調用此函數： ``` add_action( 'widgets_init', function() { register_widget( 'My_Widget' ); } ); ``` 當您使用register_sidebar()注冊窗口小部件時，將指定包含窗口小部件的HTML以及標題和窗口小部件內容的類。 ## 示例文本小部件從本文開頭的示例中構建文本小部件。您將首先設置一個擴展WP_Widget類的窗口小部件類。在類構造函數中，您將調用父構造函數并將其傳遞給您的窗口小部件的基本ID和名稱。同樣在類構造函數中，您將掛接到widgets_init操作以注冊您的窗口小部件。接下來，您將聲明創建窗口小部件時使用的參數。你必須定義四個參數，before_title，after_title，before_widget和after_widget。這些參數將定義包裝小部件標題和小部件本身的代碼。定義參數后，您將定義小部件功能。此函數有兩個參數，前面的$ args數組和窗口小部件的$實例，它將處理表單中的選項，并在您網站的前端顯示窗口小部件的HTML。在上面的例子中，窗口小部件功能簡單地輸出窗口小部件標題，同時通過widget_title過濾器。然后，它放置一個簡單的小部件包裝器和小部件的文本字段的內容。如示例中所述，您可以從存儲在$ instance中的小部件訪問選項。接下來你將定義表單函數。此函數使用一個參數$ instance，并輸出用戶在Widgets管理屏幕中用于創建窗口小部件的窗體。在上面的例子中，函數首先定義$ title和$ text變量，并將它們設置為先前輸入的值（如果存在這些值）。然后，它輸出一個簡單的表單，帶有標題的文本字段和文本內容的textarea。最后你將定義更新功能。此函數具有兩個參數$ new_instance和$ old_instance，并且負責在提交時使用新選項更新您的小部件。在這里，您只需將$ instance定義為空數組。然后，您將標題和文本鍵設置為$ new_instance值（如果存在）。然后你返回$ instance。最后，當定義所有上述內容時，您將實例化新的小部件類并測試您的工作。 ## 示例小部件 ``` /** * Adds Foo_Widget widget. */ class Foo_Widget extends WP_Widget { /** * Register widget with WordPress. */ public function __construct() { parent::__construct( 'foo_widget', // Base ID 'Foo_Widget', // Name array( 'description' => __( 'A Foo Widget', 'text_domain' ), ) // Args ); } /** * Front-end display of widget. * * @see WP_Widget::widget() * * @param array $args Widget arguments. * @param array $instance Saved values from database. */ public function widget( $args, $instance ) { extract( $args ); $title = apply_filters( 'widget_title', $instance['title'] ); echo $before_widget; if ( ! empty( $title ) ) { echo $before_title . $title . $after_title; } echo __( 'Hello, World!', 'text_domain' ); echo $after_widget; } /** * Back-end widget form. * * @see WP_Widget::form() * * @param array $instance Previously saved values from database. */ public function form( $instance ) { if ( isset( $instance[ 'title' ] ) ) { $title = $instance[ 'title' ]; } else { $title = __( 'New title', 'text_domain' ); } ?> <p> <label for="<?php echo $this->get_field_name( 'title' ); ?>"><?php _e( 'Title:' ); ?></label> <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" /> </p> <?php } /** * Sanitize widget form values as they are saved. * * @see WP_Widget::update() * * @param array $new_instance Values just sent to be saved. * @param array $old_instance Previously saved values from database. * * @return array Updated safe values to be saved. */ public function update( $new_instance, $old_instance ) { $instance = array(); $instance['title'] = ( !empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : ''; return $instance; } } // class Foo_Widget ``` 然后可以在widgets_init鉤子中注冊此示例窗口小部件： ``` // Register Foo_Widget widget add_action( 'widgets_init', function() { register_widget( 'Foo_Widget' ); } ); ``` ##使用命名空間的示例如果您使用PHP 5.3命名空間，則應直接調用構造函數，如下例所示： ``` namespace a\b\c; class My_Widget_Class extends \WP_Widget { function __construct() { parent::__construct( 'baseID', 'name' ); } // ... rest of the functions } ``` 并使用以下命令調用注冊窗口 ``` add_action( 'widgets_init', function() { register_widget( 'a\b\c\My_Widget_Class' ); } ); ``` 有關詳細信息，請參閱堆棧交換中的此答案。 ## 特殊考慮如果要在其他模板文件中使用小部件，而不是側邊欄，則可以the_widget()以編程方式顯示。該函數接受窗口小部件類名。您將小部件類名稱傳遞給這樣的函數： ``` <h1><?php the_title(); ?></h1> <div class="content"> <?php the_content(); ?> </div> <div class="widget-section"> <?php the_widget( 'My_Widget_Class' ); ?> </div> ``` 如果您需要在頁面上的特定區域中使用窗口小部件，則可能需要使用此方法，例如在網站首頁的某個部分中顯示表單旁邊的事件列表，或者顯示電子郵件捕獲表單一個超級菜單旁邊的導航。