QiuYe UI
视觉与动效

AdaptivePointer

参照 iPadOS 妙控板圆形指针的自适应指针:淡灰填充层悬停时变形为目标下方的圆角板并带阻尼偏移,图标随之轻微移动,正文上变为 I 形竖条,静止 2 秒后淡出;可选的深灰外环缩成小圆 1:1 标出真实指针位置。支持整页与局部作用域(含浮层)与主题令牌,触屏与减少动态效果时使用系统指针。

iPadOS指针光标cursor悬停视差弹簧变形

快速预览

查看 AdaptivePointer 组件的基本效果

把指针移到按钮或链接上

基本用法

使用 AdaptivePointer 组件的基础示例

导入组件

1import {
2 AdaptivePointer,
3 AdaptivePointerArea,
4 pointerTarget,
5} from "@/components/qiuye-ui/adaptive-pointer";
6import { Button } from "@/components/ui/button";
7import { BoldIcon } from "lucide-react";

使用组件

1// 整页:放在根布局里一次。默认单层指针、内容视差、正文 I 形竖条、静止 2 秒后隐藏
2<AdaptivePointer />
3
4// 局部:只在子树内生效(含它打开的菜单、对话框);ring 开启外环定位
5<AdaptivePointerArea ring className="rounded-xl border p-6">
6 <Button variant="ghost" size="icon" aria-label="加粗">
7 <BoldIcon />
8 </Button>
9 {/* 高度超过 96px 的卡片自动按 hover 处理:跟手的柔和圆,不变形 */}
10 <a href="/posts/1" className="block h-32 rounded-xl border p-4">
11 大卡片
12 </a>
13 {/* 显式指定效果(在客户端组件里调用) */}
14 <Button {...pointerTarget({ effect: "lift" })}>发布</Button>
15</AdaptivePointerArea>

组件演示

查看组件的各种使用方式和效果

交互实验台
在下方区域内移动鼠标或触控板:悬停可点击元素时,淡灰填充层变形为垫在元素下方的圆角板,并朝指针做有阻尼的偏移;深灰外环缩成小圆,始终标出真实指针位置。

工具栏

相邻按钮之间直接滑行,不回缩成圆;缝隙里外环立即恢复。

分段与标签

tablist 自动成组,板子贴合当前选项。

正文与链接

正文上是吸附到行的 I 形竖条,行尾空白处恢复圆形;折行的链接只贴合指针所在的那一段。

指针落在 链接 上时,填充层变成垫在下方的圆角板;遇到 一条刻意写得很长、会折到下一行的链接,板子只贴合当前那一段。

按钮与控件

不透明按钮外扩一圈光边;禁用控件保持大外环,诚实地表示不可点击。

大卡片

高或面积超过阈值的目标只显示跟手的柔和圆;叠在卡片上的按钮直接切换为圆角板。

表单与原生区

输入框用原生 I 形光标;原生区、语义光标与 iframe 交还系统指针。

data-pointer
= native
cursor-crosshair

浮层

局部作用域也覆盖 Portal 出去的菜单与对话框;菜单项自带高亮,改用柔和圆。

滚动列表

停住指针再滚动:外环每帧如实,板子与容器边缘求交、不会溢出。

经典单层 vs 双层
在两边的同一个按钮上缓慢移动:左边只知道「在哪个按钮上」,右边还能看见指针落在按钮的哪个位置。
经典单层(默认)一个文字链接
外环定位:外环 1:1 标出真实位置一个文字链接
主题与品牌色
颜色全部来自 CSS 变量:局部深色岛按区域重新求值,品牌色只需覆盖两个变量。
局部深色岛
品牌色