卡片展开

概述

TxCardSpread 使用调用方的卡片数据。每种布局保留独立坐标、层叠顺序和旋转支点。未控制展开状态时，悬停或键盘聚焦会展开卡片，按钮可以固定展开。v-model:expanded 直接控制布局。v-model 表示从 0 开始的当前项，与展开状态相互独立。

用法

变体	几何与来源默认值
`card-arc-5`	底部中心支点；角度 30°、间距 70px，垂直停点为 `[10,-2,-10,-2,10]`。
`card-arc-7`	七个独立弧线停点；角度 45°、间距 110px、偏移 30px。
`card-long-arc-5`	更宽、更平的弧线；角度 15°、间距 140px、偏移 20px。
`card-linear-spread`	仅水平位移；间距 90px。
`card-corner-fan`	左下角支点；默认旋转从 −10° 到 +30°。
`card-stamp-arc`	邮票虚线边缘；角度系数为 `[-1,-0.48,0,0.48,1]`，间距 180px、偏移 40px。
`card-cascade-stagger`	中心支点；每级向右 14px、向上 28px、旋转 6°。收起时保留 2px 错位。
`card-scatter-spread`	独立的发牌坐标和旋转角度，不替换成对称扇形。
`card-wheel-fan`	支点在卡片下方 110% 处；旋转范围为 ±36°，垂直停点为 `[-8,-22,-28,-22,-8]`。
`focus-blur`	保留额外 `FocusBlur` 行为：悬停或聚焦项清晰，其他项模糊、淡出，虚线括号按弹簧展开。

最佳实践

提供稳定的 id 和图片替代文本。title 同时作为选择控件的名称。
应用需要控制展开状态时使用 expanded。省略这个属性可启用悬停、聚焦和固定展开按钮。
angle、gap 和 yOffset 对应邮票来源的弧度、展开间距和偏移。其他布局在省略参数时保留各自默认值。
卡片插槽位于选择按钮内，请提供非交互内容。focus-blur 项有 href 时会渲染真实链接。
宽布局在小屏幕上支持横向滚动。size 同时缩放卡片与几何坐标。

API 参考

属性

属性	类型	默认值	说明
`items`	`MotionCardItem[]`	必填	调用方内容；空数组只渲染 `#empty`。
`modelValue`	`number`	内部 `0`	从 0 开始的当前项。
`variant`	`CardSpreadVariant`	`card-arc-5`	上表中的十个 ID；常量由 `CARD_SPREAD_VARIANTS` 导出。
`expanded`	`boolean`	未设置	控制展开；未设置时启用悬停、聚焦和固定展开。
`angle`	`number`	按变体	来源旋转角度，单位为度。
`gap`	`number`	按变体	水平展开间距，单位为像素。
`yOffset`	`number`	按变体	来源垂直偏移，单位为像素。
`hoverIntensity`	`number`	`1`	位移与旋转的倍数，不改变卡片缩放。
`duration`	`number`	`500`	过渡时长，单位为毫秒；时间曲线使用共享弹簧。
`colorful`	`boolean`	`false`	使用主题色浅色卡片；单项 `color` 优先。
`blurAmount`	`number`	`4`	`focus-blur` 非当前项的模糊像素值。
`opacityAmount`	`number`	`0.4`	`focus-blur` 非当前项的不透明度。
`showBrackets`	`boolean`	`true`	显示 `focus-blur` 聚焦括号。
`animated`	`boolean`	`true`	只控制动效；关闭后仍可选择和展开。
`disabled`	`boolean`	`false`	禁止选择、链接导航和固定展开。
`size`	`xs / sm / md / lg`	`md`	卡片与几何缩放。
`ariaLabel`	`string`	`Card spread`	分组的无障碍名称。
`expandLabel`	`string`	`Expand cards`	可本地化的展开按钮文字。
`collapseLabel`	`string`	`Collapse cards`	可本地化的固定展开或受控按钮文字。

MotionCardItem 字段为 id?: string | number、title?、description?、src?、alt?、date?、href? 和 color?: string。图片和文字来自调用方数据。color 接受 CSS 颜色或主题变量表达式。

事件

事件	参数	含义
`update:modelValue`	`index: number`	卡片、链接或键盘触发选择。
`update:expanded`	`expanded: boolean`	固定展开按钮或 Escape 请求。
`select`	`item: MotionCardItem, index: number`	当前调用方数据项。

插槽与实例方法

API	契约
`#item`	`{ item, index, selected, expanded }`；替换内容，不改变卡片几何。
`#empty`	`items.length === 0` 时的空状态内容。
`select(index)`	选择已有项；禁用时不执行。
`toggle()`	切换固定展开或受控展开；禁用时不执行。

左右方向键、Home 和 End 选择卡片，原生按钮支持 Enter 和 Space。Escape 释放固定展开，并发出受控收起请求。键盘聚焦展开卡片，并显示聚焦轮廓。

来源为 Amicro 的 CardArc5、CardArc7、CardLongArc5、CardLinearSpread、CardCornerFan、CardStampArc、CardCascadeStagger、CardScatterSpread、CardWheelFan 和 FocusBlur。固定提交为 43c29ce9cdd16459e3eab4992381b8d35b38776a，采用 MIT，Copyright (c) 2026 SYED SUBHAN UDDIN。

变换使用已有共享弹簧编译器。useMotionActivity 在离屏、文档隐藏、KeepAlive 失活和减少动态效果时移除动效，内容与操作仍可用。组件不引入 React/Motion 运行时，也不包含外部演示素材。

概述

用法

全部来源布局

最佳实践

API 参考

属性

事件

插槽与实例方法

技术实现