feat(parser): 优化 ABC 解析器的时值计算逻辑

- 更新音符时值计算，确保根据 ABC 数字表示正确解析音符的时值。
- 增强注释，提供更清晰的说明，帮助理解音符时值的计算方式。
- 在 SVG 渲染中引入谱号信息的查找逻辑，确保音符渲染时考虑谱号的影响。

该变更提升了 ABC 解析器的准确性和可读性，增强了代码的可维护性。

Author: Encaik

packages/simple-notation/src/data/parser/abc-parser.ts

@@ -1226,10 +1226,11 @@ export class AbcParser extends BaseParser<SNAbcInput> {
         const durationStr = restStr.match(/^(\d+)/)?.[1];
         const dotCount = (restStr.match(/\./g) || []).length;
 
-        const abcDurationMultiplier = durationStr
-          ? parseInt(durationStr, 10)
-          : 1;
-        const noteValue = defaultNoteLength / abcDurationMultiplier;
+        // ABC 数字表示全音符的分母，例如 "z2" = 1/2（二分休止符），"z4" = 1/4（四分休止符）
+        // 如果没有数字，则使用默认 L: 值
+        const noteValue = durationStr
+          ? 1 / parseInt(durationStr, 10) // 例如 "2" -> 1/2 = 0.5（二分休止符）
+          : defaultNoteLength; // 例如 L:1/4 -> 0.25（四分休止符）
         const dottedNoteValue =
           dotCount > 0
             ? noteValue * (1 + 0.5 * (1 - Math.pow(0.5, dotCount)))
@@ -1290,7 +1291,7 @@ export class AbcParser extends BaseParser<SNAbcInput> {
       const octave = baseOctave + octaveOffset;
 
       // 3. 解析时值并转换为 duration（ticks）
-      // ABC 中数字表示相对于 L: 字段的倍数
+      // ABC 中数字表示全音符的分母，如果没有数字则使用默认 L: 值
       // 例如：如果 L: 是 1/4，"C4" = 1/4（四分音符），"C2" = 1/2（二分音符），"C" = 1/4（默认）
       let duration: number;
 
@@ -1301,13 +1302,11 @@ export class AbcParser extends BaseParser<SNAbcInput> {
         const defaultNoteLength = this.getDefaultNoteLength(trimmed);
         const noteLengthValue = defaultNoteLength; // 相对于全音符，例如 1/4 = 0.25
 
-        // ABC 数字表示倍数，如果没有数字则为 1（即默认 L: 值）
-        const abcDurationMultiplier = durationStr
-          ? parseInt(durationStr, 10)
-          : 1;
-
-        // 计算实际音符时值（相对于全音符）
-        const noteValue = noteLengthValue / abcDurationMultiplier;
+        // ABC 数字表示全音符的分母，例如 "G2" = 1/2（二分音符），"G4" = 1/4（四分音符）
+        // 如果没有数字，则使用默认 L: 值
+        const noteValue = durationStr
+          ? 1 / parseInt(durationStr, 10) // 例如 "2" -> 1/2 = 0.5（二分音符）
+          : noteLengthValue; // 例如 L:1/4 -> 0.25（四分音符）
 
         // 处理附点（每个点表示延长 1/2）
         const dotCount = (trimmed.match(/\./g) || []).length;

packages/simple-notation/src/render/renderer/staff-calculator.ts

@@ -0,0 +1,269 @@
+import type { SNPitch } from '@core/model/music';
+// import { SNAccidental } from '@core/model/music'; // 暂时未使用，将在后续版本中添加变音记号支持
+import type { SNVoiceMetaClef } from '@data/model/parser';
+
+/**
+ * 乐谱计算器
+ *
+ * 负责计算不同类型乐谱（五线谱、吉他谱、口琴谱等）中音符的位置和渲染属性
+ * 布局层不需要关心渲染层渲染为什么乐谱，只需要调用这个模块获取计算结果
+ */
+export class StaffCalculator {
+  /**
+   * 五线谱配置
+   */
+  static readonly STAFF_CONFIG = {
+    lineCount: 5, // 五线谱有5条线
+    lineGap: 7.5, // 线间距（像素）
+    staffHeight: 30, // 五线谱总高度（4个线间距）
+    staffTop: 6, // 五线谱顶部 y 坐标偏移
+  };
+
+  /**
+   * 不同谱号的参考音高（第一条线的音高）
+   * 五线谱从下往上编号，第一条线（最下面）是第0条线
+   */
+  static readonly CLEF_REFERENCE_NOTES: Record<
+    SNVoiceMetaClef,
+    { letter: string; octave: number }
+  > = {
+    treble: { letter: 'E', octave: 3 }, // 高音谱号：第一条线是 E3（ABC记谱法中大写字母基准八度为3）
+    bass: { letter: 'G', octave: 2 }, // 低音谱号：第一条线是 G2
+    alto: { letter: 'C', octave: 4 }, // 中音谱号：第一条线是 C4
+    tenor: { letter: 'C', octave: 4 }, // 次中音谱号：第一条线是 C4
+  };
+
+  /**
+   * 音名字母到半音数的映射（C=0, D=2, E=4, F=5, G=7, A=9, B=11）
+   */
+  private static readonly LETTER_TO_SEMITONE: Record<string, number> = {
+    C: 0,
+    D: 2,
+    E: 4,
+    F: 5,
+    G: 7,
+    A: 9,
+    B: 11,
+  };
+
+  /**
+   * 计算音符在五线谱上的 y 坐标
+   *
+   * @param pitch 音高信息
+   * @param clef 谱号（默认为高音谱号）
+   * @param staffTop 五线谱顶部 y 坐标（默认使用配置值）
+   * @param staffHeight 五线谱高度（默认使用配置值）
+   * @returns 音符符头中心的 y 坐标
+   */
+  static calculateNoteY(
+    pitch: SNPitch,
+    clef: SNVoiceMetaClef = 'treble',
+    staffTop: number = StaffCalculator.STAFF_CONFIG.staffTop,
+    staffHeight: number = StaffCalculator.STAFF_CONFIG.staffHeight,
+  ): number {
+    // 获取谱号的参考音高
+    const referenceNote = StaffCalculator.CLEF_REFERENCE_NOTES[clef];
+
+    // 注意：变音记号的处理暂时未实现，将在后续版本中添加
+
+    // 第一条线（最下面）的 y 坐标
+    const lineGap = staffHeight / 4; // 线间距
+    const firstLineY = staffTop + staffHeight; // 第一条线在五线谱底部
+
+    // 在五线谱中，每个线或间对应一个自然音阶的音符位置
+    // 五线谱的自然音阶排列：E-F-G-A-B-C-D-E-F-G-A-B-C-D...
+    // 从E到F是1个半音，从F到G是1个半音，从G到A是1个半音，等等
+    // 但在五线谱上，从一条线到下一个间是1个位置（0.5个线间距），从一条线到下一条线是2个位置（1个线间距）
+    //
+    // 对于ABC记谱法（E3作为第一条线）：
+    // - 第一条线：E3
+    // - 下加一线：C3（E3下方，但只向下0.5个线间距）
+    // - 第一间：F3（E3上方0.5个线间距）
+    // - 第二条线：G3（E3上方1个线间距）
+    //
+    // 因此，我们需要根据音符在自然音阶中的位置来计算，而不是直接使用MIDI半音差
+    //
+    // 计算音符在自然音阶中相对于参考音高的位置差
+    // 从E3开始，向上：E3->F3->G3->A3->B3->C4->D4->E4->F4->G4...
+    // 向下：E3->D3->C3->B2->A2->G2->F2->E2...
+    const refLetterIndex = ['C', 'D', 'E', 'F', 'G', 'A', 'B'].indexOf(
+      referenceNote.letter,
+    );
+    const noteLetterIndex = ['C', 'D', 'E', 'F', 'G', 'A', 'B'].indexOf(
+      pitch.letter.toUpperCase(),
+    );
+
+    // 计算八度差和字母差
+    const octaveDiff = pitch.octave - referenceNote.octave;
+    const letterDiff = noteLetterIndex - refLetterIndex;
+
+    // 计算在自然音阶中的位置差（从参考音高开始，向上或向下移动多少个自然音阶位置）
+    // 每个自然音阶位置对应半个线间距（0.5 * lineGap）
+    // 例如：从E3到G3，向上移动2个位置（E3->F3->G3），对应1个线间距
+    const positionDiff = octaveDiff * 7 + letterDiff;
+
+    // 计算y坐标：positionDiff为正数时，音符在参考音高上方，y坐标更小
+    const y = firstLineY - positionDiff * (lineGap / 2);
+
+    return y;
+  }
+
+  /**
+   * 判断音符是否需要符干
+   *
+   * @param duration 音符时值（ticks）
+   * @param ticksPerWhole 全音符的 ticks 数（默认 48）
+   * @returns 是否需要符干
+   */
+  static needsStem(duration: number, ticksPerWhole: number = 48): boolean {
+    // 全音符（duration = ticksPerWhole）不需要符干
+    // 二分音符及更短的需要符干
+    return duration < ticksPerWhole;
+  }
+
+  /**
+   * 判断音符是实心还是空心
+   *
+   * @param duration 音符时值（ticks）
+   * @param ticksPerWhole 全音符的 ticks 数（默认 48）
+   * @returns 是否为实心（true=实心，false=空心）
+   */
+  static isFilledNote(duration: number, ticksPerWhole: number = 48): boolean {
+    // 全音符和二分音符是空心的，四分音符及更短的是实心的
+    const halfNoteTicks = ticksPerWhole / 2;
+    return duration < halfNoteTicks;
+  }
+
+  /**
+   * 判断符干方向
+   *
+   * @param noteY 音符的 y 坐标
+   * @param clef 谱号（默认为高音谱号）
+   * @param staffTop 五线谱顶部 y 坐标（默认使用配置值）
+   * @param staffHeight 五线谱高度（默认使用配置值）
+   * @returns 符干方向（true=向上，false=向下）
+   */
+  static getStemDirection(
+    noteY: number,
+    _clef: SNVoiceMetaClef = 'treble',
+    staffTop: number = StaffCalculator.STAFF_CONFIG.staffTop,
+    staffHeight: number = StaffCalculator.STAFF_CONFIG.staffHeight,
+  ): boolean {
+    // 计算中间线（第三条线）的 y 坐标
+    const middleLineY = staffTop + staffHeight / 2; // 中间线在五线谱中间
+
+    // 音符在中间线及以上时，符干向下（stemUp = false）
+    // 音符在中间线以下时，符干向上（stemUp = true）
+    return noteY > middleLineY;
+  }
+
+  /**
+   * 计算需要绘制的辅助线（ledger lines）的 y 坐标
+   *
+   * @param noteY 音符的 y 坐标
+   * @param staffTop 五线谱顶部 y 坐标（默认使用配置值）
+   * @param staffHeight 五线谱高度（默认使用配置值）
+   * @returns 辅助线的 y 坐标数组（从下往上排序）
+   */
+  static getLedgerLines(
+    noteY: number,
+    staffTop: number = StaffCalculator.STAFF_CONFIG.staffTop,
+    staffHeight: number = StaffCalculator.STAFF_CONFIG.staffHeight,
+  ): number[] {
+    const lineGap = staffHeight / 4; // 线间距
+    const firstLineY = staffTop + staffHeight; // 第一条线（最下面）的 y 坐标
+    const lastLineY = staffTop; // 第五条线（最上面）的 y 坐标
+    const ledgerLines: number[] = [];
+    const tolerance = lineGap / 4; // 判断音符是否在线上的容差
+
+    // 检查音符符头是否在线上（而不是在线间）
+    // 音符在线上时，y坐标应该接近某条线的位置（允许一定误差）
+    const isOnLine = (y: number, lineY: number): boolean => {
+      return Math.abs(y - lineY) < tolerance;
+    };
+
+    // 检查音符是否低于第一线（需要下加线）
+    if (noteY > firstLineY) {
+      // 从第一条线下方开始，每个线间距绘制一条辅助线，直到音符符头所在的线
+      let currentLineY = firstLineY + lineGap;
+      // 继续向下绘制，直到音符符头所在的线或更下方
+      while (currentLineY <= noteY + tolerance) {
+        // 如果音符符头在这条线上，或者这条线在音符符头下方，都需要绘制
+        if (
+          isOnLine(noteY, currentLineY) ||
+          currentLineY <= noteY + tolerance
+        ) {
+          ledgerLines.push(currentLineY);
+        }
+        currentLineY += lineGap;
+      }
+    }
+
+    // 检查音符是否高于第五线（需要上加线）
+    if (noteY < lastLineY) {
+      // 从第五条线上方开始，每个线间距绘制一条辅助线，直到音符符头所在的线
+      let currentLineY = lastLineY - lineGap;
+      // 继续向上绘制，直到音符符头所在的线或更上方
+      while (currentLineY >= noteY - tolerance) {
+        // 如果音符符头在这条线上，或者这条线在音符符头上方，都需要绘制
+        if (
+          isOnLine(noteY, currentLineY) ||
+          currentLineY >= noteY - tolerance
+        ) {
+          ledgerLines.push(currentLineY);
+        }
+        currentLineY -= lineGap;
+      }
+    }
+
+    // 去重并按从下往上排序
+    return Array.from(new Set(ledgerLines)).sort((a, b) => a - b);
+  }
+
+  /**
+   * 获取音符的渲染属性
+   *
+   * @param pitch 音高信息
+   * @param duration 音符时值（ticks）
+   * @param clef 谱号（默认为高音谱号）
+   * @param ticksPerWhole 全音符的 ticks 数（默认 48）
+   * @param staffTop 五线谱顶部 y 坐标（默认使用配置值）
+   * @param staffHeight 五线谱高度（默认使用配置值）
+   * @returns 音符渲染属性
+   */
+  static getNoteRenderProps(
+    pitch: SNPitch,
+    duration: number,
+    clef: SNVoiceMetaClef = 'treble',
+    ticksPerWhole: number = 48,
+    staffTop: number = StaffCalculator.STAFF_CONFIG.staffTop,
+    staffHeight: number = StaffCalculator.STAFF_CONFIG.staffHeight,
+  ): {
+    y: number;
+    isFilled: boolean;
+    needsStem: boolean;
+    stemDirection: boolean; // true=向上，false=向下
+  } {
+    const y = StaffCalculator.calculateNoteY(
+      pitch,
+      clef,
+      staffTop,
+      staffHeight,
+    );
+    const isFilled = StaffCalculator.isFilledNote(duration, ticksPerWhole);
+    const needsStem = StaffCalculator.needsStem(duration, ticksPerWhole);
+    const stemDirection = StaffCalculator.getStemDirection(
+      y,
+      clef,
+      staffTop,
+      staffHeight,
+    );
+
+    return {
+      y,
+      isFilled,
+      needsStem,
+      stemDirection,
+    };
+  }
+}