用于设置方框边框颜色、样式和宽度的输入控件。边框可以整体自定义，也可以针对方框的每一侧单独自定义。

开发指南

BorderBoxControl 实际上有两种视图状态。第一种是“链接”视图，允许通过单个 BorderControl 配置扁平边框。第二种是“拆分”视图，为每一侧包含一个 BorderControl，以及一个用于显示当前选定边框的可视化器。每个视图还包含一个按钮，用于在这两种视图之间切换。

当从“拆分”视图切换到“链接”时，如果各个侧边的边框不一致，“链接”视图将显示一致的边框属性选择，而对于不一致的属性则显示混合状态。例如，如果所有边框的颜色和样式相同但宽度不同，那么“链接”视图中 BorderControl 的边框下拉菜单将显示一致的颜色和样式，而“链接”视图中的宽度输入框将显示“Mixed”占位符文本。

用法

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

const colors = [
    { name: 'Blue 20', color: '#72aee6' },
    // ...
];

const MyBorderBoxControl = () => {
    const defaultBorder = {
        color: '#72aee6',
        style: 'dashed',
        width: '1px',
    };
    const [ borders, setBorders ] = useState( {
        top: defaultBorder,
        right: defaultBorder,
        bottom: defaultBorder,
        left: defaultBorder,
    } );
    const onChange = ( newBorders ) => setBorders( newBorders );

    return (
        <BorderBoxControl
            colors={ colors }
            label={ __( 'Borders' ) }
            onChange={ onChange }
            value={ borders }
        />
    );
};

如果您在编辑器外部使用此组件，可以通过在元素树更上层渲染 Popover.Slot 并在整体上位于 SlotFillProvider 内，来确保 BorderBoxControl 的颜色和样式选项的 Tooltip 定位。

Props

colors: ( PaletteObject | ColorObject )[]

颜色定义数组。这也可以是一个多维数组，其中颜色按多个来源组织。

每种颜色可以是包含 name 和 color 值的对象。

  • Required: No
  • Default: []

disableCustomColors: boolean

此属性切换选择自定义颜色的能力。

  • Required: No

enableAlpha: boolean

此属性控制在选择自定义颜色时是否提供 alpha 通道。

  • Required: No
  • Default: false

enableStyle: boolean

此属性控制是否支持边框样式选择。

  • Required: No
  • Default: true

hideLabelFromVision: boolean

控制标签是否仅对屏幕阅读器可见。

  • Required: No

label: string

如果提供，将使用此内容生成标签。可见标签与链接/未链接切换按钮在同一行呈现；当没有可见标签时，切换按钮将呈现在边框输入旁边。

它是否仅对屏幕阅读器可见由 hideLabelFromVision 控制。

  • Required: No

onChange: ( value?: Object ) => void

当任何边框值更改时调用的回调函数。接收到的值可能是“扁平”边框对象（即具有定义各个侧边边框属性的对象），或者是 undefined。

注意：如果用户清除所有边框，该值将为 undefined。

  • Required: Yes

popoverPlacement: string

颜色弹出窗口相对于控件包装器的位置。

默认情况下，弹出窗口相对于启动弹出窗口的按钮显示。通过提供弹出窗口位置，您可以强制弹出窗口在特定位置显示。

可用的基本位置包括 ‘top’、‘right’、‘bottom’、‘left’。这些基本位置每种都有 -start 和 -end 形式的对齐方式。例如，‘right-start’ 或 ‘bottom-end’。这允许您将工具提示对齐到按钮的边缘，而不是居中。

  • Required: No

popoverOffset: number | { mainAxis?: number; crossAxis?: number }

弹出窗口与控件包装器之间的间距。数字沿主轴位移弹出窗口；传递对象以同时沿交叉轴位移它。

  • Required: No

value: Object

表示当前边框配置的对象。

这可能是“扁平”边框，其中对象具有 color、style 和 width 属性；也可能是“拆分”边框，其中定义了上述属性，但针对每一侧：top、right、bottom 和 left。

示例：

const flatBorder = { color: '#72aee6', style: 'solid', width: '1px' };
const splitBorders = {
    top: { color: '#72aee6', style: 'solid', width: '1px' },
    right: { color: '#e65054', style: 'dashed', width: '2px' },
    bottom: { color: '#68de7c', style: 'solid', width: '1px' },
    left: { color: '#f2d675', style: 'dotted', width: '1em' },
};
  • Required: No