云策 WordPress 开发者社区

块编辑器开发文档

BaseControl

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

概述

BaseControl 是 WordPress 组件库中的一个底层组件，用于为处理用户输入的组件生成标签和帮助文本。它通过 useBaseControlProps Hook 简化了可访问性关联，并包含 BaseControl.VisualLabel 子组件用于纯视觉标签。

关键要点

  • BaseControl 主要用于生成可访问的标签和帮助文本，关联到内部控件元素。
  • 推荐使用 useBaseControlProps Hook 自动生成唯一 id 并处理 props，确保可访问性。
  • BaseControl.VisualLabel 子组件用于在控件已有可访问标签时添加纯视觉标签。
  • 支持通过 as 属性自定义渲染元素或 React 组件，以及通过 className 添加样式类。
  • props 包括 label、help、hideLabelFromVision 等，用于控制标签和帮助文本的显示与行为。

代码示例

import { BaseControl, useBaseControlProps } from '@wordpress/components';

// Render a `BaseControl` for a textarea input
const MyCustomTextareaControl = ({ children, ...baseProps }) => {
    const { baseControlProps, controlProps } = useBaseControlProps( baseProps );

    return (
        <BaseControl { ...baseControlProps }>
            <textarea { ...controlProps }>
              { children }
            </textarea>
        </BaseControl>
    );
};

注意事项

  • 使用 help 属性时，仅用于有意义的描述或指令，以确保可访问性。
  • 如果手动传递 id 属性，需确保其唯一性，否则推荐使用 useBaseControlProps。
  • BaseControl.VisualLabel 仅适用于控件已有可访问标签的场景，避免重复标签。
📄 原文内容

See the WordPress Storybook for more detailed, interactive documentation.

BaseControl is a low-level component used to generate labels and help text for components handling user inputs.

import { BaseControl, useBaseControlProps } from '@wordpress/components';

// Render a `BaseControl` for a textarea input
const MyCustomTextareaControl = ({ children, ...baseProps }) => (
    // `useBaseControlProps` is a convenience hook to get the props for the `BaseControl`
    // and the inner control itself. Namely, it takes care of generating a unique `id`,
    // properly associating it with the `label` and `help` elements.
    const { baseControlProps, controlProps } = useBaseControlProps( baseProps );

    return (
        <BaseControl { ...baseControlProps }>
            <textarea { ...controlProps }>
              { children }
            </textarea>
        </BaseControl>
    );
);

Props

as

  • Type: "symbol" | "object" | "label" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 516 more ... | ("view" & FunctionComponent<...>)
  • Required: No

The HTML element or React component to render the component as.

className

  • Type: string
  • Required: No

children

  • Type: ReactNode
  • Required: Yes

The content to be displayed within the BaseControl.

help

  • Type: ReactNode
  • Required: No

Additional description for the control.

Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an aria-describedby attribute.

hideLabelFromVision

  • Type: boolean
  • Required: No
  • Default: false

If true, the label will only be visible to screen readers.

id

  • Type: string
  • Required: No

The HTML id of the control element (passed in as a child to BaseControl) to which labels and help text are being generated.
This is necessary to accessibly associate the label with that element.

The recommended way is to use the useBaseControlProps hook, which takes care of generating a unique id for you.
Otherwise, if you choose to pass an explicit id to this prop, you are responsible for ensuring the uniqueness of the id.

label

  • Type: ReactNode
  • Required: No

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

Subcomponents

BaseControl.VisualLabel

BaseControl.VisualLabel is used to render a purely visual label inside a BaseControl component.

It should only be used in cases where the children being rendered inside BaseControl are already accessibly labeled,
e.g., a button, but we want an additional visual label for that section equivalent to the labels BaseControl would
otherwise use if the label prop was passed.

import { BaseControl } from '@wordpress/components';

const MyBaseControl = () => (
    <BaseControl help="This button is already accessibly labeled.">
        <BaseControl.VisualLabel>Author</BaseControl.VisualLabel>
        <Button>Select an author</Button>
    </BaseControl>
);

Props

as
  • Type: "symbol" | "object" | "label" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | ...
  • Required: No

The HTML element or React component to render the component as.

children
  • Type: ReactNode
  • Required: Yes

The content to be displayed within the BaseControl.VisualLabel.