云策 WordPress 开发者社区

块编辑器开发文档

SearchControl

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

概述

SearchControl 是 WordPress 组件库中的一个 React 组件，用于提供搜索输入界面。它允许用户输入搜索内容，并支持多种自定义属性以增强可访问性和功能。

关键要点

  • SearchControl 用于渲染搜索控件，支持标签、占位符、值、类名等属性。
  • 核心属性包括 onChange（必需，处理输入变化）、label（推荐用于可访问性）、value（当前输入值）和 className（添加包装 div 的类）。
  • 其他属性如 placeholder、help、hideLabelFromVision、size 和 onClose（已弃用）提供了额外定制选项。
  • 组件基于 React 和 WordPress i18n 构建，需导入 @wordpress/components 使用。

代码示例

import { useState } from 'react';
import { __ } from '@wordpress/i18n';
import { SearchControl } from '@wordpress/components';

function MySearchControl( { className, setState } ) {
    const [ searchInput, setSearchInput ] = useState( '' );

    return (
        <SearchControl
            label={ __( 'Search posts' ) }
            value={ searchInput }
            onChange={ setSearchInput }
        />
    );
}

注意事项

  • label 属性应始终提供以确保可访问性，即使定义了 placeholder 或 hideLabelFromVision 为 true。
  • onClose 属性已弃用，建议使用自定义逻辑替代。
  • 未包含在 props 列表中的属性将应用于输入元素。
  • 对于更受限的输入选项，可考虑使用 TextControl、SelectControl 等其他相关组件。
📄 原文内容

SearchControl components let users display a search control.

Check out the Storybook page for a visual exploration of this component.

Development guidelines

Usage

Render a user interface to input the name of an additional css class.

import { useState } from 'react';
import { __ } from '@wordpress/i18n';
import { SearchControl } from '@wordpress/components';

function MySearchControl( { className, setState } ) {
    const [ searchInput, setSearchInput ] = useState( '' );

    return (
        <SearchControl
            label={ __( 'Search posts' ) }
            value={ searchInput }
            onChange={ setSearchInput }
        />
    );
}

Props

The set of props accepted by the component will be specified below.
Props not included in this set will be applied to the input element.

label

The accessible label for the input.

A label should always be provided as an accessibility best practice, even when a placeholder is defined
and hideLabelFromVision is true.

  • Type: String
  • Required: No
  • Default: __( 'Search' )

placeholder

If this property is added, a specific placeholder will be used for the input.

  • Type: String
  • Required: No
  • Default: __( 'Search' )

value

The current value of the input.

  • Type: String
  • Required: No

className

The class that will be added to the classes of the wrapper div.

  • Type: String
  • Required: No

onChange

A function that receives the value of the input.

  • Type: function
  • Required: Yes

onClose

Note: this prop is deprecated.

When an onClose callback is provided, the search control will render a close button that will trigger the given callback.

Use this if you want the button to trigger your own logic to close the search field entirely, rather than just clearing the input value.

  • Type: function
  • Required: No

help

If this property is added, a help text will be generated using help property as the content.

  • Type: String|Element
  • Required: No

hideLabelFromVision

If true, the label will not be visible, but will be read by screen readers. Defaults to true.

  • Type: Boolean
  • Required: No
  • Default: true

size: 'default' | 'compact'

The size of the component.

  • Required: No
  • Default: 'default'

Related components

  • To offer users more constrained options for input, use TextControl, SelectControl, RadioControl, CheckboxControl, or RangeControl.