Layout Painter

通用截面布局图绘制工具。提供灵活的布局系统，支持函数回调、链式调用和参数化配置三种使用方式。

特性

- 三种 API 模式：函数回调 API、链式 API 和参数化 API，满足不同使用场景
- 灵活的圆形布局：支持多层嵌套的圆形布局算法
- 线性布局：支持沿直线均匀排列子元素
- 多边形布局：支持沿正多边形的边均匀排列子元素
- SVG 输出：内置 SVGPainter，生成高质量的 SVG 图形
- TypeScript 支持：完整的类型定义
- 轻量级：零依赖，易于集成

安装

``bash
npm install layout-painter
`

要求：Node.js >= 22.0.0

快速开始

$3

最底层的 API，使用 circleLayout 函数和回调来处理每个元素的位置：

`typescript
import { circleLayout, lineLayout, polygonLayout, SVGPainter } from 'layout-painter';

const painter = new SVGPainter(500, 500);
const center = [250, 250];

// 绘制中心圆
painter.circle(center, 20);

// 绘制正六边形
painter.polygon([250, 100], 0, 6, 40);

// 围绕中心点创建 6 个子圆
circleLayout(center, 0, 80, 6, (subCenter) => {
// 在每个子圆位置绘制
painter.circle(subCenter, 10);

// 每个子圆周围再创建 6 个小圆
circleLayout(subCenter, 0, 20, 6, (tinyCenter) => {
painter.circle(tinyCenter, 3);
});
});

// 沿水平方向排列 5 个圆
lineLayout([100, 400], 0, 300, 5, (center) => {
painter.circle(center, 8);
});

// 沿正六边形的边排列元素，每条边 4 个元素
polygonLayout([250, 250], 0, 6, 100, 40, 4, (pos, angle) => {
painter.circle(pos, 8);
});

const svg = painter.render();
`

$3

链式接口，使用 .end() 返回父层级，适合构建层级结构：

`typescript
import { createChain, SVGPainter } from 'layout-painter';

const painter = new SVGPainter(500, 500);

// 圆形布局示例
createChain(painter, [250, 250])
.circle(20) // 中心圆
.polygon(0, 6, 30) // 中心六边形
.circleLayout(0, 80, 6) // 第一层布局：6 个子圆
.circle(10) // 子圆
.circleLayout(0, 20, 6) // 第二层布局：每个子圆周围 6 个小圆
.circle(3)
.end()
.end();

// 线性布局示例
createChain(painter, [100, 400])
.lineLayout(0, 300, 5) // 沿水平方向排列 5 个元素
.circle(8);

// 多边形布局示例
createChain(painter, [250, 450])
.polygonLayout(0, 6, 80, 50, 3) // 正六边形，每条边 3 个元素
.circle(10);

const svg = painter.render();
`

$3

使用配置对象定义布局，适合数据驱动或序列化的场景：

`typescript
import { draw, SVGPainter } from 'layout-painter';

const painter = new SVGPainter(500, 500);

// 圆形布局示例
const circleLayers = [
{ type: 'circle', radius: 20 },
{ type: 'polygon', angle: 0, sides: 6, radius: 30 },
{
type: 'circleLayout',
angle: 0,
radius: 80,
count: 6,
layers: [
{ type: 'circle', radius: 10 },
{
type: 'circleLayout',
angle: 0,
radius: 20,
count: 6,
layers: [
{ type: 'circle', radius: 3 }
]
}
]
}
];

// 线性布局示例
const lineLayers = [
{
type: 'lineLayout',
angle: 0,
length: 300,
count: 5,
layers: [
{ type: 'circle', radius: 8 }
]
}
];

// 多边形布局示例
const polygonLayers = [
{
type: 'polygonLayout',
angle: 0,
sides: 6,
apothem: 80,
length: 50,
perSide: 3,
layers: [
{ type: 'circle', radius: 10 }
]
}
];

draw(painter, [250, 250], 0, circleLayers);
draw(painter, [100, 400], 0, lineLayers);
draw(painter, [250, 450], 0, polygonLayers);
const svg = painter.render();
`

API 参考

$3

| 导出 | 说明 |
|------|------|
| circleLayout | 圆形布局算法函数 |
| lineLayout | 线性布局算法函数 |
| polygonLayout | 多边形布局算法函数 |
| SVGPainter | SVG 绘图和渲染器 |
| Point | 坐标点类型 [x, y] |

$3

| 导出 | 说明 |
|------|------|
| createChain | 创建链式调用对象 |
| Chain | 链式调用类型 |

$3

| 导出 | 说明 |
|------|------|
| draw | 使用参数配置绘制 |
| LayerParam | 图层配置类型 |

核心算法与接口

$3

circleLayout(center, angle, radius, count, callback)

围绕中心点按圆形分布多个元素。

- center: Point - 中心点坐标 [x, y]
- angle: number - 起始角度（度）
- radius: number - 分布半径
- count: number - 元素数量
- callback: LayoutCallback - 每个元素位置的回调函数

$3

lineLayout(center, angle, length, count, callback)

沿直线均匀分布多个元素，直线以中心点为基准向两端延伸。

- center: Point - 直线中心的坐标 [x, y]
- angle: number - 直线的角度（度），决定直线的方向
- length: number - 直线的总长度
- count: number - 要排列的子元素数量
- callback: LayoutCallback - 每个元素位置的回调函数

示例：

`typescript
// 在中心点 (100, 100) 处，沿水平方向（0度）排列 5 个半径为 8 的圆，总长度 200
lineLayout([100, 100], 0, 200, 5, (center, angle, index) => {
painter.circle(center, 8);
});
`

$3

polygonLayout(center, angle, sides, apothem, length, perSide, callback)

沿正多边形的边均匀分布多个元素。

- center: Point - 多边形中心的坐标 [x, y]
- angle: number - 起始角度（度），用于旋转整个布局
- sides: number - 多边形的边数（3=三角形，4=正方形，5=五边形，6=六边形...）
- apothem: number - 多边形的边心距（边到中心的垂直距离）
- length: number - 每条边上用于排列元素的总长度
- perSide: number - 每条边上的元素数量
- callback: LayoutCallback - 每个元素位置的回调函数

示例：

`typescript
// 在中心点 (250, 250) 周围，沿正六边形的边排列元素
// 边心距 100，每条边分布长度 40，每条边 4 个元素
polygonLayout([250, 250], 0, 6, 100, 40, 4, (center, angle, index) => {
painter.circle(center, 8);
});
`

$3

定义基本绘图操作，实现此接口可用于不同渲染后端。

`typescript
interface Painter {
/**
* 绘制一个圆形
* @param center - 圆心的坐标 [x, y]
* @param radius - 圆的半径
*/
circle(center: Point, radius: number): void;

/**
* 绘制一个椭圆
* @param center - 椭圆中心的坐标 [x, y]
* @param angle - 旋转角度（度），angle = 0 时长轴垂直向上
* @param semiMajorAxis - 半长轴长度
* @param semiMinorAxis - 半短轴长度
*/
ellipse(center: Point, angle: number, semiMajorAxis: number, semiMinorAxis: number): void;

/**
* 绘制一个正多边形
* @param center - 多边形中心的坐标 [x, y]
* @param angle - 旋转角度（度）
* @param sides - 边数
* @param radius - 外接圆半径
*/
polygon(center: Point, angle: number, sides: number, radius: number): void;
}
`

示例：

`typescript
// 绘制垂直长轴的椭圆（半长轴50，半短轴30）
painter.ellipse([250, 250], 0, 50, 30);

// 绘制旋转 45 度的椭圆（半长轴40，半短轴20）
painter.ellipse([100, 100], 45, 40, 20);

// 绘制正六边形
painter.polygon([250, 250], 0, 6, 50);

// 绘制旋转 30 度的正方形
painter.polygon([100, 100], 30, 4, 40);
`

开发

`bash


构建

npm run build

运行测试

npm run test

监听模式测试

npm run test:watch
``

测试输出：test-output/visual-report.html

许可证

MIT