Skip to content

Repository files navigation

浮光球 · Nest Orb

一个流畅、可配置、无障碍友好的 Vue 3 悬浮快捷菜单。

浮在界面上的一束小光,随手一碰,就能抵达常用功能。

A fluid, configurable and accessible floating shortcut orb for Vue 3.

浮光球 Nest Orb demo

CI MIT License 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>

Props

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 为关闭

其余文本可通过 menuLabelkickerhintariaLabelhideLabelrestoreLabel 覆盖。

Events

事件 参数 说明
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 猫头鹰表情状态变化

Exposed methods

组件 ref 暴露 open()close()hide()restore()setMood(mood, duration?)

交互设计

浮光球的动效遵循几条简单原则:

  1. pointerdown 立即反馈,不等待点击结束。
  2. 拖动使用 Pointer Events 与 Pointer Capture,内容和手指保持 1:1。
  3. 动画可以被下一次拖动随时打断,并从屏幕当前值继续。
  4. 松手速度会影响投射落点,悬浮球不会只按释放坐标机械贴边。
  5. 越界时采用渐进阻力,不会突然“撞墙”。
  6. prefers-reduced-motion 下直接落位,保留反馈但移除大幅移动。

隐私与依赖

  • 组件不发起网络请求。
  • 组件不读取消息、联系人、路由或业务状态。
  • 默认只把 { x, y } 保存到浏览器本地。
  • 运行时唯一 peer dependency 是 Vue。
  • Demo 使用原创中性数据,不包含私人前端的域名、账号、头像或聊天内容。

本地开发

npm install
npm run dev

完整检查:

npm run check

这会依次运行运动函数测试、组件库构建和 Demo 构建。

Project structure

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

Credits

浮光球(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.

License

MIT © 2026 youyue282-gif

About

浮光球 · A fluid, accessible floating shortcut orb for Vue 3.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages