feat(layout): 更新布局构建逻辑以优化宽度和高度计算

- 在 SNLayoutBuilder 中更新布局树构建方法，明确宽度和高度的计算顺序，确保自顶向下和自底向上的计算逻辑清晰。
- 优化 Measure、Page、Score 和 Section 节点的构建过程，增强节点间的宽度和高度动态调整能力。
- 更新文档注释，提升代码可读性，帮助开发者更好地理解布局计算的流程。

该变更提升了布局构建的灵活性和可维护性，确保元素在视觉上更加协调。

Author: Encaik

packages/simple-notation/src/layout/builder.ts

@@ -37,7 +37,11 @@ export class SNLayoutBuilder {
   }
 
   /**
-   * 构建布局树（自底向上构建）
+   * 构建布局树
+   *
+   * 宽度计算：自顶向下（Root → Page/Block → Line → Element）
+   * 高度计算：自底向上（Element → Line → Block → Page → Root）
+   *
    * @param dataTree - 数据树
    * @param containerSize - 容器尺寸（可选）
    * @returns 布局树根节点
@@ -46,13 +50,14 @@ export class SNLayoutBuilder {
     dataTree: SNParserRoot,
     containerSize?: { width: number; height: number },
   ): SNLayoutRoot {
-    // 先创建 Root 节点（不设置子节点）
+    // 先创建 Root 节点（宽度在 transformRoot 中已设置）
     const root = transformRoot(dataTree, this.layoutConfig, containerSize);
 
     // 获取页面配置
     const pageConfig = this.layoutConfig.getPage();
 
-    // 根据页面配置决定是否分页，自底向上构建子节点
+    // 根据页面配置决定是否分页，构建子节点
+    // 构建过程中会递归计算宽度（自顶向下）和高度（自底向上）
     if (pageConfig.enable) {
       buildPages(
         dataTree.children || [],
@@ -69,7 +74,7 @@ export class SNLayoutBuilder {
       );
     }
 
-    // 所有子节点构建完成后，计算 Root 的布局信息
+    // 所有子节点构建完成后，计算 Root 的高度和位置（自底向上）
     finalizeNodeLayout(root);
 
     return root;

packages/simple-notation/src/layout/builder/build-measures.ts

@@ -3,12 +3,15 @@ import type { SNLayoutLine } from '@layout/node';
 import { ScoreConfig } from '@manager/config';
 import { transformMeasure } from '../trans';
 import { buildMeasureElements } from './build-measure-elements';
-import { finalizeNodeLayout } from './finalize-node-layout';
 import { calculateNodeHeight } from './calculate-height';
 import { computeMeasureWidthByTicks } from './utils';
 
 /**
  * 构建 Measure 节点
+ *
+ * 宽度计算：自顶向下（父节点 Line → Measure Element）
+ * 高度计算：自底向上（Measure Element 内部元素 → Measure Element → Line）
+ *
  * @param measures - Measure 节点数组
  * @param parentNode - 父节点（Line）
  * @param shouldStretch - 是否拉伸小节以撑满整行（非最后一行时）
@@ -22,47 +25,48 @@ export function buildMeasures(
   availableWidth = 0,
   scoreConfig: ScoreConfig,
 ): void {
-  // 先计算所有小节的基础宽度
+  // ========== 宽度计算（自顶向下）==========
+  // 1. 先计算所有小节的基础宽度
   const baseWidths: number[] = [];
   for (const measure of measures) {
     const baseWidth = computeMeasureWidthByTicks(measure);
     baseWidths.push(baseWidth);
   }
 
-  // 计算总宽度
+  // 2. 计算总宽度
   const totalBaseWidth = baseWidths.reduce((sum, w) => sum + w, 0);
 
-  // 如果需要拉伸且总宽度小于可用宽度，计算拉伸比例
+  // 3. 如果需要拉伸且总宽度小于可用宽度，计算拉伸比例
   let stretchRatio = 1;
   if (shouldStretch && totalBaseWidth > 0 && availableWidth > totalBaseWidth) {
     stretchRatio = availableWidth / totalBaseWidth;
   }
 
-  // 构建每个小节
+  // 4. 构建每个小节并设置宽度
   for (let i = 0; i < measures.length; i++) {
     const measure = measures[i];
     // 使用 transformMeasure 转换 Measure 为 Element
     const element = transformMeasure(measure, scoreConfig, parentNode);
 
     if (!element) continue;
 
-    // 应用拉伸后的宽度
+    // 5. 设置 Measure Element 的宽度（基于父节点 Line 的可用宽度）
     const finalWidth = Math.round(baseWidths[i] * stretchRatio);
     if (element.layout) {
       element.layout.width = finalWidth;
     }
 
-    // 构建 Measure 内部的元素（Note/Rest/Lyric等）
+    // 6. 构建 Measure 内部的元素（Note/Rest/Lyric等）
+    // 内部元素的宽度会基于 Measure Element 的宽度按比例分配
     buildMeasureElements(
       (measure.children || []) as SNParserNode[],
       element,
       scoreConfig,
     );
-
-    // 子节点构建完成后，计算 Element 的布局信息
-    finalizeNodeLayout(element);
-
-    // 子节点添加后，立即更新父节点（Line）的高度
-    calculateNodeHeight(parentNode);
   }
+
+  // ========== 高度计算（自底向上）==========
+  // 7. 所有 Measure Element 构建完成后，计算父节点（Line）的高度
+  // （buildMeasureElements 中已经计算了内部元素的高度，并更新了 Measure Element 的高度）
+  calculateNodeHeight(parentNode);
 }

packages/simple-notation/src/layout/builder/build-pages.ts

@@ -7,8 +7,12 @@ import { finalizeNodeLayout } from './finalize-node-layout';
 
 /**
  * 构建页面节点（分页模式）
+ *
+ * 宽度计算：自顶向下（Page 宽度在 transformPage 中已设置）
+ * 高度计算：自底向上（子节点 → Page）
+ *
  * @param scores - Score 节点数组
- * @param parentNode - 父节点
+ * @param parentNode - 父节点（Root）
  * @param layoutConfig - 布局配置
  * @param scoreConfig - 乐谱配置
  */
@@ -20,12 +24,14 @@ export function buildPages(
 ): void {
   for (const score of scores) {
     // 使用 transformPage 转换 Score 为 Page
+    // Page 的宽度在 transformPage 中已经设置（基于配置）
     const page = transformPage(score, layoutConfig, parentNode);
 
     // 构建 Score 节点（在 Page 内部）
+    // buildScores 会递归计算所有子节点的宽度（自顶向下）和高度（自底向上）
     buildScores([score], page, layoutConfig, scoreConfig);
 
-    // 子节点构建完成后，计算 Page 的布局信息
+    // 所有子节点构建完成后，计算 Page 的高度和位置（自底向上）
     finalizeNodeLayout(page);
   }
 }

packages/simple-notation/src/layout/builder/build-scores.ts

@@ -9,6 +9,10 @@ import { calculateNodePosition } from './calculate-position';
 
 /**
  * 构建 Score 节点
+ *
+ * 宽度计算：自顶向下（父节点 → 子节点）
+ * 高度计算：自底向上（子节点 → 父节点）
+ *
  * @param scores - Score 节点数组
  * @param parentNode - 父节点（Root 或 Page）
  * @param layoutConfig - 布局配置
@@ -24,37 +28,45 @@ export function buildScores(
     // 使用 transformScore 转换 Score 为 Block
     const scoreBlock = transformScore(score, layoutConfig, parentNode);
 
-    // 先计算 Block 的宽度（这样子节点 Section Block 可以获取父节点宽度）
+    // ========== 宽度计算（自顶向下）==========
+    // 1. 先计算父节点（Score Block）的宽度
     calculateNodeWidth(scoreBlock);
 
-    // 计算所有子节点（包括元信息行）的宽度和高度
+    // 2. 计算元信息行的宽度（基于父节点宽度）
     if (scoreBlock.children) {
       for (const child of scoreBlock.children) {
         calculateNodeWidth(child);
-        calculateNodeHeight(child);
       }
     }
 
-    // 构建 Section 节点
+    // 3. 构建 Section 节点（在构建过程中会递归计算宽度）
     buildSections(score.children || [], scoreBlock, layoutConfig, scoreConfig);
 
-    // 子节点构建完成后，计算 Score Block 的高度和位置
+    // ========== 高度计算（自底向上）==========
+    // 4. 所有子节点构建完成后，计算子节点的高度
+    if (scoreBlock.children) {
+      for (const child of scoreBlock.children) {
+        calculateNodeHeight(child);
+        // 如果子节点有子节点，也需要计算高度
+        if (child.children) {
+          for (const grandChild of child.children) {
+            calculateNodeHeight(grandChild);
+          }
+        }
+      }
+    }
+
+    // 5. 最后计算父节点（Score Block）的高度（基于子节点高度）
     calculateNodeHeight(scoreBlock);
-    calculateNodePosition(scoreBlock);
 
-    // 计算所有子节点（包括元信息行和Section）的位置
+    // ========== 位置计算（自顶向下）==========
+    // 6. 计算所有节点的位置
+    calculateNodePosition(scoreBlock);
     if (scoreBlock.children) {
       for (const child of scoreBlock.children) {
-        // 先确保子节点的宽度和高度已计算
-        calculateNodeWidth(child);
-        calculateNodeHeight(child);
-        // 计算子节点的位置
         calculateNodePosition(child);
-        // 如果子节点是Line，需要递归计算其子节点（Element）的位置
         if (child.children) {
           for (const grandChild of child.children) {
-            calculateNodeWidth(grandChild);
-            calculateNodeHeight(grandChild);
             calculateNodePosition(grandChild);
           }
         }

packages/simple-notation/src/layout/builder/build-sections.ts

@@ -9,6 +9,10 @@ import { calculateNodePosition } from './calculate-position';
 
 /**
  * 构建 Section 节点
+ *
+ * 宽度计算：自顶向下（父节点 → 子节点）
+ * 高度计算：自底向上（子节点 → 父节点）
+ *
  * @param sections - Section 节点数组
  * @param parentNode - 父节点（Block）
  * @param layoutConfig - 布局配置
@@ -26,42 +30,50 @@ export function buildSections(
 
     if (!sectionBlock) continue;
 
-    // 先计算 Block 的宽度（这样子节点 VoiceGroup 可以获取父节点宽度）
+    // ========== 宽度计算（自顶向下）==========
+    // 1. 先计算父节点（Section Block）的宽度
     calculateNodeWidth(sectionBlock);
 
-    // 计算所有子节点（包括元信息行）的宽度和高度
+    // 2. 计算元信息行的宽度（基于父节点宽度）
     if (sectionBlock.children) {
       for (const child of sectionBlock.children) {
         calculateNodeWidth(child);
-        calculateNodeHeight(child);
       }
     }
 
-    // 构建 VoiceGroup（包含所有 Voice，并处理分行逻辑）
+    // 3. 构建 VoiceGroup（在构建过程中会递归计算宽度）
     buildVoiceGroups(
       (section.children || []) as SNParserNode[],
       sectionBlock,
       layoutConfig,
       scoreConfig,
     );
 
-    // 子节点构建完成后，计算 Section Block 的高度和位置
+    // ========== 高度计算（自底向上）==========
+    // 4. 所有子节点构建完成后，计算子节点的高度
+    if (sectionBlock.children) {
+      for (const child of sectionBlock.children) {
+        calculateNodeHeight(child);
+        // 如果子节点有子节点，也需要计算高度
+        if (child.children) {
+          for (const grandChild of child.children) {
+            calculateNodeHeight(grandChild);
+          }
+        }
+      }
+    }
+
+    // 5. 最后计算父节点（Section Block）的高度（基于子节点高度）
     calculateNodeHeight(sectionBlock);
-    calculateNodePosition(sectionBlock);
 
-    // 计算所有子节点（包括元信息行和VoiceGroup）的位置
+    // ========== 位置计算（自顶向下）==========
+    // 6. 计算所有节点的位置
+    calculateNodePosition(sectionBlock);
     if (sectionBlock.children) {
       for (const child of sectionBlock.children) {
-        // 先确保子节点的宽度和高度已计算
-        calculateNodeWidth(child);
-        calculateNodeHeight(child);
-        // 计算子节点的位置
         calculateNodePosition(child);
-        // 如果子节点是Line，需要递归计算其子节点（Element）的位置
         if (child.children) {
           for (const grandChild of child.children) {
-            calculateNodeWidth(grandChild);
-            calculateNodeHeight(grandChild);
             calculateNodePosition(grandChild);
           }
         }

packages/simple-notation/src/layout/builder/build-voice-groups.ts

@@ -33,10 +33,11 @@ export function buildVoiceGroups(
   );
   if (!voiceGroup) return;
 
-  // 计算 VoiceGroup 的宽度（撑满父级）
+  // ========== 宽度计算（自顶向下）==========
+  // 1. 先计算 VoiceGroup 的宽度（撑满父级）
   calculateNodeWidth(voiceGroup);
 
-  // 获取可用宽度（减去 padding）
+  // 2. 获取可用宽度（减去 padding），用于后续的小节宽度计算
   const availableWidth = voiceGroup.getAvailableWidth();
 
   // 收集所有 Voice 的小节信息
@@ -126,7 +127,10 @@ export function buildVoiceGroups(
       );
       if (!line) return;
 
+      // 3. 计算 Line 的宽度（基于父节点 VoiceGroup 的宽度）
       calculateNodeWidth(line);
+
+      // 4. 构建 Measure 节点（在构建过程中会计算 Measure 的宽度）
       if (lineMeasures.length > 0) {
         // 对于非最后一行，需要拉伸小节以撑满整行
         buildMeasures(
@@ -137,11 +141,33 @@ export function buildVoiceGroups(
           scoreConfig,
         );
       }
-      calculateNodePosition(line);
     });
   }
 
-  // 子节点构建完成后，计算 VoiceGroup 的高度和位置
+  // ========== 高度计算（自底向上）==========
+  // 5. 所有子节点（Line）构建完成后，计算子节点的高度
+  if (voiceGroup.children) {
+    for (const child of voiceGroup.children) {
+      calculateNodeHeight(child);
+      // Line 的子节点（Element）高度在 buildMeasures 中已计算
+    }
+  }
+
+  // 6. 最后计算父节点（VoiceGroup）的高度（基于子节点高度）
   calculateNodeHeight(voiceGroup);
+
+  // ========== 位置计算（自顶向下）==========
+  // 7. 计算所有节点的位置（递归计算所有子节点）
   calculateNodePosition(voiceGroup);
+  if (voiceGroup.children) {
+    for (const child of voiceGroup.children) {
+      calculateNodePosition(child);
+      // 递归计算 Line 的子节点（Measure Element）的位置
+      if (child.children) {
+        for (const grandChild of child.children) {
+          calculateNodePosition(grandChild);
+        }
+      }
+    }
+  }
 }

packages/simple-notation/src/layout/builder/calculate-width.ts

@@ -12,23 +12,15 @@ export function calculateNodeWidth(node: SNLayoutNode): void {
     case SNLayoutNodeType.ROOT: {
       // Root节点的宽度在渲染时由渲染器根据SVG实际宽度设置
       // 这里先设置为0，表示自适应
-      if (
-        node.layout.width === null ||
-        node.layout.width === 'auto' ||
-        typeof node.layout.width !== 'number'
-      ) {
+      if (node.layout.width === null || typeof node.layout.width !== 'number') {
         node.layout.width = 0;
       }
       break;
     }
 
     case SNLayoutNodeType.PAGE: {
       // Page宽度已在构建时设置，确保是数值类型
-      if (
-        node.layout.width === null ||
-        node.layout.width === 'auto' ||
-        typeof node.layout.width !== 'number'
-      ) {
+      if (node.layout.width === null || typeof node.layout.width !== 'number') {
         node.layout.width = 0;
       }
       break;