Infographic Structure Creator

Infographic Structure Creator

Overview

Generate complete Structure component code for the infographic framework, following the project's component rules, layout constraints, and registration requirements.

Workflow

1. Read references/structure-prompt.md for the full framework rules, allowed components, and output requirements. 2. Clarify minimal requirements if missing: structure category, layout direction, hierarchy depth, and whether add/remove buttons are needed. 3. Choose Item vs Items, compute layout from getElementBounds, and plan decor elements under ItemsGroup. 4. Produce a full TypeScript file: imports, Props extends BaseStructureProps, component implementation, and registerStructure with accurate composites. 5. Self-check against the constraints in the reference (no unlisted components, no SVG cx/cy/r, correct indexes, empty-state handling).

Notes

• Prefer scanning src/designs/structures for similar existing structures to match local patterns when appropriate.
• Keep output concise; avoid React-only features (keys, hooks).

信息图结构组件生成规范

本文件用于指导生成符合框架规范的 Structure 组件代码。

目录

• 框架核心概念
• 结构分类体系
• 技术规范
• 代码生成要求
• 生成流程
• 参考示例
• 输出格式

框架核心概念

信息图框架由三个核心部分组成：

• 结构 (Structure): 负责整体布局和数据项的组织方式
• 标题 (Title): 可选的标题组件
• 数据项 (Item/Items): 单个或多个信息单元的展示组件

结构是入口组件，通过组合 Title 和 Item/Items，配合布局逻辑和交互按钮，形成完整的信息图。对于层级结构，可以使用 Items 数组传递多个组件（如根节点组件和子节点组件）。

结构分类体系

根据信息组织特点，结构分为以下类型：

1. *列表结构 (list-\)**: 信息项并列排布，无明显方向性或层级关系

• 横向列表、纵向列表、网格列表、瀑布流等

2. *对比结构 (compare-\)**: 明确的二元或多元对比布局

• 左右对比、上下对比、多项对比、镜像对比等

3. *顺序结构 (sequence-\)**: 具有明确方向性和顺序性的信息流

• 时间轴、步骤流程、阶梯式、S型流程等

4. *层级结构 (hierarchy-\)**: 树状、嵌套或明显的主次关系布局

• 树形、金字塔、放射状、嵌套圈等

5. *关系结构 (relation-\)**: 展示元素间的连接、依赖或相互作用关系

• 网络图、矩阵、循环图、维恩图等

6. *地理结构 (geo-\)**: 基于地理空间或物理位置的信息组织

• 地图标注、区域分布、路线图等

7. *统计图 (chart-\)**: 以图表形式展示定量数据关系

• 柱状图、饼图、折线图、雷达图等

技术规范

1. 类型定义

export interface BaseStructureProps {
  Title?: ComponentType<Pick<TitleProps, 'title' | 'desc'>>;
  Item?: ComponentType<
    Omit<BaseItemProps, 'themeColors'> &
      Partial<Pick<BaseItemProps, 'themeColors'>>
  >;
  Items?: ComponentType<Omit<BaseItemProps, 'themeColors'>>[];
  data: Data;
  options: ParsedInfographicOptions;
}

export interface Data {
  title?: string;
  desc?: string;
  items: ItemDatum[];
  illus?: Record<string, string | ResourceConfig>;
  [key: string]: any;
}

export interface ItemDatum {
  icon?: string | ResourceConfig;
  label?: string;
  desc?: string;
  value?: number;
  illus?: string | ResourceConfig;
  children?: ItemDatum[];
  [key: string]: any;
}

export interface BaseItemProps {
  x?: number;
  y?: number;
  id?: string;
  indexes: number[];
  data: Data;
  datum: Data['items'][number];
  themeColors?: ThemeColors;
  positionH?: 'normal' | 'center' | 'flipped';
  positionV?: 'normal' | 'middle' | 'flipped';
  width?: number;
  height?: number;
  [key: string]: any;
}

重要说明:

• 对于简单结构，使用 Item 属性传递单个组件
• 对于层级结构（如树形、金字塔等），使用 Items 数组传递多个组件，不同层级可以使用不同的组件样式
• options 包含主题配置、调色板等信息，可通过工具函数访问
• themeColors 在 BaseItemProps 中是可选的，部分组件会自定义传入

2. 可用组件清单

必须从以下组件中选择,不得使用未列出的组件:

原子组件 (从 ../../jsx 导入)

所有原子组件统一使用 x, y, width, height 属性来定义位置和尺寸，不使用 SVG 原生属性如 cx/cy/r 等。

• Defs: 定义渐变、滤镜等 SVG 定义

  <Defs>{/* 渐变、滤镜等定义 */}</Defs>

• Ellipse: 椭圆图形

  <Ellipse x={0} y={0} width={100} height={60} fill="blue" />
  // 注意:
  // 1. x/y 为左上角位置，非中心点
  // 2. 使用 width/height,不使用 rx/ry
  // 3. 绘制圆形时，width 和 height 相等

• Group: 分组容器

  <Group x={10} y={10}>
    {children}
  </Group>

• Path: 路径图形

  <Path
    d="M 0 0 L 100 100"
    stroke="black"
    strokeWidth={2}
    width={100}
    height={100}
  />
  // width/height 为 d 的预估尺寸

• Rect: 矩形图形

  <Rect x={0} y={0} width={100} height={50} fill="red" />

• Text: 文本元素(支持换行)

  <Text
    x={0}
    y={0}
    width={100}
    height={50}
    fontSize={14}
    fontWeight="normal" // 或 'bold'
    alignHorizontal="center" // 'left' | 'center' | 'right'
    alignVertical="middle" // 'top' | 'middle' | 'bottom'
    fill="#000000"
  >
    Text Content
  </Text>
  // 注意: 文本内容作为 children 传入，不是 text 属性

• Polygon: 多边形

  <Polygon
    points={[
      { x: 0, y: 0 },
      { x: 100, y: 0 },
      { x: 50, y: 100 },
    ]}
    fill="green"
  />
  // 注意: points 是对象数组 {x, y}[],不是字符串

封装组件 (从 ../components 导入)

• BtnAdd: 添加按钮,需要 indexes 属性

  <BtnAdd indexes={[0]} x={10} y={20} />

• BtnRemove: 删除按钮,需要 indexes 属性

  <BtnRemove indexes={[0]} x={10} y={20} />

• BtnsGroup: 按钮组容器

  <BtnsGroup>{btnElements}</BtnsGroup>

• ShapesGroup

和 Group 属性和用法完全一致，但内部图形可以被进行风格化渲染

<ShapesGroup>
  <Rect width={100} height={100} />
  <Rect x={100} width={100} height={100} />
  <Rect x={200} width={100} height={100} />
</ShapesGroup>

• ItemsGroup: 数据项组容器

  <ItemsGroup>{itemElements}</ItemsGroup>

• Illus: 插图组件(会被替换为图片或 SVG)

  <Illus x={0} y={0} width={200} height={150} />

• Title: 默认标题组件

  <Title title="标题" desc="描述" alignHorizontal="center" />

• ItemLabel: 数据项标签

  <ItemLabel indexes={[0]} x={0} y={0}>
    标签
  </ItemLabel>

• ItemDesc: 数据项描述

  <ItemDesc indexes={[0]} x={0} y={0}>
    描述
  </ItemDesc>

• ItemIcon: 数据项图标

  <ItemIcon indexes={[0]} x={0} y={0} size={40} />

• ItemValue: 数据项数值

  <ItemValue indexes={[0]} value={100} x={0} y={0} />

• ItemIconCircle: 圆形图标组件

  <ItemIconCircle indexes={[0]} x={0} y={0} size={50} fill="#000000" />

装饰组件 (从 ../decorations 导入)

• SimpleArrow: 简单箭头装饰

  <SimpleArrow
    x={0}
    y={0}
    width={25}
    height={25}
    colorPrimary="#000000"
    rotation={0} // 可选，旋转角度：0, 90, 180, 270
  />

• Triangle: 三角形装饰

  <Triangle
    x={0}
    y={0}
    width={10}
    height={8}
    rotation={0}
    colorPrimary="#000000"
  />

定义组件 (从 ../defs 导入)

• LinearGradient: 线性渐变定义

  <Defs>
    <LinearGradient
      id="my-gradient"
      startColor="#ff0000"
      stopColor="#0000ff"
      direction="left-right" // 'left-right' | 'right-left' | 'top-bottom' | 'bottom-top'
    />
  </Defs>
  <Rect fill="url(#my-gradient)" />

原生 SVG 元素在 Defs 中的使用: 在 <Defs> 标签内可以使用原生 SVG 元素：

<Defs>
  <linearGradient
    id="gradient-id"
    x1="0%"
    y1="0%"
    x2="100%"
    y2="100%"
    gradientUnits="userSpaceOnUse"
  >
    <stop offset="0%" stopColor="#ff0000" />
    <stop offset="100%" stopColor="#0000ff" />
  </linearGradient>
</Defs>

布局组件 (从 ../layouts 导入)

• FlexLayout: 弹性盒子布局

  <FlexLayout
    flexDirection="row" // 'row' | 'column' | 'row-reverse' | 'column-reverse'
    justifyContent="center" // 'flex-start' | 'flex-end' | 'center' | 'space-between'
    alignItems="center" // 'flex-start' | 'flex-end' | 'center'
    alignContent="center" // 'flex-start' | 'flex-end' | 'center' | 'space-between'
    flexWrap="wrap" // 'wrap' | 'nowrap'
    gap={20}
  >
    {children}
  </FlexLayout>

风格化渲染

风格化渲染是指将图形在渲染阶段转换为风格化图形，例如手绘风格。

通过以下方式标识的图形可以被进行风格化渲染（由渲染器实现）

1. 添加 data-element-type="shape" 属性

<Rect data-element-type="shape" width="100" height="100" />

2. 使用 ShapesGroup 包裹

<ShapesGroup>
  <Rect width="100" height="100" />
  <Rect x="100" width="100" height="100" />
  <Rect x="200" width="100" height="100" />
</ShapesGroup>

风格化渲染只支持图形元素（如 Path、Ellipse、Rect、Polygon 等），不支持文本元素和分组

工具函数

布局计算函数 (从 ../../jsx 导入):

• getElementBounds: 获取元素边界信息

  const bounds = getElementBounds(<Rect width={100} height={50} />);
  // 返回: { x: number, y: number, width: number, height: number }

主题与颜色函数 (从 ../utils 导入):

• getPaletteColor: 获取调色板中指定索引的颜色

  const color = getPaletteColor(options, [index]); // 返回颜色字符串

• getPaletteColors: 获取完整调色板颜色数组

  const palette = getPaletteColors(options); // 返回颜色数组

• getColorPrimary: 获取主题色

  const colorPrimary = getColorPrimary(options); // 返回主题色字符串

• getThemeColors: 获取主题配置

  const themeColors = getThemeColors(options.themeConfig);
  // 或自定义配置
  const themeColors = getThemeColors(
    {
      colorPrimary: '#FF356A',
      colorBg: '#ffffff',
    },
    options,
  );
  // 返回包含 colorText, colorPrimaryBg 等的主题对象

数据处理函数 (从 ../../utils 导入):

• getDatumByIndexes: 根据索引获取数据项

  const datum = getDatumByIndexes(items, [0, 1]); // 获取嵌套数据

组件选择函数 (从 ../utils 导入):

• getItemComponent: 获取指定层级的 Item 组件（用于 Items 数组）

  const ItemComponent = getItemComponent(Items, level);
  // Items 为组件数组，level 为层级索引
  // 如果 level 超出数组长度，返回最后一个组件

3. 按需导入

import type { ComponentType, JSXElement } from '../../jsx';
import {
  getElementBounds,
  Defs,
  Ellipse,
  Group,
  Path,
  Polygon,
  Rect,
  Text,
} from '../../jsx';
import {
  BtnAdd,
  BtnRemove,
  BtnsGroup,
  Illus,
  ItemDesc,
  ItemIcon,
  ItemIconCircle,
  ItemLabel,
  ItemsGroup,
  ItemValue,
  Title,
} from '../components';
import { LinearGradient } from '../defs';
import { SimpleArrow, Triangle } from '../decorations';
import { FlexLayout } from '../layouts';
import {
  getColorPrimary,
  getPaletteColor,
  getPaletteColors,
  getThemeColors,
  getItemComponent,
} from '../utils';
import { getDatumByIndexes } from '../../utils';
import { registerStructure } from './registry';
import type { BaseStructureProps } from './types';

注意事项:

• 只导入实际使用的组件和函数
• 对于层级结构，记得导入 BaseItemProps 类型（如果需要）
• 装饰组件和定义组件按需导入

支持的第三方库：

• d3: 用于力导向布局、层次布局等复杂布局计算
• lodash-es: 通用工具函数
• tinycolor2: 颜色处理

可以按实际需求引入其他库

4. 组件结构模板

简单结构模板 (使用 Item):

export interface [StructureName]Props extends BaseStructureProps {
  gap?: number;
  // 其他自定义参数
}

export const [StructureName]: ComponentType<[StructureName]Props> = (props) => {
  const { Title, Item, data, gap = 20, options } = props;
  const { title, desc, items = [] } = data;

  // 1. 处理标题
  const titleContent = Title ? <Title title={title} desc={desc} /> : null;

  // 2. 获取元素尺寸
  const btnBounds = getElementBounds(<BtnAdd indexes={[0]} />);
  const itemBounds = getElementBounds(
    <Item indexes={[0]} data={data} datum={items[0]} />
  );

  // 3. 准备元素数组
  const btnElements: JSXElement[] = [];
  const itemElements: JSXElement[] = [];
  const decorElements: JSXElement[] = []; // 装饰元素（如箭头、连线等）

  // 4. 遍历数据项生成元素
  items.forEach((item, index) => {
    const indexes = [index];

    // 计算位置并添加 Item
    itemElements.push(
      <Item
        indexes={indexes}
        datum={item}
        data={data}
        x={/* 计算 x */}
        y={/* 计算 y */}
      />
    );

    // 添加删除按钮
    btnElements.push(
      <BtnRemove
        indexes={indexes}
        x={/* 计算 x */}
        y={/* 计算 y */}
      />
    );

    // 添加插入按钮
    btnElements.push(
      <BtnAdd
        indexes={indexes}
        x={/* 计算 x */}
        y={/* 计算 y */}
      />
    );
  });

  // 5. 添加末尾的添加按钮
  if (items.length > 0) {
    btnElements.push(
      <BtnAdd
        indexes={[items.length]}
        x={/* 计算 x */}
        y={/* 计算 y */}
      />
    );
  }

  // 6. 返回布局
  return (
    <FlexLayout
      id="infographic-container"
      flexDirection="column"
      justifyContent="center"
      alignItems="center"
    >
      {titleContent}
      <Group>
        <Group>{decorElements}</Group>
        <ItemsGroup>{itemElements}</ItemsGroup>
        <BtnsGroup>{btnElements}</BtnsGroup>
      </Group>
    </FlexLayout>
  );
};

registerStructure('[structure-name]', {
  component: [StructureName],
  composites: ['title', 'item'], // 根据实际使用的组件填写
});

层级结构模板 (使用 Items 数组):

export interface [StructureName]Props extends BaseStructureProps {
  gap?: number;
  // 其他自定义参数
}

export const [StructureName]: ComponentType<[StructureName]Props> = (props) => {
  const { Title, Items, data, gap = 20, options } = props;
  const [RootItem, ChildItem] = Items; // 解构获取不同层级的组件
  const { title, desc, items = [] } = data;

  const titleContent = Title ? <Title title={title} desc={desc} /> : null;

  const btnElements: JSXElement[] = [];
  const itemElements: JSXElement[] = [];

  // 获取根节点和子节点的尺寸
  const rootItemBounds = getElementBounds(
    <RootItem indexes={[0]} data={data} datum={items[0]} />
  );
  const childItemBounds = getElementBounds(
    <ChildItem indexes={[0, 0]} data={data} datum={items[0]?.children?.[0] || {}} />
  );

  // 遍历根节点
  items.forEach((rootItem, rootIndex) => {
    const { children = [] } = rootItem;

    // 渲染根节点
    itemElements.push(
      <RootItem
        indexes={[rootIndex]}
        datum={rootItem}
        data={data}
        x={/* 计算 x */}
        y={/* 计算 y */}
      />
    );

    // 遍历子节点
    children.forEach((child, childIndex) => {
      itemElements.push(
        <ChildItem
          indexes={[rootIndex, childIndex]}
          datum={child}
          data={data}
          x={/* 计算 x */}
          y={/* 计算 y */}
        />
      );
    });
  });

  return (
    <FlexLayout
      id="infographic-container"
      flexDirection="column"
      justifyContent="center"
      alignItems="center"
    >
      {titleContent}
      <Group>
        <ItemsGroup>{itemElements}</ItemsGroup>
        <BtnsGroup>{btnElements}</BtnsGroup>
      </Group>
    </FlexLayout>
  );
};

registerStructure('[structure-name]', {
  component: [StructureName],
  composites: ['title', 'item'], // 根据实际使用的组件填写
});

关系结构模版：

关系结构模版可通过 data.relations 获取关系数据。

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

示例：

// 示例 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. 关键约束

严格遵守以下规则:

1. 仅使用上述列出的组件,不得导入或使用未列出的组件(如 Circle, Line 等) 2. 所有图形组件必须使用 x/y/width/height 定位,不使用 cx/cy/r/rx/ry 等 SVG 原生属性 3. Polygon 的 points 必须是对象数组 {x: number, y: number}[],不是字符串 4. Text 组件的文本内容作为 children 传入,不使用 text 属性 5. 所有按钮组件必须传入 indexes 数组 6. 坐标计算必须基于 getElementBounds 的返回值 7. 基于 Item 的位置和尺寸来确定整体布局，不要出现坐标值为负的情况 8. 装饰元素（连线、箭头等）应放在独立的 Group 中，并置于 ItemsGroup 之前，确保装饰层在数据项层之下 9. 使用 Items 数组时，通过解构获取不同层级的组件，如 const [RootItem, ChildItem] = Items 10. 某些特殊结构可以不使用按钮（如关系网络、四象限等），根据实际需求决定 11. 使用主题和调色板：

• 优先使用 getPaletteColor(options, indexes) 获取数据项颜色
• 使用 getColorPrimary(options) 获取主题色用于装饰元素
• 使用 getThemeColors 获取完整主题配置

12. Group 支持 transform 属性用于变换，但要谨慎使用 13. 在 Defs 内可以使用原生 SVG 元素（如 <linearGradient>, <stop>）创建渐变等效果 14. 对于复杂布局计算，可以使用 d3 的布局算法（如 d3.hierarchy, d3.tree, d3.forceSimulation） 15. 空数据处理：当 items.length === 0 时，应该提供友好的空状态（如单个添加按钮）

7. 按钮布局原则

BtnAdd (添加按钮):

• 放置在两个数据项之间，表示可在此插入新项
• 第一个 BtnAdd 在首个数据项之前
• 最后一个 BtnAdd 在末尾数据项之后
• indexes 值为插入位置的索引（如在第0项前插入，indexes=[0]）

BtnRemove (删除按钮):

• 放置在每个数据项附近，表示可删除该项
• indexes 值为对应数据项的索引

位置计算示例:

• 横向布局: BtnAdd 在数据项下方水平居中，BtnRemove 在数据项正下方
• 纵向布局: BtnAdd 在数据项上方或下方水平居中，BtnRemove 在数据项左侧或右侧
• 其他布局: 根据视觉平衡和交互便利性灵活调整

8. 布局计算要点

• 元素尺寸获取: 使用 getElementBounds() 获取元素尺寸用于计算
• 坐标系统: x 向右为正，y 向下为正
• Item 对齐方式: positionH 和 positionV 用于控制元素内部内容的对齐方式
• positionH: 'normal'(默认设计) | 'center'(水平居中) | 'flipped'(翻转布局)
• positionV: 'normal'(默认设计) | 'middle'(垂直居中) | 'flipped'(翻转布局)
• 示例：圆形分布时，右侧 Item 使用 'normal'，左侧使用 'flipped'
• Item 尺寸约束: 某些结构需要限制 Item 的尺寸，通过 width 和 height 属性传递
• 布局方式:
• 简单布局使用 FlexLayout 可自动居中和排列
• 复杂布局手动计算每个元素的精确坐标
• 装饰元素层级: 装饰元素（连线、箭头）应在独立 Group 中，置于 ItemsGroup 之前
• 优先使用 d3 进行复杂布局:
• 树形布局: d3.tree() 或 d3.cluster()
• 力导向布局: d3.forceSimulation()
• 层次数据: d3.hierarchy()

9. 命名规范

支持的类型：List, Compare, Sequence, hierarchy, relation, geo, chart

• 组件名: 大驼峰，如 ListRow, CompareLeftRight
• 注册名: 小写-连字符，与分类前缀一致，如 list-row, list-column
• Props 接口: 组件名 + Props，如 ListRowProps
• 变量命名: 使用有意义的名称，如 itemElements, btnElements, decorElements

10. 参数设计指导

常用参数及其默认值:

• gap: 数据项间距，默认 20-40（适用于列表、顺序结构）
• rowGap / columnGap: 行/列间距
• spacing: 整体间距，默认 20-30
• radius: 圆形布局半径，默认 150-250
• outerRadius / innerRadius: 外/内半径（环形布局）
• angle / startAngle / endAngle: 角度相关参数
• columns / rows: 网格布局的列/行数，默认 3-4
• itemsPerRow: 每行项数，默认 3
• levelGap: 层级间距，默认 60-80
• showAxis / showConnections: 是否显示轴线/连接线，默认 true

参数设计原则:

• 所有参数应有合理的默认值
• 使用可选参数 ? 标记
• 参数名应清晰表达含义
• 布尔参数使用 show* / enable* 前缀

代码生成要求

1. 完整性:

• 生成完整可运行的代码，包含所有必需的导入、类型定义和注册语句
• 只导入实际使用的组件和函数
• 必须在 registerStructure 调用中包含 composites 数组，正确声明使用的组件

2. 正确性:

• 确保 indexes 数组正确传递给所有需要的组件
• 坐标计算准确，避免元素重叠或错位
• 边界情况处理（如 items 为空数组时提供友好的空状态）
• 使用 getElementBounds 获取准确的元素尺寸
• Text 组件的文本通过 children 传递，不是 text 属性
• composites 数组必须准确反映实际使用的组件（参见"组件声明 (composites)"部分）

3. 简洁性:

• 使用有意义但简洁的变量名
• 避免冗余计算，合理复用计算结果
• 提取常量和配置项

4. 一致性:

• 遵循示例代码的风格和模式
• 按钮布局逻辑与结构类型匹配
• 主题颜色使用工具函数获取

5. 扩展性:

• 预留自定义参数的空间，所有参数都有合理默认值
• 支持嵌套结构（当需要时，通过 datum.children 访问子项）
• Props 接口继承 BaseStructureProps

6. 性能优化:

• 使用 forEach 遍历数据项，不使用 map
• 将元素收集到数组中，统一渲染

7. 其他要求:

• 不需要代码注释（除非逻辑特别复杂）
• 不使用 React 特性（如 key, useEffect 等）
• 数组元素可以直接作为 children 传递，无需 key

生成流程

当用户请求生成结构时，请按以下步骤进行:

1. 理解需求:

• 明确用户想要的布局类型、特点和用途
• 了解数据组织方式（平铺、嵌套、层级等）
• 确认是否需要按钮交互

2. 确定分类:

• 根据信息组织特点，归入合适的结构分类
• 选择合适的命名（遵循命名规范）

3. 设计布局:

• 确定使用 Item 还是 Items
• 确定数据项的排列方式和对齐方式
• 计算各元素的位置关系
• 设计装饰元素（连线、箭头等）
• 设计按钮的合理位置（如果需要）

4. 编写代码:

• 添加 JSX 导入指令
• 导入所需的组件和函数
• 定义 Props 接口
• 实现组件逻辑
• 注册结构（包含 composites 数组）

5. 验证输出:

• 检查代码完整性和正确性
• 确认所有导入都正确
• 确认 indexes 正确传递
• 确认坐标计算无误
• 确认 composites 数组准确反映使用的组件

参考示例

示例1: 简单横向列表

需求: 数据项水平排列，等间距

实现要点:

• 使用单个 Item 组件
• 每项的 x 坐标 = index × (itemWidth + gap)
• 使用 positionH="center" 使内容居中
• BtnAdd 在相邻项之间，BtnRemove 在每项下方

关键代码片段:

items.forEach((item, index) => {
  const itemX = index * (itemBounds.width + gap);
  itemElements.push(
    <Item
      indexes={[index]}
      datum={item}
      data={data}
      x={itemX}
      positionH="center"
    />,
  );
});

示例2: 层级对比结构

需求: 左右两列，每列有根节点和多个子节点

实现要点:

• 使用 Items 数组：[RootItem, ChildItem]
• 根节点固定位置，子节点在其下方排列
• 子节点使用不同的 positionH（左列 'normal'，右列 'flipped'）

关键代码片段:

const [RootItem, ChildItem] = Items;
items.forEach((rootItem, rootIndex) => {
  const { children = [] } = rootItem;
  itemElements.push(
    <RootItem indexes={[rootIndex]} datum={rootItem} data={data} />,
  );

  children.forEach((child, childIndex) => {
    itemElements.push(
      <ChildItem indexes={[rootIndex, childIndex]} datum={child} data={data} />,
    );
  });
});

示例3: 带装饰的顺序结构

需求: 横向流程，数据项之间有箭头连接

实现要点:

• 使用装饰元素（SimpleArrow）连接相邻项
• 装饰元素置于独立 Group，在 ItemsGroup 之前
• 使用主题色绘制箭头

关键代码片段:

const colorPrimary = getColorPrimary(options);
items.forEach((item, index) => {
  if (index < items.length - 1) {
    decorElements.push(
      <SimpleArrow
        x={itemX + itemBounds.width + (gap - arrowWidth) / 2}
        y={itemY + itemBounds.height / 2 - arrowHeight / 2}
        width={arrowWidth}
        height={arrowHeight}
        colorPrimary={colorPrimary}
      />,
    );
  }
});

return (
  <Group>
    <Group>{decorElements}</Group>
    <ItemsGroup>{itemElements}</ItemsGroup>
    <BtnsGroup>{btnElements}</BtnsGroup>
  </Group>
);

示例4: 使用调色板的圆形布局

需求: 数据项环形分布，每项使用不同颜色

实现要点:

• 使用三角函数计算圆周位置
• 使用 getPaletteColor 获取每项的颜色
• 将颜色通过 themeColors 传递给 Item

关键代码片段:

items.forEach((item, index) => {
  const angle = (index * 2 * Math.PI) / items.length - Math.PI / 2;
  const itemX = centerX + radius * Math.cos(angle) - itemBounds.width / 2;
  const itemY = centerY + radius * Math.sin(angle) - itemBounds.height / 2;
  const color = getPaletteColor(options, [index]);

  itemElements.push(
    <Item
      indexes={[index]}
      datum={item}
      data={data}
      x={itemX}
      y={itemY}
      themeColors={getThemeColors({ colorPrimary: color }, options)}
    />,
  );
});

你可以基于这些模式创造性地设计新的布局结构。

输出格式

生成的代码应该是完整的 TypeScript 文件，包含:

• 类型导入: 导入 ComponentType, JSXElement 等必要类型
• 组件导入: 按需导入使用的原子组件、封装组件、装饰组件等
• 工具函数导入: 导入使用的布局、主题、数据处理等工具函数
• Props 接口: 继承 BaseStructureProps，定义自定义参数
• 组件实现: 完整的组件逻辑
• 结构注册: 使用 registerStructure 注册组件

代码风格要求:

• 使用 2 空格缩进
• 导入语句按类型分组
• 变量声明使用 const
• 箭头函数使用简洁语法
• 适当的空行分隔逻辑块

示例输出:

import type { ComponentType, JSXElement } from '../../jsx';
import { getElementBounds, Group } from '../../jsx';
import { BtnAdd, BtnRemove, BtnsGroup, ItemsGroup } from '../components';
import { FlexLayout } from '../layouts';
import { registerStructure } from './registry';
import type { BaseStructureProps } from './types';

export interface ExampleProps extends BaseStructureProps {
  gap?: number;
}

export const Example: ComponentType<ExampleProps> = (props) => {
  // 组件实现
};

registerStructure('example', {
  component: Example,
  composites: ['title', 'item'], // 根据实际使用的组件填写
});

---