查看 WordPress Storybook 以获取更详细、交互式的文档。

BaseControl 是一个低级组件，用于为处理用户输入的组件生成标签和帮助文本。

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

// 渲染一个用于 textarea 输入的 `BaseControl`
const MyCustomTextareaControl = ({ children, ...baseProps }) => (
    // `useBaseControlProps` 是一个便捷钩子，用于获取 `BaseControl`
    // 以及内部控件本身的 props。具体来说，它负责生成唯一的 `id`，
    // 并将其与 `label` 和 `help` 元素正确关联。
    const { baseControlProps, controlProps } = useBaseControlProps( baseProps );

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

Props

as

  • Type: "symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...
  • Required: Yes

要渲染该组件的 HTML 元素。

className

  • Type: string
  • Required: No

children

  • Type: ReactNode
  • Required: Yes

要在 BaseControl 内显示的内容。

help

  • Type: ReactNode
  • Required: No

控件的附加描述。

仅用于控件有意义的描述或说明。包含描述的元素将通过 aria-describedby 属性在程序上关联到 BaseControl。

hideLabelFromVision

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

如果为 true，则标签仅对屏幕阅读器可见。

id

  • Type: string
  • Required: No

控件元素的 HTML id（作为子项传递给 BaseControl），正在为其生成标签和帮助文本。
这对于无障碍地将标签与该元素关联是必要的。

推荐的方式是使用 useBaseControlProps 钩子，它负责为您生成唯一的 id。
否则，如果您选择向此 prop 传递显式的 id，您需要确保 id 的唯一性。

label

  • Type: ReactNode
  • Required: No

如果添加了此属性，将使用 label 属性的内容生成标签。

Subcomponents

BaseControl.VisualLabel

BaseControl.VisualLabel 用于在 BaseControl 组件内渲染纯视觉标签。

它仅应在 BaseControl 内渲染的子项已经具有无障碍标签的情况下使用，
例如按钮，但我们希望为该部分提供额外的视觉标签，相当于如果传递了 label prop 时
BaseControl 通常会使用的标签。

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: keyof IntrinsicElements | JSXElementConstructor<any>
  • Required: No

要渲染该组件的 HTML 元素或 React 组件。

children
  • Type: ReactNode
  • Required: Yes

要在 BaseControl.VisualLabel 内显示的内容。