动态应用栏 | Tuff Docs

概述

TxMotionDock 渲染调用方提供的真实项目。指针距离同时影响当前项目和临近项目，来源弹簧保持宽高同步。拖动先改变局部预览，释放后返回新的有序项目数组。组件不使用内置演示颜色替换调用方项目，也不修改传入数组。

应用栏采用水平工具栏语义。原生按钮和链接使用单项轮转焦点、本地化说明，并在真实排序后礼貌播报。暂停、减少动态效果或可见性失活时，尺寸动画停止，项目保持可读和可操作。

用法

受控项目和插槽

演示在每次用指针或键盘排序后显示当前顺序。它还包含选择、禁用项、真实图标和标签插槽，以及链接到说明段落的原生链接。

示例加载中...

指针和键盘

沿应用栏移动指针可放大临近项目。md 使用来源的 28 px 静止尺寸、44 px 峰值和 80 px 影响半径。主指针横向移动 4 px 后开始拖动，局部排序期间保持指针捕获，并在释放时返回最终顺序。Escape、指针取消或失去捕获会恢复调用方顺序，不触发排序事件。调用方从外部替换 items 时，旧拖动快照会取消。

左右方向键跳过禁用项循环移动焦点。Home/End 到达首个和末个可用项。Alt + 左右方向键将当前项移动一个位置；Alt + Home/End 移到两端。Enter 或空格激活当前项目。链接保持原生导航，空格提供与按钮一致的工具栏激活行为。拖动不会激活项目，也不会屏蔽后续键盘激活。

API 参考

属性

属性	类型	默认值	说明
`items`	`readonly MotionDockItem[]`	必填	调用方顺序和稳定的唯一 ID。需要应用 `update:items`，通常使用 `v-model:items`。
`activeId`	`string \| number`	—	选中项目标识，支持 `v-model:active-id`。选择不改变顺序。
`reorderable`	`boolean`	`true`	启用指针拖动和 Alt 按键排序；普通导航和激活仍然可用。
`disabled`	`boolean`	`false`	禁用全部激活、排序并停止尺寸动画。
`paused`	`boolean`	`false`	停止放大并恢复静止尺寸，不禁用项目操作。
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'md'`	静止尺寸分别为 20、24、28 和 36 px。峰值按来源的 44/28 比例缩放。
`itemSize`	`number`	由 `size` 决定	覆盖静止尺寸，最小 16 px；非有限值使用尺寸预设。
`magnifiedSize`	`number`	`itemSize × 44 / 28`	覆盖峰值，不会小于静止尺寸。
`distance`	`number`	`80`	指针影响半径，单位 px，最小 1 px。
`showLabels`	`boolean`	`false`	在应用栏下显示标签。可访问名称始终来自 `item.label`。
`labels`	`Partial<MotionDockLabels>`	见下表	本地化工具栏名称、键盘说明和排序播报。

项目和文案

MotionDockItem 包含 id: string | number、label: string，以及可选的 disabled: boolean 和 href: string。没有 href 时渲染原生按钮，有 href 时渲染原生链接。禁用链接不能导航。排序保留相同项目对象，包括调用方附加字段。

文案	默认值	用途
`dock`	`'Application dock'`	工具栏可访问名称。
`instructions`	英文方向键、Home/End、Alt 排序、Enter/空格和 Escape 说明	通过稳定的 Vue ID 关联到工具栏。
`reordered`	`'Moved {label} to position {position} of {total}.'`	礼貌排序播报。位置从 1 开始；事件索引从 0 开始。

事件

事件	载荷	说明
`update:items`	`MotionDockItem[]`	指针或键盘排序改变后返回的新数组，调用方需要应用。
`reorder`	`(items, detail)`	同一个实际有序数组，以及说明操作的 `MotionDockReorder`。
`update:activeId`	`string \| number`	原生激活请求选中项目。
`select`	`(item, index)`	实际选中项目和当前顺序索引，不伪造业务操作。

MotionDockReorder 为 { id, from, to, source: 'pointer' | 'keyboard' }。from 和 to 从 0 开始。顺序未变化的释放或取消拖动不触发排序。组件不会写入存储，也不会替按钮项目执行导航。

插槽

插槽	参数	说明
`item`	`{ item, index, active, dragging }`	替换原生项目控件中的内容。不要嵌套另一个交互控件。
`icon`	`{ item, index }`	图标画面。默认显示调用方标签的首字符；画面对辅助技术隐藏。
`label`	`{ item, index }`	`showLabels=true` 时显示的标签，不替换可访问名称。

无需命令式方法。items、activeId、reorderable 和 paused 驱动真实状态。

@talex-touch/tuffex/motion-dock 导出 TxMotionDock、可安装的 MotionDock、TxMotionDockInstance、MotionDockProps、MotionDockEmits、MotionDockItem、MotionDockId、MotionDockLabels、MotionDockReorder 和 MOTION_DOCK_DEFAULT_LABELS。

CSS 变量

变量	用途
`--tx-motion-dock-base-size`	由 `size` / `itemSize` 决定的静止尺寸。
`--tx-motion-dock-item-size`	共享弹簧驱动器管理的每项尺寸。

表面、线条、选中环和图标底色使用宿主 --tx-* token。悬停底色立即变化，不做颜色渐变过渡。

来源映射

变体	原始名称	固定版本来源	保留行为
`dock`	`Dock` / `DockItem`	Dock.tsx	临近指针距离放大，宽高同步；质量 0.1、刚度 220、阻尼 16；横向拖动排序。内置颜色数组改为调用方项目和插槽。

最佳实践

使用稳定且唯一的 ID，并应用 update:items。渲染固定数组而忽略返回顺序，会保留调用方原有顺序。
保留自己的项目对象和业务动作。按钮操作监听 select；真实链接提供 href。
提供本地化文案和非空项目名称。图标保持装饰内容，不嵌套第二个按钮。
固定应用或导航顺序使用 reorderable=false。禁用项仍在数据中，但不能激活、通过工具栏聚焦或发起拖动。
应用栏长度应适合宿主。可见标签可能比图标单元更宽；窄屏使用短名称或保持 showLabels=false。
不再建立悬停计时器或第二套弹簧。组件管理运动活跃状态，收敛或失活时取消唯一 RAF。

技术实现

组件使用原生指针捕获和 HTML 工具栏语义。布局只在输入事件中读取，不在弹簧帧中测量。现有 liquid springSteps 保留速度并推进来源弹簧。单个按需 RAF 写入每项尺寸变量，收敛后停止。useMotionActivity 提供 SSR 安全的可见性、隐藏页面、减少动态效果和 KeepAlive 控制。停用或卸载时释放 RAF、指针捕获和未完成拖动。Dock 不复制 observer 或全局监听器。