React、Vue、Astro一次打通Cuelume框架集成与SPA路由换页音完整指南【免费下载链接】cuelumeCuelume is a curated sound palette, not an audio engine. It gives buttons, links, toggles, and completed actions clear feedback without asking developers to design sounds themselves. Add an attribute, call bind(), done.项目地址: https://gitcode.com/gh_mirrors/cu/cuelumeCuelume是一个策展式的网页交互音效库而非通用音频引擎用 Web Audio 实时合成 14 个语义化提示音覆盖按钮点击、下拉选择、弹窗开关、路由切换等场景全程无音频文件、零运行时依赖。只需给元素加一个data-cuelume-*属性再调用一次bind()界面就拥有清晰的听觉反馈。本文带你把 Cuelume 框架集成到 React、Vue、Astro 三大技术栈并实现 SPA 路由换页音。什么是 Cuelume一个不需要音频文件的交互音效库 Cuelume 的理念是策展式音效——你不需要自己设计声音只需要按场景选提示音14 个语义化提示音tap按钮点按、type打字、select选择、toggle开关、open/close开合、navigate路由切换以及success、error、warning、loading、ready、attention、count等状态反馈实时合成所有声音都基于玻璃、木质、气流、木琴等真实材质建模在浏览器里现场合成包体极小4 套材质主题default温暖、mech机械、bubble俏皮、press高级手感上下文感知打字速度、选择方向、开关状态都会微妙地影响音色但无需配置完整设计与提示音清单见 README.md所有公开 API 汇总在 src/index.ts。一分钟安装与第一个音效npm install cuelumenpm install cuelume⚠️ 注意Cuelume 是ESM-only见 package.json 的type: module请通过原生import或 ESM 兼容的打包器使用不支持require()。服务端导入SSR是安全的声音只在浏览器里播放。最小用法只需两步——加属性、绑一次button>import { bind } from cuelume; bind();bind()之所以在 SPA 里好用关键在它采用事件委托监听器挂在根节点上事件触发时才实时解析属性实现见 src/interactions/bind.ts。所以组件或路由整体替换 DOM 后声音依然正常重复调用是幂等的绝不会挂重复监听。React 集成 CuelumeuseEffect 里加一行就好React 里最省事——应用挂载后绑一次即可import { bind } from cuelume; useEffect(() { bind(); }, []);此后所有组件里的data-cuelume-*属性都会自动生效无需关心组件的卸载与重建React 18 StrictMode 的双挂载调用也不会出问题。Vue 路由换页音afterEach 里播 navigate 音效Vue 的接入方式一致在根组件onMounted里调用bind()onMounted(() bind());再配合 Vue Router 加换页音。navigate提示音是上升的柔和气声用direction参数可以区分前进与后退import { play } from cuelume; router.afterEach(() { play(navigate); // 前进上升的气声 }); // 后退时播下行版本 play(navigate, { direction: back });Astro 页面切换音效astro:page-load 触发路由换页音Astro 官方推荐启用 View Transitions客户端路由带页面过渡换页音恰好可以挂在astro:page-load事件上import { bind, play } from cuelume; bind(); document.addEventListener(astro:page-load, () play(navigate));这正是 README.md Frameworks 一节 给出的用法。得益于事件委托Astro 岛Islands如何再水合、如何被替换Cuelume 的绑定都不受影响。关于自动播放限制浏览器禁止在用户首次交互前播放声音所以路由换页音会在第一次点击之后的客户端导航才生效。这是浏览器层面的策略无法绕过设计时别把换页音当作核心体验。SPA 路由换页音最佳实践什么时候播、什么时候不播 Cuelume 的官方建议是按任务选声音而不是按声音选任务。常见场景对应关系节选自 README.md 的完整对照表场景提示音建议强调度路由变化 / 换页navigatesubtle返回上一页navigatedirection: back—轮播、画廊、分页navigatedirectionsubtle保存、提交、发送tapnormal保存成功、发布确认successsubtle/strong表单被拒、权限不足error—上传、构建开始loading—三条不吵人的铁律一个动作最多一个音——即使多个带标记的元素嵌套Cuelume 也保证每次事件只响一次高频事件不要播——hover、流式输出的每个 token、数字动画的每一位数字都不播动作结束时播一次即可用强调度区分轻重——subtle会剥掉装饰层变成安静的笔记本键盘声、毛毡木琴strong增加专属声层14 个提示音 × 3 档 42 种不同音色。声音三设置音量、静音与主题切换 ️Cuelume 不读写任何存储控制面板完全由你的应用来建。给用户提供声音开关是它的官方建议import { setEnabled, setVolume, setTheme } from cuelume; setVolume(0.7); // 全局音量0–1 setEnabled(false); // 静音后续 play 调用变为无操作 setTheme(mech); // 切换材质default / mech / bubble / press主题相当于给声音换材质mech是快门咔哒与棘轮定位声bubble是敲击、滴水与木塞声press像触碰一台精密硬件开关。四套主题音量已对齐切换不会忽大忽小。内置主题列表见 src/sounds/themes.ts实时合成引擎见 src/audio/engine.ts。常见集成坑位 ⚠️require()不可用纯 ESM 项目CommonJS 环境请走打包器或改import密码框不播打字音刻意设计避免尴尬快速打字自带节流最快 40ms 一个音且每次击键音高与力度都略有差异一句话不会听起来像同一个键无效名称安全降级传入不存在的提示音名时play()静默无操作不抛错bind()幂等重复调用安全后加入 DOM 的元素也自动生效。总结三步给 Web 应用装上听觉反馈npm install cuelume给按钮、下拉、弹窗加data-cuelume-*属性在应用根生命周期调用一次bind()ReactuseEffect/ VueonMounted/ Astro 入口直接调用在路由钩子afterEach/astro:page-load里调用play(navigate)补上 SPA 路由换页音并用setEnabled/setVolume给用户留一个声音开关。集成完成后你会发现好的音效库真的就是加几个属性这么简单。【免费下载链接】cuelumeCuelume is a curated sound palette, not an audio engine. It gives buttons, links, toggles, and completed actions clear feedback without asking developers to design sounds themselves. Add an attribute, call bind(), done.项目地址: https://gitcode.com/gh_mirrors/cu/cuelume创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考