一个流畅、可配置、无障碍友好的 Vue 3 悬浮快捷菜单。
浮在界面上的一束小光,随手一碰,就能抵达常用功能。
A fluid, configurable and accessible floating shortcut orb for Vue 3.
- 点击:展开半透明快捷菜单
- 双击:触发默认动作,例如回到聊天
- 长按或直接拖动:跟手移动
- 松手:根据释放速度投射位置并贴边
- 拖到底部:临时隐藏为一个小把手
- 菜单展开时:悬浮球自动隐藏,减少视觉干扰
- 键盘与辅助功能:焦点样式、Escape 关闭、ARIA 标签
- 系统偏好:支持减少动态、减少透明度与增强对比度
- 可选猫头鹰桌宠:左右贴边、输入框磁吸、眨眼、开心、惊讶与休眠状态
组件不绑定路由、图标库或状态管理。选择菜单项时只发出事件,由你的应用决定下一步。
仓库启用 GitHub Pages 后,可在以下地址体验:
https://youyue282-gif.github.io/nest-orb/
发布到 npm 后:
npm install nest-orb-vue直接从 GitHub 安装:
npm install github:youyue282-gif/nest-orb<template>
<NestOrb
:items="shortcuts"
active-id="home"
:bottom-inset="92"
menu-label="快捷入口"
hint="双击悬浮球,直接回到聊天"
@select="handleShortcut"
@default="goToChat"
/>
</template>
<script setup>
import { NestOrb } from "nest-orb-vue";
import "nest-orb-vue/style.css";
const shortcuts = [
{ id: "call", label: "通话", icon: "☎" },
{ id: "tasks", label: "清单", icon: "✓" },
{ id: "journal", label: "日记", icon: "□" },
{ id: "home", label: "主页", icon: "⌂" },
{ id: "chat", label: "聊天", icon: "…" },
];
function handleShortcut(item) {
console.log("selected", item.id);
}
function goToChat() {
console.log("default action");
}
</script>桌宠是可选外观,默认仍是原来的浮光球。传入一个 CSS 选择器后,猫头鹰可以磁吸到对应元素上方;没有目标或目标离开页面时仍会回到屏幕左右边缘。
<template>
<div class="message-composer">输入消息……</div>
<NestOrb
ref="pet"
appearance="owl"
perch-selector=".message-composer"
:size="58"
:margin="7"
@dock-change="handleDock"
@mood-change="handleMood"
/>
</template>
<script setup>
import { ref } from "vue";
import { NestOrb } from "nest-orb-vue";
import "nest-orb-vue/style.css";
const pet = ref();
function celebrate() {
pet.value?.setMood("happy", 900);
}
function handleDock(dock) {
console.log(dock); // left | right | perch
}
function handleMood(mood) {
console.log(mood); // awake | wink | happy | sleep | surprise
}
</script>浮光球没有捆绑图标库。通过 item-icon 插槽即可使用任意 SVG 或图标组件:
<NestOrb :items="shortcuts">
<template #item-icon="{ item }">
<MyIcon :name="item.icon" />
</template>
</NestOrb><NestOrb :items="shortcuts">
<template #orb="{ dragging }">
<img
class="my-avatar"
src="/avatar.webp"
:class="{ 'is-dragging': dragging }"
alt=""
/>
</template>
</NestOrb>| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
items |
Array |
[] |
{ id, label, icon?, description?, disabled? } |
activeId |
String |
"" |
当前高亮入口 |
bottomInset |
Number |
24 |
底部需要避让的高度 |
maxWidth |
Number |
920 |
悬浮球允许活动的最大内容宽度 |
size |
Number |
56 |
悬浮球尺寸 |
margin |
Number |
16 |
屏幕边缘间距 |
hideZoneHeight |
Number |
84 |
底部隐藏触发区域 |
doubleTapEnabled |
Boolean |
true |
是否启用双击默认动作 |
doubleTapMs |
Number |
280 |
双击识别窗口 |
longPressMs |
Number |
360 |
长按反馈时间 |
persist |
Boolean |
true |
是否在 localStorage 保存位置 |
storageKey |
String |
nest-orb.position.v1 |
位置存储键 |
haptics |
Boolean |
true |
浏览器支持时使用轻触震动 |
accent |
String |
#5878a6 |
强调色 |
surface |
String |
半透明浅色 | 球与菜单材质色 |
ink |
String |
#172237 |
前景文字色 |
appearance |
"orb" | "owl" |
"orb" |
使用经典浮光球或猫头鹰桌宠外观 |
perchSelector |
String |
"" |
可供猫头鹰磁吸停靠的元素选择器 |
perchSnapRadius |
Number |
106 |
输入框磁吸半径 |
idleSleepMs |
Number |
45000 |
无操作后进入睡眠状态的等待时间,0 为关闭 |
其余文本可通过 menuLabel、kicker、hint、ariaLabel、hideLabel 和 restoreLabel 覆盖。
| 事件 | 参数 | 说明 |
|---|---|---|
select |
item |
选择快捷入口 |
default |
— | 双击触发默认动作 |
position-change |
{ x, y } |
位置落定 |
hidden-change |
boolean |
隐藏状态变化 |
menu-change |
boolean |
菜单开关变化 |
dock-change |
left | right | perch |
猫头鹰停靠位置变化 |
mood-change |
awake | wink | happy | sleep | surprise |
猫头鹰表情状态变化 |
组件 ref 暴露 open()、close()、hide()、restore() 和 setMood(mood, duration?)。
浮光球的动效遵循几条简单原则:
pointerdown立即反馈,不等待点击结束。- 拖动使用 Pointer Events 与 Pointer Capture,内容和手指保持 1:1。
- 动画可以被下一次拖动随时打断,并从屏幕当前值继续。
- 松手速度会影响投射落点,悬浮球不会只按释放坐标机械贴边。
- 越界时采用渐进阻力,不会突然“撞墙”。
prefers-reduced-motion下直接落位,保留反馈但移除大幅移动。
- 组件不发起网络请求。
- 组件不读取消息、联系人、路由或业务状态。
- 默认只把
{ x, y }保存到浏览器本地。 - 运行时唯一 peer dependency 是 Vue。
- Demo 使用原创中性数据,不包含私人前端的域名、账号、头像或聊天内容。
npm install
npm run dev完整检查:
npm run check这会依次运行运动函数测试、组件库构建和 Demo 构建。
src/
NestOrb.vue # Vue component
assets/ # bundled owl poses
orb-motion.js # framework-independent gesture physics
index.js # public exports
demo/ # interactive, neutral demo
test/ # Node.js unit tests
浮光球(Nest Orb)由 youyue282-gif 设计并开源。交互研究参考了移动端浮动快捷控件与公开的人机界面设计原则;项目不隶属于或受 Apple Inc. 认可,也不包含 Apple 的代码、商标或素材。
Designed and open-sourced by youyue282-gif. Inspired by common floating shortcut patterns and public interface-design principles. This project is not affiliated with or endorsed by Apple Inc.
MIT © 2026 youyue282-gif
