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;真实项目应由设计令牌提供这两个值。

Card 设计区域到 React 内容接口的映射

接口还应约定三条不变量:标题必须为可读文本;actions 缺省时不生成空白操作容器;children 可包含段落或列表,但卡片不替调用方决定业务数据、按钮点击行为。

用 React 实现并运行

示例适用于 React 18/19、TypeScript 和 Vite 的 react-ts 模板。使用支持当前 Vite 的 Node.js 版本(20.19+ 或 22.12+),先创建项目:

bash
npm create vite@latest card-slots -- --template react-ts
cd card-slots
npm install
npm run dev

预期结果:终端显示本地开发地址,例如 http://localhost:<PORT>/;<PORT> 由运行环境决定。将 src/App.tsx 替换为以下完整代码:

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。

验证组合边界与常见误用

  1. 把第一张卡片正文改成两段文字或列表,检查宽度和间距;不修改 Card 实现,也不增加 Figma 变体。
  2. 移除第一张卡片的 actions,检查 Header 是否仅剩标题;恢复后用 Tab 键聚焦按钮并按 Enter,应能切换收藏状态。
  3. 同时渲染三张 Card,在浏览器检查标题 id 与 aria-labelledby 是否一一对应;不要硬编码相同 ID。
  4. 当一个组件出现多个可重复子项、复杂顺序和共享交互状态时,再评估复合组件。例如 Tabs 的触发器与面板需要明确匹配、选中状态和键盘行为,不能只把几个 JSX 子元素拼在一起就当成完整 Tabs。

不要把 JSX 内容预先转成字符串,也不要靠 cloneElement 给任意子元素强行注入属性:这会限制可组合性,并可能破坏自定义组件封装。Card 只约束区域、语义和布局;按钮是否显示、内容是什么以及交互如何执行,都由调用方负责。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为组件约定插槽与组合接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通