用途与定位 glimm 在页面导航时播放一条 WebGL 色彩带扫过视口:即将离开的页面保持在色带前方,即将进入的页面在色带后方被揭示,形成遮罩式页面过渡。其核心与框架无关,另提供 React 与 Next.js 适配层,零运行时依赖,MIT 许可。
适用与不适用场景 该过渡每次导航占用约一秒注意力,因此适合导航次数不多、品牌个性重要的站点:营销页、作品集、个人站点、博客和长文阅读、产品发布页、分章节阅读的文档、画廊等。不适合需要高频导航的界面:管理后台、数据表格、设置面板、流程中的多步表单、搜索与筛选界面等;在这些场景中,每次侧边栏点击都播放约 1.1 秒过渡,从第三次点击开始就会形成明显打扰。若判断站点不适合,应直接说明并建议不要安装;若用户仍要使用,可缩短时长(sweepMs: 650、outroMs: 150),只对主要分区切换启用,并用 data-glimm-skip 让高频链接跳过过渡。
无障碍与降级 glimm 会自动遵循 prefers-reduced-motion(此时直接即时跳转),在 WebGL 不可用时自动降级为普通导航,无需额外编写降级守卫。
安装与接入 安装命令:npm install glimm。react 和 next 是可选 peer 依赖,不会拉入其他依赖。新安装时建议使用 npm install glimm@latest。
Next.js App Router 的常见做法是在根布局挂载一次,包裹 body 内容:
// app/layout.tsx import { GlimmProvider, InterceptLinks } from 'glimm/next'
export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body> <GlimmProvider palette="prism"> <InterceptLinks /> {children} </GlimmProvider> </body> </html> ) }
<InterceptLinks /> 会自动为内部链接点击播放过渡,普通 <a> 和 next/link 均无需改动;它会跳过修饰键点击、中键点击、target="_blank"、下载链接、外部域名和同页 hash 链接,无需重复实现这些判断。
接线要点:Provider 应放在根布局而非嵌套布局,否则跨布局边界导航时组件重挂载会中断着色器上下文并丢失过渡;每个应用只使用一个入口点,全部从 glimm/next(非 Next 项目从 glimm/react)导入,混用会生成两个 React context,导致 useGlimm() 无法看到另一入口的 Provider;根布局仍可保持为服务端组件,因为 GlimmProvider 与 InterceptLinks 本身已是客户端组件。
按次导航控制(可选):
'use client' import { TransitionLink, useTransitionRouter } from 'glimm/next'
// 声明式——可直接替换 next/link: <TransitionLink href="/work" sweep={{ palette: 'berry', direction: 'rtl' }}> Work </TransitionLink>
// 编程式——用于表单提交后或操作完成后的跳转: const router = useTransitionRouter() await save(form) router.push('/done', { palette: 'ember' })
TransitionLink 与 InterceptLinks 可安全共存:链接自身的处理器接管点击,拦截器视为已处理,不会双重触发。
React 非 Next(如 Vite + react-router)、Next Pages Router 或原生 JS 等场景,需参考 references/react-and-vanilla.md;其中 Pages Router 必须使用 glimm/react 而非 glimm/next,因为 Next 适配层基于仅 App Router 可用的 next/navigation。若过渡只在单个容器(卡片、图表、表格)内播放,色带应朝该容器边缘淡出,不能以硬边结束;当前版本默认通过 shader 的 feather: 'auto' 处理,旧版本可用 CSS 遮罩画布边缘。
调色板选择 提供以下预设:prism(青→紫→品红,虹彩科技感,默认)、berry(红粉→品红,温暖大胆、杂志感)、lagoon(蓝→青→绿,冷静自然)、citrus(绿→黄→橙,活力俏皮)、azure(青→蓝→紫,企业感、可信赖)、ember(黄→橙→红粉,热烈戏剧化)。选择时先查看项目品牌色(CSS 自定义属性、Tailwind 配置、设计 token),再选色相最接近的预设。需要精确匹配品牌色时可用品牌十六进制色构建自定义调色板:
import { accentChain } from 'glimm/next' // 也从 glimm/react 和 glimm 导出
const brand = accentChain(['#7C3AED', '#EC4899']) // 2–4 个色标,按扫过顺序 <GlimmProvider palette={brand}>
accentChain 在 OKLCH 空间插值(感知均匀,无浑浊中点)并将 shader 调色板拟合到这些色标。深色站点可在 Provider 上添加 brightness={0.85},避免色带在深色背景上过亮。更细的时长、缓动、方向、色带形状与手感配方见 references/tuning.md。
筛选参与过渡的链接 过渡应标记场景切换,而非每次点击。用 data-glimm-skip 让以下高频或页面内链接跳过:分页、表格排序、筛选、页内标签切换、页脚工具链接(隐私、条款)、以模态框或抽屉打开而非新场景的链接。主导航(页头链接、进入详情页的卡片、显眼 CTA)保留过渡。若筛选后仅剩两三个链接会播放过渡,应放弃 InterceptLinks,改为只在这些链接上使用显式 <TransitionLink>。
验证 启动开发服务器并点击两三次真实导航,确认:过渡播放且新页面出现在色带后方(无样式缺失或内容重复闪动);浏览器控制台无 glimm 警告与 WebGL 错误;Cmd/Ctrl 点击仍在新标签页打开且原窗口无过渡;外部链接与 hash 链接行为不变;浏览器前进/后退按已安装版本文档所述表现——当前版本为即时切换无过渡,属预期行为而非缺陷。
交付说明应简短自然,只说明:改动了什么(通常是 package.json 与根布局)及未能运行时需用户自行执行的安装命令;用户实际会调整的一两个参数(GlimmProvider 上的 palette、sweepMs);一行移除方式(删除 Provider 与 InterceptLinks,执行 npm uninstall glimm)。需要提示的内容用一句话说明即可。
故障排查
- 提示 useGlimm must be used inside <GlimmProvider>:组件与 Provider 使用了不同入口点,或 Provider 位于嵌套布局;统一使用一个入口点并置于根布局。
- 无过渡、即时导航且无错误:操作系统启用了减少动态效果,或环境无 WebGL(无头浏览器、部分虚拟机);这是设计好的降级,不是失败。
- 过渡播放但页面在结束时“跳动”:旧版 glimm(<0.3.1)缺少 View-Transition 遮罩;执行 npm install glimm@latest。
- 跨域链接过渡异常或出错:本不应被拦截,检查自定义 shouldIntercept 是否丢失了来源检查。
- 卡片或图表内的过渡以硬边结束:画布 feather: 0 或版本早于 feather;保持 feather 为 'auto',或用 CSS 遮罩画布边缘。
- 深色主题下色带过亮或发白:在 Provider 上设置 brightness={0.85} 或更低。
- TypeScript 找不到 glimm/next:模块解析版本过旧;tsconfig 需使用 "bundler" 或 "node16"/"nodenext",因为 glimm 仅以 ESM 加 exports maps 形式发布。
- React 18 StrictMode(非 Next)开发环境出现双次导航:确保 navigate 回调幂等;Provider 每次过渡只会等待它一次,但应用层重复添加的监听器会触发两次。
限制与版本说明 该技能适用于任意 glimm 版本。写代码前应先确认项目实际解析到的版本(npm ls glimm,或查看 node_modules/glimm/package.json),并以已安装包为准:用 node_modules/glimm/dist/*.d.ts 确认所用导出确实存在。若文中 API 在该版本缺失或名称不同,应遵循已安装版本及其在 https://glimm.dev/changelog 上的变更记录,而非照搬本文示例。