MotionButton 动效按钮

安装

import { TxMotionButton } from '@talex-touch/tuffex/motion-button'
import '@talex-touch/tuffex/base.css'
import '@talex-touch/tuffex/motion-button/style.css'

用法

全部交互与来源组合

演示可筛选 13 类交互，遍历 35 个图标组合，并切换网格、列表和图标矩阵。每项支持真实悬停、键盘聚焦、原生激活和装饰回放。选中状态与激活次数只保存在演示自己的本地状态里，复制项会真的写入剪贴板。

调用方的操作与内容

sourceId 只选择视觉参数，不执行操作，也不提供默认文案。悬停可以显示勾选图标，但不宣称业务成功。只有调用方设置的 selected 才启用 activeLabel。

<script setup lang="ts">
import { ref } from 'vue'
import { TxMotionButton } from '@talex-touch/tuffex/motion-button'

const copied = ref(false)
const busy = ref(false)
const error = ref('')
const marked = ref(false)
async function copyHash() {
  busy.value = true
  error.value = ''
  try {
    await navigator.clipboard.writeText('43c29ce9cdd16459e3eab4992381b8d35b38776a')
    copied.value = true
  }
  catch {
    error.value = '无法访问剪贴板'
  }
  finally {
    busy.value = false
  }
}
</script>

<template>
  <TxMotionButton source-id="4" label="复制提交" active-label="已复制"
    :selected="copied" :disabled="busy" @click="copyHash" />
  <p role="status">{{ error }}</p>
  <TxMotionButton variant="sparkle" label="标记本地条目" :selected="marked" @click="marked = !marked">
    <template #icon><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M4 6h16M4 12h16M4 18h16" /></svg></template>
    <template #active-icon><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5" /></svg></template>
    <template #default="{ selected }">{{ selected ? '已标记本地条目' : '标记本地条目' }}</template>
  </TxMotionButton>
</template>

应用负责真实业务操作和图标内容。内容插槽用于标签和装饰，需要独立操作的控件应放在按钮外。

焦点模糊链接

来源 35 渲染真实链接或按钮的分组。组件不创建占位地址，也不把多个交互元素包在一个按钮里。

<script setup lang="ts">
import { ref } from 'vue'
import { TxMotionButton } from '@talex-touch/tuffex/motion-button'
const lastLabel = ref('')
</script>

<template>
  <TxMotionButton source-id="35" label="项目链接" :items="[
    { label: '仓库', href: 'https://github.com/TalexDreamSoul/talex-touch' },
    { label: '文档', href: '/docs' },
    { label: '本地操作' },
  ]" @select="item => lastLabel = item.label" />
  <output>{{ lastLabel }}</output>
</template>

最佳实践

• 用 label、默认插槽或 ariaLabel 提供明确名称。图标矩阵中的控件也需要无障碍名称。
• 在 @click 或 @select 中执行真实操作。根据调用方状态设置 selected 和 activeLabel。悬停与回放不报告成功，也不改写业务状态。
• 导航用 href，表单提交用 type="submit"。按钮保留 Enter 和空格激活，链接保留 Enter 激活及组合键打开方式。
• 操作不可执行时设置 disabled。禁用链接会移除地址和 Tab 停靠，不依靠装饰遮罩拦截事件。
• 使用 sourceId 选择原始组合。内容不同时可以覆盖 variant、图标和颜色，也可以通过插槽提供自己的图标。
• 焦点模糊的 #item 插槽只放非交互标签。外层原生链接或按钮已经负责聚焦和激活。
• 设置 animated=false 保留内容和静态端点。减少动态效果、文档隐藏、控件离屏及 KeepAlive 失活都会暂停装饰动画。

API 参考

属性

id、name、value、form、download、aria-expanded 和 aria-controls 等原生属性透传到实际元素。焦点模糊模式的透传属性应用于分组。

事件

插槽

暴露方法

CSS 变量

类型

导出 MotionButtonProps、MotionButtonEmits、MotionButtonInstance、MotionButtonItem、MotionButtonSize、MotionButtonVariant、MotionButtonSourceId、MotionButtonCatalogEntry 和 TxMotionButtonInstance。MotionButton 可安装，TxMotionButton 是 Vue 组件。MOTION_BUTTON_VARIANTS、MOTION_BUTTON_SOURCE_IDS、MOTION_BUTTON_CATALOG 和 MOTION_BUTTON_PRESETS 提供真实枚举与来源元数据。

概述

• 显式 variant、图标、颜色和 holdDuration 优先于 sourceId。来源标签只用于归属信息，不自动变成应用文案。
• 悬停、聚焦、指针按下和回放驱动装饰。selected 保留目标图标并启用 activeLabel，始终由调用方提供。来源实现中仅凭悬停宣称“已复制”的行为不沿用。
• 内容和装饰层不拦指针事件。普通控件使用原生按钮/链接，焦点模糊的各条目也保留原生语义和可见键盘轮廓。禁用链接没有 href、Tab 停靠或激活事件。
• 原生表单提交/重置和链接导航不改成 JavaScript 键盘模拟。Enter/空格按下装饰遵循实际元素支持的按键。
• 共享活动边界停止 CSS 循环、待执行回放帧、保留/回放定时器、磁吸 RAF 和图标/文字变形。SSR 不读取浏览器 API。减少动态效果时保留可读内容与静态端点。
• 回放只处理视觉：先绘制静止姿态，再进入同一轨迹。磁吸回放只读一次控件尺寸，复用拉动和归零弹簧；焦点模糊回放强调首个启用条目。

技术实现

• 上游：Amicro，MIT，Copyright (c) 2026 SYED SUBHAN UDDIN。
• 行为来源：src/components/AnimatedButton.tsx:39～415、src/data/buttons.tsx:43～77 和 src/components/cards/FocusBlur.tsx:17～73。已阅读 registry 的 hover/magnetic-button.tsx 与 hover/glow-button.tsx，独立 registry 版本归入 Motion 交互组件族。
• 原始图标来自上游锁文件固定的 lucide-react 0.546.0。全部 46 个 SVG 图标保留原始节点和几何属性，仅移除 React key。ISC 与 Feather 派生部分的 MIT 声明完整保存在 icons.ts 的 @license 头中。
• TuffEx 落点：motion-button/src/TxMotionButton.vue、catalog.ts、icons.ts 和 MotionButtonGlyph.vue。图标变形复用 IconMorph，文字值变化复用 TextMorph，物理与生命周期复用已有共享弹簧和 useMotionActivity。活动边界变化时以实例 key 销毁旧变形控制器，不只改变减少动态效果标志。
• 下表保留全部 35 个实际组合。ID 改变图标、轨迹参数、填充和保留时间，不只是更换标签。固定标签属于来源元数据，可见文案由调用方提供。