UI 视觉设计 / 系统课时
为组件约定插槽与组合接口
为组件约定插槽与组合接口
同一张卡片可能显示说明文字、数据列表或操作按钮。如果把每一种内容组合都做成 Figma 变体,组件数量会迅速膨胀。本篇以 Card 为例,区分外观属性与内容区域,约定 React 的 children、命名插槽以及复合组件的使用边界。
学习目标
- 判断哪些变化属于设计变体,哪些应交给调用方提供内容。
- 用
children和ReactNode命名属性实现可复用的内容区域。 - 根据布局自由度判断何时需要复合组件,并验证接口可用性。
把外观变化与内容变化分开
假设一张卡片有两种尺寸、两种视觉强调等级和启用/禁用两种状态,外观组合最多为 2 × 2 × 2 = 8 种。如果又把三种正文类型、两种标题和两种按钮数量都乘进去,就会膨胀为 96 种。正文文案和嵌套结构不应成为变体轴。
| 变化 | Figma 中的处理 | React 中的接口 |
|---|---|---|
| 紧凑/常规尺寸 | Size 变体 |
size 枚举属性 |
| 标题文案 | 文本属性或实例内编辑 | title: string |
| 段落、列表、提示内容 | 保留可调整的正文布局区 | children: ReactNode |
| 零个或一个操作区 | 在实例中展示或隐藏操作区域 | actions?: ReactNode |
判断标准很直接:改变颜色、间距或状态选外观属性;替换文字、列表或按钮组合则使用内容接口。 Figma 的实例结构和 React 组件树并非自动同步,需要团队在组件规范中明确区域对应关系。
选择三种组合方式
| 方式 | 适用条件 | 接口约定 |
|---|---|---|
children |
只有一个主要内容区域,内容类型不固定 | 把嵌套 JSX 渲染在正文容器内 |
| 命名插槽 | 标题、操作、页脚等区域位置固定 | 用 header、actions、footer 等 ReactNode 属性传入 |
| 复合组件 | 子项数量可变、允许灵活排列且需共享状态 | 约定如 Tabs.List、Tabs.Trigger、Tabs.Panel 的子组件协议 |
这里的“命名插槽”是 React 组件自定义的属性模式,并非 React 内置的 slot 语法;HTML 的 <slot> 主要服务于 Web Components。复合组件的子组件名称同样是团队设计的 API,而非 React 自带组件。
本例的 Card 有稳定的标题、正文和操作位置,采用 children 加可选 actions 即可;不需要为简单卡片引入上下文状态或复杂的子组件解析。
将 Figma 区域映射为组件契约
在 Figma 的 Card 主组件中,用纵向 Auto Layout 组织 Header 与 Body,Header 内横向排列标题和可选操作位。常规内边距约定为 20 px,紧凑内边距为 12 px;真实项目应由设计令牌提供这两个值。

接口还应约定三条不变量:标题必须为可读文本;actions 缺省时不生成空白操作容器;children 可包含段落或列表,但卡片不替调用方决定业务数据、按钮点击行为。
用 React 实现并运行
示例适用于 React 18/19、TypeScript 和 Vite 的 react-ts 模板。使用支持当前 Vite 的 Node.js 版本(20.19+ 或 22.12+),先创建项目:
npm create vite@latest card-slots -- --template react-ts
cd card-slots
npm install
npm run dev预期结果:终端显示本地开发地址,例如 http://localhost:<PORT>/;<PORT> 由运行环境决定。将 src/App.tsx 替换为以下完整代码:
import { useId, useState } from 'react';
import type { ReactNode } from 'react';
type CardProps = {
title: string;
size?: 'compact' | 'regular';
actions?: ReactNode;
children: ReactNode;
};
function Card({ title, size = 'regular', actions, children }: CardProps) {
const headingId = useId();
const padding = size === 'compact' ? 12 : 20;
return (
<section
aria-labelledby={headingId}
style={{ border: '1px solid #CBD5E1', borderRadius: 12, padding }}
>
<header style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 12 }}>
<h2 id={headingId} style={{ margin: 0, fontSize: 18 }}>{title}</h2>
{/* 不传 actions 时不创建空操作区。 */}
{actions != null ? <div style={{ display: 'flex', gap: 8 }}>{actions}</div> : null}
</header>
{/* children 只约束所在区域,不限制内容种类。 */}
<div style={{ marginTop: 12 }}>{children}</div>
</section>
);
}
export default function App() {
const [saved, setSaved] = useState(false);
return (
<main style={{ maxWidth: 520, margin: '40px auto', display: 'grid', gap: 16 }}>
<Card
title="本月账单"
actions={
<button type="button" onClick={() => setSaved(!saved)}>
{saved ? '已收藏' : '收藏'}
</button>
}
>
<p>本月支出:¥1,280</p>
</Card>
{/* 列表内容使用相同组件,无须新增设计变体。 */}
<Card title="账号安全" size="compact">
<ul>
<li>双重验证:已开启</li>
<li>登录设备:2 台</li>
</ul>
</Card>
</main>
);
}预期结果:浏览器显示上下两张卡片。第一张正文为金额段落,右上角有“收藏”按钮,点击后切换为“已收藏”;第二张正文为列表,没有空白操作区,内边距为 12 px。两个 <section> 各自通过 useId 关联标题,避免多实例使用相同 HTML ID。
验证组合边界与常见误用
- 把第一张卡片正文改成两段文字或列表,检查宽度和间距;不修改 Card 实现,也不增加 Figma 变体。
- 移除第一张卡片的
actions,检查 Header 是否仅剩标题;恢复后用 Tab 键聚焦按钮并按 Enter,应能切换收藏状态。 - 同时渲染三张 Card,在浏览器检查标题
id与aria-labelledby是否一一对应;不要硬编码相同 ID。 - 当一个组件出现多个可重复子项、复杂顺序和共享交互状态时,再评估复合组件。例如 Tabs 的触发器与面板需要明确匹配、选中状态和键盘行为,不能只把几个 JSX 子元素拼在一起就当成完整 Tabs。
不要把 JSX 内容预先转成字符串,也不要靠 cloneElement 给任意子元素强行注入属性:这会限制可组合性,并可能破坏自定义组件封装。Card 只约束区域、语义和布局;按钮是否显示、内容是什么以及交互如何执行,都由调用方负责。