refactor(infographic): structure registration add composites

Aarebecca · Aarebecca · commit c6871302ff86 · 2025-10-31T15:52:46.000+08:00
diff --git a/packages/infographic/src/designs/structures/compare-hierarchy-left-right.tsx b/packages/infographic/src/designs/structures/compare-hierarchy-left-right.tsx
@@ -358,4 +358,5 @@ const DotLine = (props: DecorationProps) => {
 
 registerStructure('compare-hierarchy-left-right', {
   component: CompareHierarchyLeftRight,
+  composites: ['title', 'item'],
 });
diff --git a/packages/infographic/src/designs/structures/compare-hierarchy-row.tsx b/packages/infographic/src/designs/structures/compare-hierarchy-row.tsx
@@ -214,4 +214,7 @@ export const CompareHierarchyRow: ComponentType<CompareHierarchyRowProps> = (
   );
 };
 
-registerStructure('compare-hierarchy-row', { component: CompareHierarchyRow });
+registerStructure('compare-hierarchy-row', {
+  component: CompareHierarchyRow,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/compare-left-right.tsx b/packages/infographic/src/designs/structures/compare-left-right.tsx
@@ -150,4 +150,7 @@ export const CompareLeftRight: ComponentType<CompareLeftRightProps> = (
   );
 };
 
-registerStructure('compare-left-right', { component: CompareLeftRight });
+registerStructure('compare-left-right', {
+  component: CompareLeftRight,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/compare-mirror.tsx b/packages/infographic/src/designs/structures/compare-mirror.tsx
@@ -181,4 +181,7 @@ export const CompareMirror: ComponentType<CompareMirrorProps> = (props) => {
   );
 };
 
-registerStructure('compare-mirror', { component: CompareMirror });
+registerStructure('compare-mirror', {
+  component: CompareMirror,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/hierarchy-pyramid.tsx b/packages/infographic/src/designs/structures/hierarchy-pyramid.tsx
@@ -128,4 +128,7 @@ export const HierarchyPyramid: ComponentType<HierarchyPyramidProps> = (
   );
 };
 
-registerStructure('hierarchy-pyramid', { component: HierarchyPyramid });
+registerStructure('hierarchy-pyramid', {
+  component: HierarchyPyramid,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/hierarchy-tree.tsx b/packages/infographic/src/designs/structures/hierarchy-tree.tsx
@@ -285,4 +285,7 @@ export const HierarchyTree: ComponentType<HierarchyTreeProps> = (props) => {
   );
 };
 
-registerStructure('hierarchy-tree', { component: HierarchyTree });
+registerStructure('hierarchy-tree', {
+  component: HierarchyTree,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/list-column.tsx b/packages/infographic/src/designs/structures/list-column.tsx
@@ -83,4 +83,7 @@ export const ListColumn: ComponentType<ListColumnProps> = (props) => {
   );
 };
 
-registerStructure('list-column', { component: ListColumn });
+registerStructure('list-column', {
+  component: ListColumn,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/list-grid.tsx b/packages/infographic/src/designs/structures/list-grid.tsx
@@ -112,4 +112,7 @@ export const ListGrid: ComponentType<ListGridProps> = (props) => {
   );
 };
 
-registerStructure('list-grid', { component: ListGrid });
+registerStructure('list-grid', {
+  component: ListGrid,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/list-row.tsx b/packages/infographic/src/designs/structures/list-row.tsx
@@ -84,4 +84,7 @@ export const ListRow: ComponentType<ListRowProps> = (props) => {
   );
 };
 
-registerStructure('list-row', { component: ListRow });
+registerStructure('list-row', {
+  component: ListRow,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/list-sector.tsx b/packages/infographic/src/designs/structures/list-sector.tsx
@@ -287,4 +287,7 @@ export const ListSector: ComponentType<ListSectorProps> = (props) => {
   );
 };
 
-registerStructure('list-sector', { component: ListSector });
+registerStructure('list-sector', {
+  component: ListSector,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/list-waterfall.tsx b/packages/infographic/src/designs/structures/list-waterfall.tsx
@@ -134,4 +134,7 @@ export const ListWaterfall: ComponentType<ListWaterfallProps> = (props) => {
   );
 };
 
-registerStructure('list-waterfall', { component: ListWaterfall });
+registerStructure('list-waterfall', {
+  component: ListWaterfall,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/prompt.md b/packages/infographic/src/designs/structures/prompt.md
@@ -505,7 +505,10 @@ export const [StructureName]: ComponentType<[StructureName]Props> = (props) => {
   );
 };
 
-registerStructure('[structure-name]', { component: [StructureName] });
+registerStructure('[structure-name]', {
+  component: [StructureName],
+  composites: ['title', 'item'], // 根据实际使用的组件填写
+});
 ```
 
 **层级结构模板** (使用 Items 数组):
@@ -579,10 +582,72 @@ export const [StructureName]: ComponentType<[StructureName]Props> = (props) => {
   );
 };
 
-registerStructure('[structure-name]', { component: [StructureName] });
+registerStructure('[structure-name]', {
+  component: [StructureName],
+  composites: ['title', 'item'], // 根据实际使用的组件填写
+});
 ```
 
-### 5. 关键约束
+### 5. 组件声明 (composites)
+
+**composites 字段说明**：
+
+在调用 `registerStructure` 时，必须提供 `composites` 数组，用于声明该结构使用了哪些核心组件。这有助于系统了解结构的组成和依赖关系。
+
+**composites 的取值规则**：
+
+composites 数组中的值应该是小写字符串，包括以下几种：
+
+1. **'title'** - 当满足以下任一条件时包含：
+   - 使用了 `Title` prop 组件（来自 `props.Title`）
+   - 直接访问并渲染了 `data.title`（例如使用 `<Text>{title}</Text>` 或 `<Text>{data.title}</Text>`）
+   - 在代码中以任何方式将 title 数据渲染为 UI 元素
+
+2. **'item'** - 当满足以下任一条件时包含：
+   - 使用了 `Item` prop 组件（来自 `props.Item`）
+   - 使用了 `Items` prop 组件数组（来自 `props.Items`）
+   - 注意：即使使用的是 `Items`（复数），在 composites 中也应该填写 `'item'`（单数）
+
+3. **'illus'** - 当满足以下任一条件时包含：
+   - 使用了 `Illus` 组件（从 `../components` 导入）
+   - 直接访问并渲染了 `data.illus`（例如通过图片或 SVG 元素）
+   - 访问了 `data.illus.xxx` 并渲染为 UI
+
+**示例**：
+
+```typescript
+// 示例 1: 使用了 Title 和 Item props
+registerStructure('list-row', {
+  component: ListRow,
+  composites: ['title', 'item'],
+});
+
+// 示例 2: 直接在代码中渲染 title，使用 Item prop
+registerStructure('list-sector', {
+  component: ListSector,
+  composites: ['title', 'item'], // 虽然没有使用 Title prop，但渲染了 data.title
+});
+
+// 示例 3: 使用了 Items 数组（层级结构）
+registerStructure('hierarchy-tree', {
+  component: HierarchyTree,
+  composites: ['title', 'item'], // 注意是 'item' 不是 'items'
+});
+
+// 示例 4: 使用了 Title, Item 和 Illus
+registerStructure('some-structure', {
+  component: SomeStructure,
+  composites: ['title', 'item', 'illus'],
+});
+```
+
+**重要提示**：
+- composites 数组中的值必须是小写
+- 即使使用 `Items`（复数），也要填写 `'item'`（单数）
+- 如果结构直接渲染了某个数据字段（如 `data.title`），即使没有使用对应的 prop 组件，也应该在 composites 中声明
+- composites 数组不能为空，至少要包含 `['item']`
+
+### 6. 关键约束
 
 **严格遵守以下规则:**
 
@@ -678,13 +743,15 @@ registerStructure('[structure-name]', { component: [StructureName] });
    - 生成完整可运行的代码，包含所有必需的导入、类型定义和注册语句
    - JSX 导入指令必须在文件首行：`/** @jsxImportSource @antv/infographic-jsx */`
    - 只导入实际使用的组件和函数
+   - **必须在 registerStructure 调用中包含 composites 数组**，正确声明使用的组件
 
 2. **正确性**:
    - 确保 indexes 数组正确传递给所有需要的组件
    - 坐标计算准确，避免元素重叠或错位
    - 边界情况处理（如 items 为空数组时提供友好的空状态）
    - 使用 `getElementBounds` 获取准确的元素尺寸
    - Text 组件的文本通过 children 传递，不是 text 属性
+   - **composites 数组必须准确反映实际使用的组件**（参见"组件声明 (composites)"部分）
 
 3. **简洁性**:
    - 使用有意义但简洁的变量名
@@ -735,13 +802,14 @@ registerStructure('[structure-name]', { component: [StructureName] });
    - 导入所需的组件和函数
    - 定义 Props 接口
    - 实现组件逻辑
-   - 注册结构
+   - **注册结构（包含 composites 数组）**
 
 5. **验证输出**:
    - 检查代码完整性和正确性
    - 确认所有导入都正确
    - 确认 indexes 正确传递
    - 确认坐标计算无误
+   - **确认 composites 数组准确反映使用的组件**
 
 ## 参考示例
 
@@ -893,7 +961,10 @@ export const Example: ComponentType<ExampleProps> = (props) => {
   // 组件实现
 };
 
-registerStructure('example', { component: Example });
+registerStructure('example', {
+  component: Example,
+  composites: ['title', 'item'], // 根据实际使用的组件填写
+});
 ```
 
 ---
diff --git a/packages/infographic/src/designs/structures/quadrant.tsx b/packages/infographic/src/designs/structures/quadrant.tsx
@@ -248,4 +248,7 @@ function calculateQuadrantPositions(
   ];
 }
 
-registerStructure('quadrant', { component: Quadrant });
+registerStructure('quadrant', {
+  component: Quadrant,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/relation-circle.tsx b/packages/infographic/src/designs/structures/relation-circle.tsx
@@ -144,4 +144,7 @@ export const RelationCircle: ComponentType<RelationCircleProps> = (props) => {
   );
 };
 
-registerStructure('relation-circle', { component: RelationCircle });
+registerStructure('relation-circle', {
+  component: RelationCircle,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/relation-network.tsx b/packages/infographic/src/designs/structures/relation-network.tsx
@@ -185,4 +185,7 @@ export const RelationNetwork: ComponentType<RelationNetworkProps> = (props) => {
   );
 };
 
-registerStructure('relation-network', { component: RelationNetwork });
+registerStructure('relation-network', {
+  component: RelationNetwork,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/sequence-ascending-steps.tsx b/packages/infographic/src/designs/structures/sequence-ascending-steps.tsx
@@ -77,4 +77,5 @@ export const SequenceAscendingSteps: ComponentType<
 
 registerStructure('sequence-ascending-steps', {
   component: SequenceAscendingSteps,
+  composites: ['title', 'item'],
 });
diff --git a/packages/infographic/src/designs/structures/sequence-circle-arrows.tsx b/packages/infographic/src/designs/structures/sequence-circle-arrows.tsx
@@ -396,4 +396,5 @@ export const SequenceCircleArrows: ComponentType<SequenceCircleArrowsProps> = (
 
 registerStructure('sequence-circle-arrows', {
   component: SequenceCircleArrows,
+  composites: ['title', 'item'],
 });
diff --git a/packages/infographic/src/designs/structures/sequence-color-snake-steps.tsx b/packages/infographic/src/designs/structures/sequence-color-snake-steps.tsx
@@ -219,4 +219,5 @@ export const SequenceColorSnakeSteps: ComponentType<
 
 registerStructure('sequence-color-snake-steps', {
   component: SequenceColorSnakeSteps,
+  composites: ['title', 'item'],
 });
diff --git a/packages/infographic/src/designs/structures/sequence-horizontal-zigzag.tsx b/packages/infographic/src/designs/structures/sequence-horizontal-zigzag.tsx
@@ -309,4 +309,5 @@ export const SequenceHorizontalZigzag: ComponentType<
 
 registerStructure('sequence-horizontal-zigzag', {
   component: SequenceHorizontalZigzag,
+  composites: ['title', 'item'],
 });
diff --git a/packages/infographic/src/designs/structures/sequence-roadmap-vertical.tsx b/packages/infographic/src/designs/structures/sequence-roadmap-vertical.tsx
@@ -313,4 +313,5 @@ export const SequenceRoadmapVertical: ComponentType<
 
 registerStructure('sequence-roadmap-vertical', {
   component: SequenceRoadmapVertical,
+  composites: ['title', 'item'],
 });
diff --git a/packages/infographic/src/designs/structures/sequence-snake-steps.tsx b/packages/infographic/src/designs/structures/sequence-snake-steps.tsx
@@ -185,4 +185,7 @@ export const SequenceSnakeSteps: ComponentType<SequenceSnakeStepsProps> = (
   );
 };
 
-registerStructure('sequence-snake-steps', { component: SequenceSnakeSteps });
+registerStructure('sequence-snake-steps', {
+  component: SequenceSnakeSteps,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/sequence-steps.tsx b/packages/infographic/src/designs/structures/sequence-steps.tsx
@@ -116,4 +116,7 @@ export const SequenceSteps: ComponentType<SequenceStepsProps> = (props) => {
   );
 };
 
-registerStructure('sequence-steps', { component: SequenceSteps });
+registerStructure('sequence-steps', {
+  component: SequenceSteps,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/sequence-timeline.tsx b/packages/infographic/src/designs/structures/sequence-timeline.tsx
@@ -183,4 +183,7 @@ export const SequenceTimeline: ComponentType<SequenceTimelineProps> = (
   );
 };
 
-registerStructure('sequence-timeline', { component: SequenceTimeline });
+registerStructure('sequence-timeline', {
+  component: SequenceTimeline,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/sequence-zigzag-steps.tsx b/packages/infographic/src/designs/structures/sequence-zigzag-steps.tsx
@@ -275,4 +275,7 @@ export const SequenceZigzagSteps: ComponentType<SequenceZigzagStepsProps> = (
   );
 };
 
-registerStructure('sequence-zigzag-steps', { component: SequenceZigzagSteps });
+registerStructure('sequence-zigzag-steps', {
+  component: SequenceZigzagSteps,
+  composites: ['title', 'item'],
+});
diff --git a/packages/infographic/src/designs/structures/types.ts b/packages/infographic/src/designs/structures/types.ts
@@ -17,6 +17,7 @@ export interface BaseStructureProps {
 
 export interface Structure {
   component: ComponentType<BaseStructureProps>;
+  composites: string[];
 }
 
 export interface StructureOptions {
