如何让React吉他组件可交互：onChange与onPlay两大回调完整指南

如何让React吉他组件可交互：onChange与onPlay两大回调完整指南

【免费下载链接】react-guitarA beautiful and accessible guitar component for React. ⚛️ 🎸项目地址: https://gitcode.com/gh_mirrors/re/react-guitar

🎸react-guitar是一个为 React 打造的美观、可访问的吉他组件。本文是面向新手的onChange 与 onPlay 两大回调完整指南：讲清回调签名、触发时机与最小示例，帮你把一把"静态展示"的吉他快速变成可交互、能发声的吉他组件。

先搞懂核心数据：strings 数组

在配置回调之前，先理解吉他组件的"状态"——strings数组：

• 数组中每个数字代表对应琴弦按压的品格，如[0, 1, 2, 2, 0, -1]就是标准调弦下的A 小调和弦
• 0表示空弦，-1表示消音（不弹这根弦）
• 默认从第 0 品开始、共 22 品，可用frets={{ from: 0, amount: 22 }}调整

这两个回调的签名在 packages/react-guitar/src/index.tsx 中定义：

onChange 回调：让吉他从展示变可交互

触发时机

onChange会在用户点击品格、按方向键移动品位、或按 Enter 释放琴弦时触发，参数是更新后的完整strings数组。核心逻辑在 packages/react-guitar/src/index.tsx 的pressString中：每次按压都基于当前状态生成新数组并回调。

一个细节：组件内部会用disabled={!props.onChange}（见 packages/react-guitar/src/index.tsx）禁用交互——不传 onChange，吉他就是一张"静态图"。

最小可用示例：可编辑吉他

用useState保存当前按弦状态，把 setter 直接传给onChange即可（官方 Storybook 同款写法，见 storybook/index.stories.tsx）：

import { useState } from 'react' import Guitar from 'react-guitar' function EditableGuitar() { const [strings, setStrings] = useState([0, 0, 0, 0, 0, 0]) return <Guitar strings={strings} onChange={setStrings} /> }

现在用户点击品格、用方向键移动手指都会实时更新 UI——这就是受控组件的标准套路。

onPlay 回调：让吉他"开口说话"

触发方式

onPlay(string)的参数是弦的索引（从 0 开始），有两种官方触发方式：

• 🖱️鼠标悬停：给组件加上playOnHover属性，鼠标划过哪根弦就触发哪根弦（见 packages/react-guitar/src/index.tsx）
• ⌨️键盘弹奏：聚焦到某根弦后按p键触发（见 packages/react-guitar/src/index.tsx）

💡 注意：onPlay不依赖onChange。即使吉他只读（固定展示一个和弦），也可以单独挂上onPlay让它发声——Storybook 中的 "with fixed A minor and sound" 示例就是这么做的（见 storybook/index.stories.tsx）。

搭配 useSound 自动发音

手动实现发音太麻烦，项目提供了配套包react-guitar-sound的useSoundHook（源码见 packages/react-guitar-sound/src/index.ts），它接收当前按弦状态和调弦，返回play（弹单弦）与strum（扫弦）两个函数：

import Guitar from 'react-guitar' import useSound from 'react-guitar-sound' import { standard } from 'react-guitar-tunings' function GuitarWithSound() { const strings = [0, 1, 2, 2, 0, -1] // 固定的 A 小调 const { play } = useSound({ fretting: strings, tuning: standard }) return <Guitar strings={strings} onPlay={play} /> }

调弦数据来自react-guitar-tunings包（packages/react-guitar-tunings/src/index.ts），内置标准调弦、Open G、DADGAD 等常见配置。默认音色是尼龙民谣吉他，也可以用withSoundFont('electric_guitar_clean')换成电吉他，或用withSamples({ E2: 'E2.mp3', ... })换成自己的采样。

组合使用：一把完整可交互的发声吉他

把两个回调一起接上，再开启playOnHover，就是官网 Demo 的完整形态（参考 site/components/Demo.tsx）：

import { useState } from 'react' import Guitar from 'react-guitar' import useSound from 'react-guitar-sound' import { standard } from 'react-guitar-tunings' function InteractiveGuitar() { const [strings, setStrings] = useState([0, 0, 0, 0, 0, 0]) const { play } = useSound({ fretting: strings, tuning: standard }) return ( <Guitar strings={strings} onChange={setStrings} // 手指移动实时更新 onPlay={play} // 弹奏时发音 playOnHover // 鼠标悬停即发声 /> ) }

🎹 键盘党福利（官方 Demo 同款快捷键，见 site/hooks/sound.ts）：

想换风格试试内置主题包react-guitar-theme-dark和react-guitar-theme-coco：

常见问题快速解答

Q：只想要"能按"，不需要声音？只传onChange，strings状态自己更新即可。Q：想让某根弦默认为消音？strings数组对应位置写-1，如[3, -1, 0, 2, 0, -1]。Q：onPlay里能拿到当前按了几个品吗？不能，参数只有弦索引；当前品位请从自己维护的strings状态读取。Q：官方完整 Props 文档在哪看？见 packages/react-guitar/README.md 的 Props 表格。

小结

一句话记住两大回调的分工：

• onChange(strings)—— 负责"手"：把用户的按弦操作同步到你的状态，是吉他可交互的开关
• onPlay(string)—— 负责"声"：在弹奏事件发生时触发，配合useSound即可发音

按本文的最小示例把这两个回调接上，10 分钟就能做出一个可弹奏、可扫弦的 React 吉他组件。🎶

【免费下载链接】react-guitarA beautiful and accessible guitar component for React. ⚛️ 🎸项目地址: https://gitcode.com/gh_mirrors/re/react-guitar