SpeedDial 悬浮动作按钮
悬浮主按钮 + 展开子动作列表,常用于「新建/分享」等快捷操作;aria-expanded 同步,点击外部/Esc 收起,无孤儿浮层。
演示中已加
style="position: static"避免固定定位影响页面布局;实际使用默认固定在右下角。子动作展开方向由direction控制。
展开方向
direction 支持 up(默认)/ down / left / right,首个子动作始终最靠近主按钮。
方向:up / down / left / right
级联动画
展开时子动作按序级联浮现(每项 transition-delay = index × 30ms),收起时同步消失。内建动效、无需配置;prefers-reduced-motion 下级联 delay 归零、过渡停用(一次性出现,对齐可访问性)。上方各 demo 展开即生效。
圆弧几何展开
geometry 控制子动作的分布方式:linear(默认,链式排布)/ circle(整圆,从正上开始 360°/N 均分)/ semi-circle(半圆,以 direction 为轴心 180° 张开)/ quarter-circle(四分之一圆 90°,起始象限随 direction:up=左上、down=右下、left=左下、right=右上)。radius 控制圆弧半径(px,默认 96,非法值回落 96)。
角度规则:circle 从正上方开始顺时针均分;semi-circle 从「主方向 − 90°」扫到「主方向 + 90°」(up=上半圆、down=下半圆、left=左半圆、right=右半圆);quarter-circle 为主方向起的 90° 弧(首项最靠近主按钮)。圆弧模式下子动作不再参与链式排布,--cascade-i 级联与 hide-label 气泡不受影响;prefers-reduced-motion 下圆弧转场直切(动作一次到位)。
circle:整圆从正上均分
semi-circle:半圆以 direction 为轴
quarter-circle:90° 象限随 direction(up=左上 / right=右上)
radius:调节圆弧半径(circle)
纯文字动作
icon 可省略,只显示 label;纯图标子动作请用 hide-label(见下节)。
纯文字 / 纯图标
icon-only 子动作(悬停显示文字)
hide-label: true 的子动作只渲染图标(圆形小钮),label 视觉隐藏;悬停 / 键盘聚焦时浮出文字气泡(纯 CSS 转场,无 JS 浮层)。气泡方向随展开方向自适应:up 展开在动作左侧、down 在右侧、left/right 在上方,定位于动作外侧、不遮挡相邻动作。hide-label 但未提供可渲染 icon 的动作自动回落为显示 label(dev 下 console.warn 告警一次)。方向键 roving 导航、oas-select 事件不受影响。
icon-only 子动作(悬停显示文字)
事件
点击主按钮展开/收起派发 oas-open(detail: { open, reason });点击子动作派发 oas-select(detail: { index, label })并自动收起。reason 标记展开/收起来源:toggle(点击主钮)/ outside(点击外部)/ escape(Esc)/ select(选择动作)/ hover(悬停触发)。
事件反馈
悬停触发
trigger="hover":鼠标悬停主按钮即展开,移出后 120ms 宽限期收起(宽限期内移入面板不收起);触屏设备自动回落 click 行为。
hover 触发
自定义主钮图标
主按钮默认显示「+」,通过默认插槽传入自定义图标(展开时仍旋转 45°)。
自定义主钮图标
键盘导航
展开后自动聚焦第一个子动作(trigger="hover" 悬停触发展开时不抢焦点);方向键在动作间移动(纵向展开用 ArrowUp/ArrowDown,横向展开用 ArrowLeft/ArrowRight,循环),Home/End 跳首尾,Esc 收起并回焦主按钮。
键盘导航
受控 open
open 属性受控:外部设置/移除即展开/收起,组件自身点击也会同步属性并派发 oas-open(点击外部 / Esc 仍会收起)。
受控展开
API
oas-speed-dial
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
actions | 子动作 JSON([{ label, icon?, 'hide-label'? }];hide-label: true 时子动作只渲染 icon 为圆形小钮,label 视觉隐藏、hover/键盘聚焦时浮出文字气泡;未提供可渲染 icon 时回落显示 label) | string | [] |
direction | 展开方向 | string | up |
geometry | 展开几何:linear(默认,链式排布)/ circle(整圆,从正上均分)/ semi-circle(半圆,以 direction 为轴)/ quarter-circle(四分之一圆,起始象限随 direction:up=左上、down=右下、left=左下、right=右上) | string | linear |
open | 展开态(受控) | boolean | — |
radius | 圆弧半径(px,默认 96;仅 geometry 非 linear 时生效,非法值回落 96) | — | — |
trigger | 触发方式:click(默认)| hover(悬停开、移出收起,120ms 离开宽限期;触屏自动回落 click) | string | click |
事件
| 事件 | 说明 |
|---|---|
oas-open | 展开/收起,detail: { open, reason };reason = toggle / outside / escape / select / hover(来源标记,向后兼容 open 字段) |
oas-select | 选择子动作,detail: { index, label },随后自动收起 |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 主钮自定义图标,有内容时替代默认 +(展开旋转 45° 保持) |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-tooltip-bg | var(--oas-color-text-primary) |
--oas-tooltip-color | var(--oas-color-bg) |
SpeedDialAction 字段:
| 字段 | 说明 | 类型 |
|---|---|---|
label | 动作文案 | string |
icon | 图标名(@oas-ui/icons 的 内置图标名) | string |
hide-label | true 时只渲染 icon(圆形小钮),label 视觉隐藏、hover/键盘聚焦时浮出文字气泡;未提供可渲染 icon 时回落显示 label | boolean |
行为:点击主按钮切换展开(aria-expanded 同步);trigger="hover" 可改为悬停触发(触屏回落 click);点击外部或 Esc 收起(Esc 后焦点回到主按钮);点击子动作收起并派发 oas-select;展开时自动聚焦第一个子动作(hover 触发展开除外),方向键/Home/End 在动作间导航;hide-label 子动作的 menuitem 以 aria-label 保留可访问名。默认定位 position: fixed; bottom/right,可覆盖。文档级监听仅在展开时挂载、断开连接清理,无孤儿浮层。