fretboard.js 入门

Fretboard.js 是一个使用 js 生成 svg 形式的指板图的工具，之后可能要做一些关于吉他的笔记，所以对它进行一些学习。要在浏览器中使用，直接下载 该 js 文件，在 html 中引用即可。

该库具体的使用细节应当参照官方文档，其中提供了很多供参考的 例子，这里只是做一些最简单的示例。

该库的基本使用方式为定义一个 figure 标签并给定 id，然后创建相应的 Fretboard 对象，在配置后调用 render 方法，比如下面的代码会定义一个空白的指板。

<figure id="empty-fretboard"></figure>
<script>
const { Fretboard } = globalThis.fretboard
const fretboard = new Fretboard({
  el: '#empty-fretboard',
  stringWidth: [1,1.5,2,3,4,5] // 为了好看！

});
fretboard.render()
</script>

效果如下：

下面列出了 Fretboard 的构造函数的全部配置，为了描述方便，下面的 instrument 仍旧称为吉他（但它也能够描述其它弦乐器），相较于官方文档，这里进行了一些重排序：

参数	类型	默认值	描述
el	string	‘#fretboard’	对应的标签，使用选择器语法
fretCount	number	15	展示的品数
crop	boolean	false	是否对指板图进行剪切，如果为 true，则剪掉左边空余的品位，其实就是说不从 1 品开始，从第一个有指位的品开始进行渲染，这是非常有用的
fretLeftPadding	number	0	似乎在 crop 为 true 时起作用，表示左边在最低把位的音前空开多少品
tuning	string[]	[“E2”, “A2”, “D3”, “G3”, “B3”, “E4”]	吉他的 调音
stringCount	number	6	吉他的弦数，必须和调音的数组的长度相等
dotText	{string: number, fret: number} => string	(dot) => ‘’	特定指位的文字，注意这里的 string 是属性名
stringWidth	number | [number]	1	弦的宽度，可以去传入一个数组，如 [1, 1.5, 2, 3, 4, 5]，设置好了挺美观的
fretWidth	string	1	品丝的宽度
showFretNumbers	string	true	是否展示品数
middleFretWidth	string	3	12 品品丝宽度
scaleFrets	string	true	如果为 true，则品格的宽度按对数增长（现实如此），否则按线性增长
stringColor	string	‘#666’	弦的颜色
fretColor	string	‘#666’	品丝的颜色
nutWidth	string	7	上弦枕的宽度
nutColor	string	‘#666’	上弦枕颜色
disabledOpacity	string	0.9	无效（disabled）的指位的不透明度
middleFretColor	string	‘#ff636c’	12 品品丝颜色
dotSize	string	20	指位的直径
dotStrokeColor	string	‘#555’	指位边框的颜色
dotStrokeWidth	string	2	指位边框宽度
dotTextSize	string	12	指位上的文字大小
dotFill	string	‘white’	指位填充颜色
fretNumbersColor	string	‘#00000099’	品数的颜色
topPadding	string	20	Top padding（相对于 SVG 容器）
bottomPadding	string	15	Bottom padding
leftPadding	string	20	Left padding
rightPadding	string	20	Right padding
height	string	150	SVG element height
width	string	960	SVG element width
fretNumbersHeight	string	40	Fret numbers container height
fretNumbersMargin	string	20	Fret number container top margin
font	string	‘Arial’	文字的字体
barresColor	string	‘#666’	未见效果，似乎是关于大横按的，描述错误了：Amount of empty frets to display before dots.

---

我们的目的当然不仅仅是去展示空白的指板，还得在上面放指位才能起参照作用。

放置指位使用 setDots 方法，它接受一个{string: number, fret: number}，比如下面的代码展示了一个开放 C 和弦，并在指位上显示其音高：

<figure id="c-chord"></figure>
<script>
const cChord = new Fretboard({
  el: '#c-chord',
  stringWidth: [1,1.5,2,3,4,5],
  fretCount: 3,
  dotText({string, fret}) {
    console.log(string)
    if (string === 5 && fret === 3) return 'C'
    if (string === 4 && fret === 2) return 'B'
    if (string === 2 && fret === 1) return 'C'
  }
});
cChord.setDots([{
    string: 5,
    fret: 3,
  },
  {
    string: 4,
    fret: 2,
  },
  {
    string: 2,
    fret: 1,
  }])
cChord.render()
</script>

也可以使用 style 方法，style 方法需要在 render 后被调用，可以用来规定特定情况的样式，它的签名如下，满足 filter 的指位会被影响。

style({
  filter = (): boolean => true, // filter 用于进行筛选，它不止可以传递指位，也可以传递
  text,
  fontSize, // 文字大小
  fontFill, // 文字颜色
  ...opts   // 各种其他配置，会被应用到指位上，这里的配置好像是来自 svg 的……
}: {
  filter?: (position: Position) => boolean | Record<string, string|number|boolean>;
  text?: (position: Position) => string;
  fontSize?: number;
  fontFill?: string;
  [key: string]: string | number | Function;
}): Fretboard

比如，我们展示一个开放 G 和弦，其中食指为黄色，中指为蓝色，无名指为红色：

<figure id="g-chord"></figure>
<script>
const gChord = new Fretboard({
  el: '#g-chord',
  stringWidth: [1,1.5,2,3,4,5],
  fretCount: 3
});
gChord.setDots([{
    string: 5,
    fret: 2,
  },
  {
    string: 6,
    fret: 3,
  },
  {
    string: 1,
    fret: 3,
  }])
gChord.render().style({
  filter: ({string, fret}) => string === 5 && fret === 2,
  fill: "yellow"
}).style({
  filter: ({string, fret}) => string === 6 && fret === 3,
  fill: "blue"
}).style({
  filter: ({string, fret}) => string === 1 && fret === 3,
  fill: "red"
})

显然，style 方法的自定义性是最高的。

---

关于和弦，各种调式的音阶，CAGED 和 TNPS 系统等，这里就先略过了，因为考虑到我当前没有使用其的需要，且官网示例已经足够丰富。下一步是运用这里学到的东西去描述一下蔡文展的指板系统中每个模块主音分别在 6，5，4，3 弦上的形状。