第2章 Material 3 组件中的 Slot 列表：Button、Card、Dialog

Slot（插槽）是 Material 3 组件体系中的核心扩展机制——它允许开发者在保留组件交互逻辑与视觉基准的前提下，向组件内部注入自定义内容或子组件。本章系统梳理三个高频组件（Button、Card、Dialog）的 Slot 定义、数据类型与使用规则，为后续实现章节打下结构化基础。

2.1 Slot 机制概述

在 Material 3 的组件模型中，Slot 是一个具名占位符，组件通过声明 Slot 列表向外界开放内容注入点。每个 Slot 通常绑定一组类型约束（如仅允许 Icon 或 Text 组件），并在组件内部按固定层级渲染。理解 Slot 的命名规范与嵌套关系，是正确使用组件扩展能力的前提。

2.2 Button 组件 Slot 列表

Button 系列组件（FilledButton、OutlinedButton、TextButton、ElevatedButton）共享同一套 Slot 接口。以下列出所有可用 Slot 及其类型说明：

以下示例展示在 Flutter 中使用 FilledButton 同时赋值 icon 与 label 的典型写法：

FilledButton(
  onPressed: () {},
  icon: const Icon(Icons.add),
  label: const Text('新建任务'),
)

2.3 Card 组件 Slot 列表

Material 3 的 Card 组件提供比 Button 更丰富的 Slot 结构，支持媒体、头部、内容和操作栏四段布局。所有 Slot 均为可选，组件在不赋值时自动隐藏对应区域。

一个包含头部、内容和操作栏的典型 Card 构造片段：

Card(
  header: ListTile(
    leading: CircleAvatar(child: Text('A')),
    title: Text('项目概览'),
    subtitle: Text('2025-02-21'),
  ),
  content: const Text('Material 3 Slot API 是组件扩展的核心通道。'),
  actions: Row(
    children: [
      TextButton(onPressed: () {}, label: const Text('详情')),
      FilledButton(onPressed: () {}, label: const Text('编辑')),
    ],
  ),
)

2.4 Dialog 组件 Slot 列表

Dialog 组件采用“图标—标题—内容—操作”的垂直层叠结构，Slot 定义清晰且类型严格。与 Button 和 Card 不同，Dialog 的 Slot 赋值直接影响对话框的语义层级（如 icon 赋值后组件自动启用顶部圆角与间距调整）。

以下是一个包含完整四层 Slot 的 Dialog 构造示例：

AlertDialog(
  icon: const Icon(Icons.warning_amber_rounded),
  headline: const Text('确认删除'),
  content: const Text('此操作将永久删除所选文件，不可恢复。'),
  actions: Row(
    children: [
      TextButton(onPressed: () {}, label: const Text('取消')),
      FilledButton(onPressed: () {}, label: const Text('删除')),
    ],
  ),
)

2.5 三个组件 Slot 结构对比

将上述三个组件的 Slot 列表按“层级深度”“必填数量”“类型丰富度”三个维度进行横向比较：

2.6 Slot 层级关系图

下方 SVG 图展示了 Button、Card、Dialog 三个组件的 Slot 内部渲染层级关系，帮助理解 Slot 在组件树中的实际位置：

2.7 常见误区与调试指引

根据社区反馈与项目实践，以下列出 Slot 使用中最容易踩中的三个误区：

1. 将必填 Slot 当作可选处理：Button 的 label 与 Dialog 的 headline 在编译期不会报错，但运行时会导致组件不渲染或布局坍缩。调试时优先检查必填 Slot 是否已赋值。
2. Slot 类型不匹配导致隐式转换失败：部分组件内部使用 is 判断 Slot 类型，传入 Container 而非 Icon 可能导致图标区空白。应严格遵循类型约束表。
3. 多个 Slot 同时赋值时的顺序依赖：Card 的 header 与 content 都依赖 media 的间距计算；若 media 为空但 header 存在，组件仍会保留媒体占位空间。建议按 media → header → content → actions → footer 顺序赋值。

2.8 稳定性与性能提示

Slot 机制本身不会引入额外性能开销——组件内部仅在构建时遍历 Slot 列表一次。但在以下场景中需要关注优化：

• 动态 Slot 切换：频繁替换 icon 或 content 时，建议使用 key 属性保持组件状态稳定，避免不必要的重建。
• 大体积 Slot 内容：Card 的 media Slot 传入高分辨率图片时，应在外部预先缩放至组件所需尺寸，防止组件内部多次 layout 计算。
• 嵌套 Slot 层级过深：Dialog 的 actions Slot 内部尽量避免再嵌套多层 Row/Column，以降低布局计算复杂度。

至此，Button、Card、Dialog 三个核心组件的 Slot 列表已完整呈现。下一维度将进入 Slot 的类型系统与类型安全约束详解，为自定义组件 Slot 设计提供类型理论基础。