云策 WordPress 开发者社区

钩子文档

in_widget_form

查看官方原文 ↗
💡 云策文档标注

概述

in_widget_form 是一个 WordPress 动作钩子，用于在小部件控制表单末尾触发，允许开发者添加自定义字段。仅当传递给 'widget_form_callback' 钩子的值不为 false 时才会触发。

关键要点

  • in_widget_form 钩子在小部件控制表单末尾触发，用于扩展表单功能。
  • 钩子接收三个参数：$widget（WP_Widget 实例，引用传递）、$return（返回 null 如果添加了新字段）和 $instance（小部件设置数组）。
  • 如果小部件没有表单，可以使用 CSS 隐藏默认表单方法输出的文本。
  • 钩子自 WordPress 2.8.0 版本引入。

代码示例

add_action( 'in_widget_form', 'wpdocs_display_custom_field_in_widget_form', 10, 3 );
function wpdocs_display_custom_field_in_widget_form( $widget, $return, $instance ) {
    $column = isset( $instance['column'] ) ? $instance['column'] : '';
    ob_start();
    ?>
    <p>
        <label for="<?php echo esc_attr( $widget->get_field_id( 'column' ) ); ?>">
            <?php esc_html_e( 'Column:', 'textdomain' ); ?>
        </label>
        <input id="<?php echo esc_attr( $widget->get_field_id( 'column' ) ); ?>" name="<?php echo esc_attr( $widget->get_field_name( 'column' ) ); ?>" type="text" value="<?php echo esc_attr( $column ); ?>" />
    </p>
    <?php
    echo ob_get_clean();
}

注意事项

  • 添加自定义字段后，需要使用 widget_update_callback 钩子来保存字段数据，如示例中所示。
  • 确保正确处理参数传递和转义输出，以维护安全性和兼容性。
📄 原文内容

Fires at the end of the widget control form.

Description

Use this hook to add extra fields to the widget form. The hook is only fired if the value passed to the ‘widget_form_callback’ hook is not false.

Note: If the widget has no form, the text echoed from the default form method can be hidden using CSS.

Parameters

$widgetWP_Widget
The widget instance (passed by reference).
$returnnull
Return null if new fields are added.
$instancearray
An array of the widget’s settings.

Source

do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );

View all references View on Trac View on GitHub

Used by Description
WP_REST_Widget_Types_Controller::get_widget_form()wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php

Returns the output of WP_Widget::form() when called with the provided instance. Used by encode_form_data() to preview a widget’s form.
WP_Widget::form_callback()wp-includes/class-wp-widget.php

Generates the widget control form (Do NOT override).

Changelog

Version Description
2.8.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Razon Komar Pal


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Add custom widget field end of the widgets control form.

    if ( ! function_exists( 'wpdocs_display_custom_field_in_widget_form' ) ) {

    add_action( 'in_widget_form', 'wpdocs_display_custom_field_in_widget_form', 10, 3 );

    /**
     * Append custom field end of the widgets control form
     * Fires at the end of the widget control form.
     */
    function wpdocs_display_custom_field_in_widget_form( $widget, $return, $instance ) {
        $column = isset( $instance['column'] ) ? $instance['column'] : '';

        ob_start();
        ?>

        <p>
            <label for="<?php echo esc_attr( $widget->get_field_id( 'itclan_bs_grid_class' ) ) ?>">
                <input class="widefat" value="<?php echo esc_attr( $column ) ?>" id="<?php echo esc_attr( $widget->get_field_id( 'column' ) ) ?>" name="<?php echo esc_attr( $widget->get_field_name( 'column' ) ) ?>" type="text" />
                <small></small>
            </label>
        </p>

        </pre>
<p>Filter widget’s settings before saving. It will save our custom field <code>column</code> data.</p>
<pre class="wp-block-code"><code lang="php" class="language-php line-numbers">if ( ! function_exists( 'wpdocs_update_custom_field_in_widget_form' ) ) {

    add_action( 'widget_update_callback', 'wpdocs_update_custom_field_in_widget_form', 10, 2 );

    /**
     * Update widget fields
     * Filters a widget’s settings before saving.
     */
    function wpdocs_update_custom_field_in_widget_form( $instance, $new_instance ) {
        $instance['column'] = ! empty( $new_instance['column'] ) ? $new_instance['column'] : '';
        return $instance;
    }
}