canvas-component-metadata

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

File structure

文件结构

Every

component.yml

must include these top-level keys:

yaml

name: Component Name # Human-readable display name
machineName: component-name # Machine name in kebab-case
status: true # Whether the component is enabled
required: [] # Array of required prop names
props:
  properties:
    # ... prop definitions
slots: [] # Use [] only when there are no slots; otherwise use an object map

每个

component.yml

必须包含以下顶级键：

yaml

name: 组件名称 # 人类可读的显示名称
machineName: component-name # 短横线命名的机器名称
status: true # 组件是否启用
required: [] # 必填props名称数组
props:
  properties:
    # ... props定义
slots: [] # 没有插槽时使用[]；否则使用对象映射

Props

Requirements

要求

Every prop definition must include a

title

for the UI label. The

examples

array is required for required props and recommended for all others. Only the first example value is used by Drupal Canvas.

yaml

props:
  properties:
    heading:
      title: Heading
      type: string
      examples:
        - Enter a heading...

Prop IDs must be camelCase versions of their titles.

The prop ID (the key under

properties

) must be the camelCase conversion of the

title

value.

yaml

undefined

每个props定义必须包含用于UI标签的

title

。必填props必须包含

examples

数组，其他props也推荐添加。Drupal Canvas仅使用第一个示例值。

yaml

props:
  properties:
    heading:
      title: 标题
      type: string
      examples:
        - 输入标题...

Props ID必须是其title的小驼峰式（camelCase）版本。

Props ID（

properties

下的键）必须是

title

值的小驼峰式转换。

yaml

undefined

Correct

正确写法

props: properties: buttonText: # camelCase of "Button Text" title: Button Text type: string backgroundColor: # camelCase of "Background Color" title: Background Color type: string isVisible: # camelCase of "Is Visible" title: Is Visible type: boolean

props: properties: buttonText: # “Button Text”的小驼峰式 title: Button Text type: string backgroundColor: # “Background Color”的小驼峰式 title: Background Color type: string isVisible: # “Is Visible”的小驼峰式 title: Is Visible type: boolean

Wrong

错误写法

props: properties: btn_text: # should be "buttonText" for title "Button Text" title: Button Text bgColor: # should be "backgroundColor" for title "Background Color" title: Background Color

undefined

props: properties: btn_text: # “Button Text”应改为“buttonText” title: Button Text bgColor: # “Background Color”应改为“backgroundColor” title: Background Color

undefined

Prop types

Props类型

Text

文本

Basic text input. Stored as a string value.

yaml

type: string
examples:
  - Hello, world!

基础文本输入，存储为字符串值。

yaml

type: string
examples:
  - 你好，世界！

Formatted text

格式化文本

Rich text content with HTML formatting support, displayed in a block context.

yaml

type: string
contentMediaType: text/html
x-formatting-context: block
examples:
  - <p>This is <strong>formatted</strong> text with HTML.</p>

支持HTML格式的富文本内容，在块级上下文中显示。

yaml

type: string
contentMediaType: text/html
x-formatting-context: block
examples:
  - <p>这是带有HTML的<strong>格式化</strong>文本。</p>

Link

链接

URL or URI reference for links to internal or external resources.

yaml

type: string
format: uri-reference
examples:
  - /about/contact

Note: The format can be either

uri

(accepts only absolute URLs) or

uri-reference

(accepts both absolute and relative URLs).

IMPORTANT: Use proper path examples for URL props. Do not use

as an example value for

uri-reference

props—it can cause validation failures during upload. Always use realistic path-like examples:

yaml

undefined

指向内部或外部资源的URL或URI引用。

yaml

type: string
format: uri-reference
examples:
  - /about/contact

注意： 格式可以是

uri

（仅接受绝对URL）或

uri-reference

（接受绝对和相对URL）。

重要提示：URL props请使用正确的路径示例。 不要将

作为

uri-reference

props的示例值——这会导致上传时验证失败。请始终使用真实的类路径示例：

yaml

undefined

Correct

正确写法

examples:

/resources
/about/team
https://example.com/page

examples:

/resources
/about/team
https://example.com/page

Wrong

错误写法

examples:

undefined

examples:

undefined

Image

图片

Reference to an image object with metadata like alt text, dimensions, and file URL. Only the file URL is required to exist, all other metadata is always optional.

yaml

type: object
$ref: json-schema-definitions://canvas.module/image
examples:
  - src: >-
      https://images.unsplash.com/photo-1484959014842-cd1d967a39cf?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1770&q=80
    alt: Woman playing the violin
    width: 1770
    height: 1180

指向包含替代文本、尺寸和文件URL等元数据的图片对象的引用。仅要求文件URL必须存在，所有其他元数据均为可选。

yaml

type: object
$ref: json-schema-definitions://canvas.module/image
examples:
  - src: >-
      https://images.unsplash.com/photo-1484959014842-cd1d967a39cf?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1770&q=80
    alt: 拉小提琴的女性
    width: 1770
    height: 1180

Video

视频

Reference to a video object with metadata like dimensions and file URL. Only the file URL is required to exist, all other metadata is always optional.

yaml

type: object
$ref: json-schema-definitions://canvas.module/video
examples:
  - src: https://media.istockphoto.com/id/1340051874/video/aerial-top-down-view-of-a-container-cargo-ship.mp4?s=mp4-640x640-is&k=20&c=5qPpYI7TOJiOYzKq9V2myBvUno6Fq2XM3ITPGFE8Cd8=
    poster: https://example.com/600x400.png

指向包含尺寸和文件URL等元数据的视频对象的引用。仅要求文件URL必须存在，所有其他元数据均为可选。

yaml

type: object
$ref: json-schema-definitions://canvas.module/video
examples:
  - src: https://media.istockphoto.com/id/1340051874/video/aerial-top-down-view-of-a-container-cargo-ship.mp4?s=mp4-640x640-is&k=20&c=5qPpYI7TOJiOYzKq9V2myBvUno6Fq2XM3ITPGFE8Cd8=
    poster: https://example.com/600x400.png

Boolean

布尔值

True or false value.

yaml

type: boolean
examples:
  - false

真或假的值。

yaml

type: boolean
examples:
  - false

Integer

整数

Whole number value without decimal places.

yaml

type: integer
examples:
  - 42

不带小数的整数值。

yaml

type: integer
examples:
  - 42

Number

数字

Numeric value that can include decimal places.

yaml

type: number
examples:
  - 3.14

可以包含小数的数值。

yaml

type: number
examples:
  - 3.14

List: text

列表：文本

A predefined list of text options that the user can select from.

yaml

type: string
enum:
  - option1
  - option2
  - option3
meta:enum:
  option1: Option 1
  option2: Option 2
  option3: Option 3
examples:
  - option1

用户可以从中选择的预定义文本选项列表。

yaml

type: string
enum:
  - option1
  - option2
  - option3
meta:enum:
  option1: 选项1
  option2: 选项2
  option3: 选项3
examples:
  - option1

List: integer

列表：整数

A predefined list of integer options that the user can select from.

yaml

type: integer
enum:
  - 1
  - 2
  - 3
meta:enum:
  1: Option 1
  2: Option 2
  3: Option 3
examples:
  - 1

用户可以从中选择的预定义整数选项列表。

yaml

type: integer
enum:
  - 1
  - 2
  - 3
meta:enum:
  1: 选项1
  2: 选项2
  3: 选项3
examples:
  - 1

Enums

枚举（Enums）

Enum values must use lowercase, machine-friendly identifiers. Use

meta:enum

to provide human-readable display labels for the UI.

Note: Enum values cannot contain dots.

yaml

undefined

枚举值必须使用小写、机器友好的标识符。请使用

meta:enum

为UI提供人类可读的显示标签。

注意： 枚举值不能包含点。

yaml

undefined

Correct

正确写法

enum:

left_aligned
center_aligned meta:enum: left_aligned: Left aligned center_aligned: Center aligned examples:
left_aligned

enum:

left_aligned
center_aligned meta:enum: left_aligned: 左对齐 center_aligned: 居中对齐 examples:
left_aligned

Wrong

错误写法

enum:

Left aligned
Center aligned


The `examples` value must be the enum value, not the display label.

enum:

Left aligned
Center aligned


`examples`值必须是枚举值，而不是显示标签。

Enum values must match JSX component variants

枚举值必须与JSX组件变体匹配

When using class-variance-authority (CVA) or similar libraries in the JSX component, the variant keys must exactly match the enum values defined in

component.yml

jsx

// component.yml defines: enum: [left_aligned, center_aligned]
// CVA variants must match:
const variants = cva("base-classes", {
  variants: {
    layout: {
      left_aligned: "text-left", // matches enum value
      center_aligned: "text-center", // matches enum value
    },
  },
});

在JSX组件中使用class-variance-authority（CVA）或类似库时，变体键必须与

component.yml

中定义的枚举值完全匹配。

jsx

// component.yml定义：enum: [left_aligned, center_aligned]
// CVA变体必须匹配：
const variants = cva("base-classes", {
  variants: {
    layout: {
      left_aligned: "text-left", // 匹配枚举值
      center_aligned: "text-center", // 匹配枚举值
    },
  },
});

Slots

插槽（Slots）

Slots allow other components to be embedded within a component. In React, each slot is received as a named prop that matches the slot key.

Before creating slots, confirm with the user unless the use case is clearly compositional (for example, rich nested content, or repeatable embedded components). For simple text-like values, prefer a prop.

Important: Do not map Canvas slots to the

children

prop by default. If the slot key is

content

, consume it as

content

in JSX.

Using a slot key named

children

is technically possible, but it is not recommended because slot naming often flows into user-facing Canvas labels. Prefer explicit slot keys such as

content

media

, or

actions

slots

must be either:

An object map keyed by slot name (
```
content
```
,
```
sidebar
```
, etc.)
```
[]
```
when the component has no slots

yaml

slots:
  content:
    title: Content
  buttons:
    title: Buttons

In the JSX component, slots are destructured as named props and rendered directly:

jsx

const Section = ({ width, content }) => {
  return <div className={sectionVariants({ width })}>{content}</div>;
};

jsx

// Wrong when the slot key is `content`: this does not consume the named slot.
const Section = ({ children }) => {
  return <div>{children}</div>;
};

Use

slots: []

only when the component has no slots:

yaml

slots: []

Do not use arrays of slot objects:

yaml

undefined

插槽允许在一个组件中嵌入其他组件。在React中，每个插槽会作为与插槽键匹配的命名props被接收。

创建插槽前，请与用户确认，除非使用场景明显是组合式的（例如，富嵌套内容或可重复的嵌入组件）。对于简单的类文本值，优先使用props。

重要提示：默认情况下，不要将Canvas插槽映射到
children
props。如果插槽键是
content
，请在JSX中以
content
的形式使用它。

虽然技术上可以使用名为

children

的插槽键，但不推荐这样做，因为插槽名称通常会体现在面向用户的Canvas标签中。优先使用明确的插槽键，如

content

、

media

或

actions

。

slots

必须是以下两种形式之一：

以插槽名称（
```
content
```
、
```
sidebar
```
等）为键的对象映射
组件没有插槽时使用
```
[]
```

yaml

slots:
  content:
    title: 内容
  buttons:
    title: 按钮

在JSX组件中，插槽会被解构为命名props并直接渲染：

jsx

const Section = ({ width, content }) => {
  return <div className={sectionVariants({ width })}>{content}</div>;
};

jsx

// 当插槽键为`content`时的错误写法：没有使用命名插槽
const Section = ({ children }) => {
  return <div>{children}</div>;
};

组件没有插槽时，请使用

slots: []

：

yaml

slots: []

不要使用插槽对象数组：

yaml

undefined

Wrong

错误写法

slots:

name: content title: Content

undefined

slots:

name: content title: 内容

undefined