@codehz/draw-call 0.1.1 → 0.2.0

package/README.md

@@ -1,15 +1,383 @@
 # @codehz/draw-call
 
-To install dependencies:
+一个声明式 Canvas 绘图库，提供 Flexbox 布局引擎和组件化渲染系统。使用类似 UI 框架的方式来绘制 Canvas 内容，让 Canvas 绘图变得简单直观。
+
+## ✨ 特性
+
+- **Flexbox 布局引擎** - 支持完整的 Flexbox 布局，包括方向、对齐、间距等
+- **组件化渲染** - 提供 Box、Text、Image、Svg、Stack 等组件
+- **丰富的样式支持** - 渐变、阴影、边框、圆角等
+- **文本排版** - 自动换行、省略号、行高控制等
+- **SVG 图形** - 支持矩形、圆形、椭圆、路径等 SVG 图形
+- **跨平台** - 支持浏览器和 Node.js 环境
+- **TypeScript** - 完整的类型支持
+
+## 📦 安装
 
 ```bash
-bun install
+bun install @codehz/draw-call
 ```
 
-To run:
+## 🚀 快速开始
 
-```bash
-bun run index.ts
+### 浏览器环境
+
+```typescript
+import { createCanvas, Box, Text } from "@codehz/draw-call";
+
+// 获取 canvas 元素
+const canvasEl = document.getElementById("canvas") as HTMLCanvasElement;
+
+// 创建 Canvas 实例
+const canvas = createCanvas({
+  width: 400,
+  height: 300,
+  pixelRatio: window.devicePixelRatio || 1,
+  canvas: canvasEl,
+});
+
+// 渲染内容
+canvas.render(
+  Box({
+    width: "fill",
+    height: "fill",
+    background: "#ffffff",
+    padding: 20,
+    children: [
+      Text({
+        content: "Hello, draw-call!",
+        font: { size: 24, weight: "bold" },
+        color: "#333333",
+      }),
+    ],
+  })
+);
+```
+
+### Node.js 环境
+
+```typescript
+import { createCanvas, Box, Text } from "@codehz/draw-call";
+import { createNodeCanvas } from "@codehz/draw-call/node";
+
+// 创建 Canvas 实例
+const canvas = createNodeCanvas({
+  width: 400,
+  height: 300,
+  pixelRatio: 2,
+});
+
+// 渲染内容
+canvas.render(
+  Box({
+    width: "fill",
+    height: "fill",
+    background: "#ffffff",
+    padding: 20,
+    children: [
+      Text({
+        content: "Hello, draw-call!",
+        font: { size: 24, weight: "bold" },
+        color: "#333333",
+      }),
+    ],
+  })
+);
+
+// 保存为图片
+const buffer = await canvas.toBuffer("image/png");
+await Bun.write("output.png", buffer);
+```
+
+## 📚 组件
+
+### Box
+
+容器组件，支持 Flexbox 布局和丰富的样式。
+
+```typescript
+Box({
+  width: 200,
+  height: 100,
+  background: "#ffffff",
+  border: { radius: 8, width: 1, color: "#e0e0e0" },
+  shadow: { offsetY: 2, blur: 8, color: "rgba(0,0,0,0.08)" },
+  padding: 20,
+  direction: "row",
+  justify: "center",
+  align: "center",
+  children: [...],
+})
+```
+
+### Text
+
+文本组件，支持自动换行、行高控制等。
+
+```typescript
+Text({
+  content: "这是一段文本",
+  font: { size: 16, weight: "bold", family: "sans-serif" },
+  color: "#333333",
+  align: "center",
+  lineHeight: 1.5,
+  wrap: true,
+  maxLines: 3,
+  ellipsis: true,
+});
+```
+
+### RichText
+
+富文本组件，支持同时展示多种样式的文本，每个文本段落可以有不同的字体、颜色、背景、装饰等。
+
+```typescript
+RichText({
+  spans: [
+    {
+      text: "普通文本 ",
+      color: "#333333",
+    },
+    {
+      text: "加粗文本 ",
+      font: { size: 16, weight: "bold" },
+      color: "#333333",
+    },
+    {
+      text: "彩色文本 ",
+      font: { size: 16, weight: "bold" },
+      color: "#667eea",
+    },
+    {
+      text: "带背景 ",
+      color: "#ffffff",
+      background: "#764ba2",
+    },
+    {
+      text: "带下划线",
+      underline: true,
+      color: "#333333",
+    },
+    {
+      text: "删除线",
+      strikethrough: true,
+      color: "#999999",
+    },
+  ],
+  lineHeight: 1.5,
+  align: "left",
+  maxLines: 5,
+  ellipsis: true,
+});
+```
+
+### Image
+
+图片组件，支持多种适配模式。
+
+```typescript
+Image({
+  src: imageBitmap,
+  width: 200,
+  height: 150,
+  fit: "cover", // contain | cover | fill | none | scale-down
+  position: { x: "center", y: "center" },
+  border: { radius: 8 },
+});
+```
+
+### Svg
+
+SVG 图形组件，支持多种图形元素。
+
+```typescript
+import { svg } from "@codehz/draw-call";
+
+Svg({
+  width: 200,
+  height: 100,
+  viewBox: { width: 200, height: 100 },
+  children: [
+    svg.rect({ x: 10, y: 10, width: 50, height: 30, fill: "#667eea" }),
+    svg.circle({ cx: 100, cy: 50, r: 20, fill: "#764ba2" }),
+    svg.path({ d: "M150 50 Q170 30, 190 50", stroke: { color: "#333", width: 2 } }),
+  ],
+});
+```
+
+### Stack
+
+堆叠组件，子元素绝对定位。
+
+```typescript
+Stack({
+  width: 200,
+  height: 200,
+  align: "center",
+  justify: "center",
+  children: [
+    Box({ width: 100, height: 100, background: "#ff0000" }),
+    Box({ width: 50, height: 50, background: "#00ff00" }),
+  ],
+});
+```
+
+## 🎨 样式
+
+### 尺寸
+
+```typescript
+// 固定像素值
+width: 100;
+
+// 百分比
+width: "50%";
+
+// 自动计算
+width: "auto";
+
+// 填充可用空间
+width: "fill";
+```
+
+### 颜色
+
+```typescript
+// CSS 颜色字符串
+background: "#ff0000";
+background: "rgb(255, 0, 0)";
+background: "red";
+
+// 渐变
+import { linearGradient, radialGradient } from "@codehz/draw-call";
+
+// 线性渐变
+background: linearGradient(135, "#667eea", "#764ba2");
+
+// 带位置色标的线性渐变
+background: linearGradient(90, [0, "#667eea"], [0.5, "#764ba2"], [1, "#f093fb"]);
+
+// 径向渐变
+background: radialGradient({ startX: 0.5, startY: 0.5, endRadius: 0.5 }, "#667eea", "#764ba2");
+```
+
+### 边框
+
+```typescript
+border: {
+  width: 2,
+  color: "#e0e0e0",
+  radius: 8, // 或 [8, 8, 8, 8] 分别对应左上、右上、右下、左下
+}
+```
+
+### 阴影
+
+```typescript
+shadow: {
+  offsetX: 0,
+  offsetY: 4,
+  blur: 16,
+  color: "rgba(0,0,0,0.12)",
+}
+```
+
+### 间距
+
+```typescript
+// 四边相同
+padding: 20
+margin: 10
+
+// 分别设置
+padding: { top: 10, right: 20, bottom: 10, left: 20 }
+margin: { top: 5, right: 10, bottom: 5, left: 10 }
+```
+
+## 📐 布局
+
+### Flexbox 布局
+
+```typescript
+Box({
+  direction: "row", // row | column
+  justify: "center", // flex-start | center | flex-end | space-between | space-around | space-evenly
+  align: "center", // flex-start | center | flex-end | stretch | baseline
+  gap: 10,
+  wrap: true,
+  children: [...],
+})
+```
+
+### 弹性布局
+
+```typescript
+Box({
+  direction: "row",
+  children: [
+    Box({ width: 100 }), // 固定宽度
+    Box({ flex: 1 }), // 占据剩余空间
+    Box({ flex: 2 }), // 占据 2 份剩余空间
+  ],
+});
+```
+
+## 🔧 高级用法
+
+### 自定义字体（Node.js）
+
+```typescript
+import { GlobalFonts } from "@napi-rs/canvas";
+
+GlobalFonts.registerFromPath("/path/to/font.ttf", "CustomFont");
+
+Text({
+  content: "自定义字体",
+  font: { family: "CustomFont", size: 16 },
+});
 ```
 
-This project was created using `bun init` in bun v1.3.6. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### 导出图片
+
+```typescript
+// 导出为 PNG
+const buffer = await canvas.toBuffer("image/png");
+
+// 导出为 JPEG
+const buffer = await canvas.toBuffer("image/jpeg", { quality: 0.9 });
+
+// 导出为 WebP
+const buffer = await canvas.toBuffer("image/webp", { quality: 0.8 });
+```
+
+### 获取布局信息
+
+```typescript
+const layoutNode = canvas.render(
+  Box({
+    width: 200,
+    height: 100,
+    children: [...],
+  })
+);
+
+console.log(layoutNode.layout.width);   // 200
+console.log(layoutNode.layout.height);  // 100
+console.log(layoutNode.layout.x);       // 0
+console.log(layoutNode.layout.y);       // 0
+```
+
+## 📖 示例
+
+查看 [examples](examples) 目录获取更多示例：
+
+- [demo.ts](examples/demo.ts) - 浏览器环境演示
+- [card.ts](examples/card.ts) - Node.js 环境卡片示例
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+MIT

package/{canvas-BYrCq8eS.d.mts → canvas.d.cts}

@@ -101,6 +101,33 @@ interface ComputedLayout {
   contentWidth: number;
   contentHeight: number;
 }
+interface RichTextSpanSegment {
+  text: string;
+  font: FontProps;
+  color: Color;
+  background: Color;
+  underline: boolean;
+  strikethrough: boolean;
+  width: number;
+  height: number;
+  ascent: number;
+  descent: number;
+  offset: number;
+}
+interface RichTextLine {
+  segments: RichTextSpanSegment[];
+  width: number;
+  height: number;
+  baseline: number;
+}
+interface LayoutNode {
+  element: Element;
+  layout: ComputedLayout;
+  children: LayoutNode[];
+  lines?: string[];
+  lineOffsets?: number[];
+  richLines?: RichTextLine[];
+}
 interface LayoutConstraints {
   minWidth: number;
   maxWidth: number;
@@ -109,7 +136,7 @@ interface LayoutConstraints {
 }
 //#endregion
 //#region src/types/components.d.ts
-type ElementType = "box" | "text" | "image" | "shape" | "stack";
+type ElementType = "box" | "text" | "richtext" | "image" | "svg" | "stack";
 interface ElementBase {
   type: ElementType;
 }
@@ -140,8 +167,29 @@ interface TextProps extends LayoutProps {
 interface TextElement extends ElementBase, TextProps {
   type: "text";
 }
+interface RichTextStyleProps {
+  font?: FontProps;
+  color?: Color;
+  background?: Color;
+  underline?: boolean;
+  strikethrough?: boolean;
+}
+interface RichTextSpan extends RichTextStyleProps {
+  text: string;
+}
+interface RichTextProps extends LayoutProps, RichTextStyleProps {
+  spans: RichTextSpan[];
+  lineHeight?: number;
+  align?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+  maxLines?: number;
+  ellipsis?: boolean;
+}
+interface RichTextElement extends ElementBase, RichTextProps {
+  type: "richtext";
+}
 interface ImageProps extends LayoutProps {
-  src: string | ImageBitmap | CanvasImageSource;
+  src: ImageBitmap | CanvasImageSource;
   fit?: "contain" | "cover" | "fill" | "none" | "scale-down";
   position?: {
     x?: "left" | "center" | "right" | number;
@@ -154,50 +202,112 @@ interface ImageProps extends LayoutProps {
 interface ImageElement extends ElementBase, ImageProps {
   type: "image";
 }
-type ShapeType = "rect" | "circle" | "ellipse" | "line" | "polygon" | "path";
-interface ShapeProps extends LayoutProps {
-  shape: ShapeType;
-  fill?: Color;
+interface SvgStyleProps {
+  fill?: Color | "none";
   stroke?: StrokeProps;
+  opacity?: number;
+}
+interface SvgTransformProps {
+  transform?: {
+    translate?: [number, number];
+    rotate?: number | [number, number, number];
+    scale?: number | [number, number];
+    skewX?: number;
+    skewY?: number;
+    matrix?: [number, number, number, number, number, number];
+  };
+}
+interface SvgRectChild extends SvgStyleProps, SvgTransformProps {
+  type: "rect";
+  x?: number;
+  y?: number;
+  width: number;
+  height: number;
+  rx?: number;
+  ry?: number;
+}
+interface SvgCircleChild extends SvgStyleProps, SvgTransformProps {
+  type: "circle";
+  cx: number;
+  cy: number;
+  r: number;
+}
+interface SvgEllipseChild extends SvgStyleProps, SvgTransformProps {
+  type: "ellipse";
+  cx: number;
+  cy: number;
+  rx: number;
+  ry: number;
+}
+interface SvgLineChild extends SvgStyleProps, SvgTransformProps {
+  type: "line";
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+interface SvgPolylineChild extends SvgStyleProps, SvgTransformProps {
+  type: "polyline";
+  points: [number, number][];
+}
+interface SvgPolygonChild extends SvgStyleProps, SvgTransformProps {
+  type: "polygon";
+  points: [number, number][];
+}
+interface SvgPathChild extends SvgStyleProps, SvgTransformProps {
+  type: "path";
+  d: string;
+}
+interface SvgTextChild extends SvgStyleProps, SvgTransformProps {
+  type: "text";
+  x?: number;
+  y?: number;
+  content: string;
+  font?: FontProps;
+  textAnchor?: "start" | "middle" | "end";
+  dominantBaseline?: "auto" | "middle" | "hanging";
+}
+interface SvgGroupChild extends SvgStyleProps, SvgTransformProps {
+  type: "g";
+  children: SvgChild[];
+}
+type SvgChild = SvgRectChild | SvgCircleChild | SvgEllipseChild | SvgLineChild | SvgPolylineChild | SvgPolygonChild | SvgPathChild | SvgTextChild | SvgGroupChild;
+type SvgAlign = "none" | "xMinYMin" | "xMidYMin" | "xMaxYMin" | "xMinYMid" | "xMidYMid" | "xMaxYMid" | "xMinYMax" | "xMidYMax" | "xMaxYMax";
+interface SvgProps extends LayoutProps {
+  viewBox?: {
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+  };
+  preserveAspectRatio?: {
+    align?: SvgAlign;
+    meetOrSlice?: "meet" | "slice";
+  };
+  children: SvgChild[];
+  background?: Color;
   shadow?: Shadow;
-  points?: [number, number][];
-  path?: string;
 }
-interface ShapeElement extends ElementBase, ShapeProps {
-  type: "shape";
+interface SvgElement extends ElementBase, SvgProps {
+  type: "svg";
 }
-interface StackProps extends ContainerLayoutProps {
+type StackAlign = "start" | "end" | "center";
+interface StackProps extends LayoutProps {
   children: Element[];
   background?: Color;
   border?: Border;
   shadow?: Shadow;
   opacity?: number;
   clip?: boolean;
+  /** 水平对齐方式（默认 start） */
+  align?: StackAlign;
+  /** 垂直对齐方式（默认 start） */
+  justify?: StackAlign;
 }
 interface StackElement extends ElementBase, StackProps {
   type: "stack";
 }
-type Element = BoxElement | TextElement | ImageElement | ShapeElement | StackElement;
-//#endregion
-//#region src/layout/measure.d.ts
-interface MeasureContext {
-  measureText(text: string, font: FontProps): {
-    width: number;
-    height: number;
-    offset: number;
-  };
-}
-declare function createCanvasMeasureContext(ctx: CanvasRenderingContext2D): MeasureContext;
-//#endregion
-//#region src/layout/engine.d.ts
-interface LayoutNode {
-  element: Element;
-  layout: ComputedLayout;
-  children: LayoutNode[];
-  lines?: string[];
-  lineOffsets?: number[];
-}
-declare function computeLayout(element: Element, ctx: MeasureContext, constraints: LayoutConstraints, x?: number, y?: number): LayoutNode;
+type Element = BoxElement | TextElement | RichTextElement | ImageElement | SvgElement | StackElement;
 //#endregion
 //#region src/canvas.d.ts
 interface CanvasOptions {
@@ -218,11 +328,12 @@ interface DrawCallCanvas {
   readonly width: number;
   readonly height: number;
   readonly pixelRatio: number;
+  readonly canvas: HTMLCanvasElement;
   render(element: Element): LayoutNode;
   clear(): void;
   getContext(): CanvasRenderingContext2D;
   toDataURL(type?: string, quality?: number): string;
-  toBuffer(type?: "image/png" | "image/jpeg"): Promise<Buffer>;
+  toBuffer(type?: "image/png" | "image/jpeg"): Buffer;
 }
 /**
  * 创建适用于浏览器环境的 Canvas
@@ -231,4 +342,4 @@ interface DrawCallCanvas {
  */
 declare function createCanvas(options: CanvasOptions): DrawCallCanvas;
 //#endregion
-export { Shadow as A, Bounds as C, GradientDescriptor as D, FontProps as E, radialGradient as F, Spacing as M, StrokeProps as N, LinearGradientDescriptor as O, linearGradient as P, Border as S, ColorStop as T, AlignSelf as _, LayoutNode as a, JustifyContent as b, createCanvasMeasureContext as c, Element as d, StackElement as f, AlignItems as g, TextProps as h, createCanvas as i, Size as j, RadialGradientDescriptor as k, BoxElement as l, TextElement as m, DrawCallCanvas as n, computeLayout as o, StackProps as p, LayoutSize as r, MeasureContext as s, CanvasOptions as t, BoxProps as u, ContainerLayoutProps as v, Color as w, LayoutProps as x, FlexDirection as y };
+export { linearGradient as $, SvgTransformProps as A, LayoutProps as B, SvgPathChild as C, SvgRectChild as D, SvgProps as E, ContainerLayoutProps as F, FontProps as G, Bounds as H, FlexDirection as I, RadialGradientDescriptor as J, GradientDescriptor as K, JustifyContent as L, TextProps as M, AlignItems as N, SvgStyleProps as O, AlignSelf as P, StrokeProps as Q, LayoutConstraints as R, SvgLineChild as S, SvgPolylineChild as T, Color as U, Border as V, ColorStop as W, Size as X, Shadow as Y, Spacing as Z, SvgChild as _, BoxElement as a, SvgEllipseChild as b, ImageElement as c, RichTextProps as d, radialGradient as et, RichTextSpan as f, SvgAlign as g, StackProps as h, createCanvas as i, TextElement as j, SvgTextChild as k, ImageProps as l, StackElement as m, DrawCallCanvas as n, BoxProps as o, StackAlign as p, LinearGradientDescriptor as q, LayoutSize as r, Element as s, CanvasOptions as t, RichTextElement as u, SvgCircleChild as v, SvgPolygonChild as w, SvgGroupChild as x, SvgElement as y, LayoutNode as z };