云策 WordPress 开发者社区

钩子文档

dynamic_sidebar_params

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

概述

dynamic_sidebar_params 是一个 WordPress 过滤器，用于修改传递给小部件显示回调的参数。该过滤器在前端和后端均生效，包括小部件屏幕上的非活动小部件侧边栏。

关键要点

  • 过滤器名称：dynamic_sidebar_params，通过 apply_filters 调用。
  • 参数：$params 是一个数组，包含侧边栏和小部件的显示参数，如 name、id、before_widget、after_widget、widget_id 等。
  • 应用场景：可用于动态调整小部件输出，例如添加自定义 CSS 类或修改 HTML 标记。
  • 相关函数：与 register_sidebar()、dynamic_sidebar() 和 wp_render_widget() 关联。

代码示例

add_filter( 'dynamic_sidebar_params', 'wpdocs_filter_dynamic_sidebar_params' );
function wpdocs_filter_dynamic_sidebar_params( $params ) {
    global $wp_registered_widgets;
    $widget_id = $params[0]['widget_id'];
    $widget_obj = $wp_registered_widgets[ $widget_id ];
    $widget_opt = get_option( $widget_obj['callback'][0]->option_name );
    $widget_num = $widget_obj['params'][0]['number'];
    $grid_class = isset( $widget_opt[ $widget_num ]['column'] ) ? $widget_opt[ $widget_num ]['column'] : '';

    if ( preg_match( '/class="/', $params[0]['before_widget'] ) && $grid_class ) {
        $params[0]['before_widget'] = preg_replace( '/class="/', "class="{$grid_class} ", $params[0]['before_widget'], 1 );
    }

    return $params;
}

注意事项

  • 过滤器在 WordPress 2.5.0 版本引入，确保兼容性。
  • 参数 $params 是一个多维数组，通常包含侧边栏和小部件信息，操作时需注意数组结构。
  • 示例代码展示了如何从小部件选项获取自定义字段并修改 before_widget 的 class 属性，适用于前端样式定制。
📄 原文内容

Filters the parameters passed to a widget’s display callback.

Description

Note: The filter is evaluated on both the front end and back end, including for the Inactive Widgets sidebar on the Widgets screen.

See also

Parameters

$paramsarray

  • args array
    An array of widget display arguments.

    • name string
      Name of the sidebar the widget is assigned to.
    • id string
      ID of the sidebar the widget is assigned to.
    • description string
      The sidebar description.
    • class string
      CSS class applied to the sidebar container.
    • before_widget string
      HTML markup to prepend to each widget in the sidebar.
    • after_widget string
      HTML markup to append to each widget in the sidebar.
    • before_title string
      HTML markup to prepend to the widget title when displayed.
    • after_title string
      HTML markup to append to the widget title when displayed.
    • widget_id string
      ID of the widget.
    • widget_name string
      Name of the widget.
  • widget_args array
    An array of multi-widget arguments.

    • number int
      Number increment used for multiples of the same widget.

Source

$params = apply_filters( 'dynamic_sidebar_params', $params );

View all references View on Trac View on GitHub

Used by Description
wp_render_widget()wp-includes/widgets.php

Calls the render callback of a widget and returns the output.
dynamic_sidebar()wp-includes/widgets.php

Displays dynamic sidebar.

Changelog

Version Description
2.5.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: 1You must log in to vote on the helpfulness of this note

    Firstly we create a custom widget field end of the each 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>Now, we 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;
    }
}

    Finally, filter sidebar params for frontend. It will add class to before_widget from column field

    if ( ! function_exists( 'wpdocs_filter_dynamic_sidebar_params' ) ) {

    add_action( 'dynamic_sidebar_params', 'wpdocs_filter_dynamic_sidebar_params' );

    /**
     * Update widget fields
     * Filters the parameters passed to a widget’s display callback.
     */
    function wpdocs_filter_dynamic_sidebar_params( $params ) {
        global $wp_registered_widgets;
        $widget_id        = $params[0]['widget_id'];
        $widget_obj       = $wp_registered_widgets[ $widget_id ];
        $widget_opt       = get_option( $widget_obj['callback'][0]->option_name );
        $widget_num       = $widget_obj['params'][0]['number'];
        $grid_class       = isset( $widget_opt[ $widget_num ]['column'] ) ? $widget_opt[ $widget_num ]['column'] : '';

        if ( preg_match( '/class="/', $params[0]['before_widget'] ) && $grid_class ) {
            $params[0]['before_widget'] = preg_replace( '/class="/', "class="{$grid_class} ", $params[0]['before_widget'], 1 );
        }

        return $params;
    }
}

You must log in before being able to contribute a note or feedback.