UI 视觉设计 / 系统课时

定义组件属性事件和插槽契约

定义组件属性事件和插槽契约

把 Figma 的尺寸、选中态、禁用态和图标变成前端可调用的接口,必须明确哪些值由父级提供、哪些交互通过事件回传。本课用一个可切换的筛选标签,把设计变体逐项映射到 Vue 3 属性、事件和插槽,并验证状态不会在两端失去同步。

学习目标

  • 列出组件的必填属性、可选属性、默认值、事件载荷和内容插槽。
  • 用受控组件明确状态归属,并验证禁用与点击行为。
  • 找出 Figma 中存在、但前端接口尚不能表达的变体。

把组件契约写到可验收的粒度

以 DsFilterChip 为例,标签的“是否选中”属于使用它的筛选页面,而非组件内部。先规定属性,再设计交互:

属性 类型 必填 默认值 约束
selected boolean 是 无 父级持有选中状态
size sm 或 md 否 'md' 只支持两档尺寸
disabled boolean 否 false 为真时禁止交互

自定义事件只声明 update:selected(next: boolean):用户点击且未禁用时,发送期望的新值;它不是“已完成修改”的通知。默认插槽放可见标签文案,prefix 具名插槽放可选的装饰图标。团队约定默认插槽不得为空,且不允许包含嵌套的交互控件,保证按钮具有明确的可访问名称。

受控边界是:组件不创建自己的 selected 状态副本,也不在点击时直接写入属性;父级可以接受事件、拒绝改变,或因筛选重置而主动覆盖选中值。

逐项核对 Figma 与前端的表达能力

Figma 组件属性 Vue 契约 核对点
Variant:Size=Small/Medium size='sm'/'md' 两端仅有两档
Variant:Selection=Off/On selected=false/true 由业务状态驱动
Variant:Interaction=Enabled/Disabled disabled 禁用时不发事件
Text:Label 默认插槽 文案可替换且不可为空
Boolean:IconVisible + Instance swap:LeadingIcon 可选 #prefix 图标由调用方提供

Figma 里的变体描述视觉结果,不代表运行时状态的所有权。例如设计稿中的 Selection=On 对应渲染结果,不能让组件点击后偷偷切换一个与父级不一致的内部布尔值。

如果设计稿另有 Size=Large 或尾部图标,而契约既没有 'lg' 取值,也没有 suffix 插槽,就要登记为不支持的设计变体:补接口、样式及测试,或从可交付组件集中撤除,不能把它默认为 'md'。

实现受控组件并观察事件回路

片段示例:在已有 Vue 3.3+、TypeScript 项目中创建 src/components/DsFilterChip.vue。这是完整单文件组件,需由页面导入才能显示。

vue
<script setup lang='ts'>
interface Props {
  selected: boolean
  size?: 'sm' | 'md'
  disabled?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  size: 'md',
  disabled: false
})
const emit = defineEmits<{
  'update:selected': [value: boolean]
}>()

function toggle() {
  // 只提出变更请求,真实状态仍由父级决定。
  if (props.disabled) return
  emit('update:selected', !props.selected)
}
</script>

<template>
  <button
    type='button'
    class='chip'
    :class='[size, { selected }]'
    :disabled='disabled'
    :aria-pressed='selected'
    @click='toggle'
  >
    <span v-if='$slots.prefix' aria-hidden='true'><slot name='prefix' /></span>
    <slot />
  </button>
</template>

<style scoped>
.chip { display: inline-flex; align-items: center; gap: 6px; border: 1px solid #8aa0b5; border-radius: 16px; background: white; color: #24405a; cursor: pointer; }
.chip.sm { padding: 4px 10px; font-size: 12px; }
.chip.md { padding: 8px 14px; font-size: 14px; }
.chip.selected { background: #dbeafe; border-color: #2563eb; }
.chip:focus-visible { outline: 2px solid #2563eb; outline-offset: 2px; }
.chip:disabled { opacity: .5; cursor: not-allowed; }
</style>

预期结果:组件仅根据传入的 selected 渲染背景与 aria-pressed;未传 prefix 时不出现空图标容器。单独放置此文件不会生成页面。

在 src/App.vue 中提供父级状态和插槽内容:

vue
<script setup lang='ts'>
import { ref } from 'vue'
import DsFilterChip from './components/DsFilterChip.vue'

// 筛选状态由页面拥有,组件通过 v-model 事件请求更新。
const favoritesOnly = ref(false)
const locked = ref(false)
</script>

<template>
  <DsFilterChip v-model:selected='favoritesOnly' size='md' :disabled='locked'>
    <template #prefix>★</template>
    只看收藏
  </DsFilterChip>
  <p>父级 selected:{{ favoritesOnly }}</p>
  <button type='button' @click='locked = !locked'>切换禁用</button>
</template>

预期结果:首次显示“父级 selected:false”;点击“只看收藏”后变为 true,标签显示浅蓝选中底色。点击“切换禁用”后再次点标签,父级值不再变化;再次解除禁用即可切回 false。

Figma 设计变体、组件契约与父级受控状态的双向数据流

用状态矩阵验收交付边界

验收时至少覆盖四组输入:selected=false, disabled=false 可触发 update:selected(true);selected=true, disabled=false 可触发 update:selected(false);disabled=true 时点击不触发更新;不提供 prefix 时文本仍正确显示且按钮可通过键盘聚焦。再检查 sm 与 md 的上下内边距分别为 4px、8px。

还要检查动态覆盖:组件已选中时,父页面直接将 favoritesOnly 设为 false,组件应立即取消选中,不需要额外事件。若此项失败,通常是子组件复制了属性并维护另一份本地状态。

交付给开发和设计评审的应是同一套属性取值、插槽用途与事件规则;发现 Figma 新增变体时,先更新契约和验收用例,再宣布该状态可用。

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

目录与阅读设置

阅读设置

17

记录一个想法

定义组件属性事件和插槽契约

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

登录哪都通