云策 WordPress 开发者社区

块编辑器开发文档

Surface

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

概述

Surface 是 WordPress 核心组件库中的一个实验性组件，用于渲染主要背景颜色，支持多种变体和边框控制。该组件目前处于早期阶段，可能发生重大变更。

关键要点

  • Surface 是一个实验性组件，导入时需使用 __experimentalSurface 别名。
  • 组件提供 variant 属性来修改背景颜色，可选值包括 primary、secondary、tertiary、dotted 和 grid。
  • 支持通过 borderTop、borderRight、borderBottom、borderLeft 属性控制边框渲染。
  • backgroundSize 属性用于 dotted 和 grid 变体，定义网格大小。

代码示例

import {
    __experimentalSurface as Surface,
    __experimentalText as Text,
} from '@wordpress/components';

function Example() {
    return (
        <Surface>
            <Text>Code is Poetry</Text>
        </Surface>
    );
}

注意事项

  • 该组件为实验性功能，实现可能不稳定，不建议在生产环境中使用。
  • variant 的 tertiary 值仅在深色模式下可见，使用场景较少。
📄 原文内容
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

Surface is a core component that renders a primary background color.

Usage

In the example below, notice how the Surface renders in white (or dark gray if in dark mode).

import {
    __experimentalSurface as Surface,
    __experimentalText as Text,
} from '@wordpress/components';

function Example() {
    return (
        <Surface>
            <Text>Code is Poetry</Text>
        </Surface>
    );
}

Props

backgroundSize: number

  • Required: No
  • Default: 12

Determines the grid size for “dotted” and “grid” variants.

borderBottom: boolean

  • Required: No
  • Default: false

Renders a bottom border.

borderLeft: boolean

  • Required: No
  • Default: false

Renders a left border.

borderRight: boolean

  • Required: No
  • Default: false

Renders a right border.

borderTop: boolean

  • Required: No
  • Default: false

Renders a top border.

variant: string

  • Required: No
  • Default: false
  • Allowed values: primary, secondary, tertiary, dotted, grid

Modifies the background color of Surface.

  • primary: Used for almost all cases.
  • secondary: Used as a secondary background for inner Surface components.
  • tertiary: Used as the app/site wide background. Visible in dark mode only. Use case is rare.
  • grid: Used to show a grid.
  • dotted: Used to show a dots grid.