@codehz/draw-call 0.2.0 → 0.2.1

package/README.md

@@ -5,10 +5,12 @@
 ## ✨ 特性
 
 - **Flexbox 布局引擎** - 支持完整的 Flexbox 布局，包括方向、对齐、间距等
-- **组件化渲染** - 提供 Box、Text、Image、Svg、Stack 等组件
+- **组件化渲染** - 提供 Box、Text、Image、Svg、Stack、RichText、CustomDraw、Transform 等组件
 - **丰富的样式支持** - 渐变、阴影、边框、圆角等
-- **文本排版** - 自动换行、省略号、行高控制等
+- **文本排版** - 自动换行、省略号、行高控制、富文本支持等
 - **SVG 图形** - 支持矩形、圆形、椭圆、路径等 SVG 图形
+- **2D 变换** - 支持旋转、倾斜等 2D 变换操作
+- **自定义绘制** - 支持自定义 Canvas 绘制逻辑
 - **跨平台** - 支持浏览器和 Node.js 环境
 - **TypeScript** - 完整的类型支持
 
@@ -222,6 +224,44 @@ Stack({
 });
 ```
 
+### Transform
+
+2D 变换组件，支持旋转、倾斜等变换操作。
+
+```typescript
+Transform({
+  children: Box({
+    width: 100,
+    height: 100,
+    background: "#667eea",
+  }),
+  transform: {
+    rotate: Math.PI / 4, // 旋转 45 度
+  },
+  transformOrigin: ["50%", "50%"], // 变换原点
+});
+```
+
+### CustomDraw
+
+自定义绘制组件，提供原生 Canvas 上下文进行自定义绘制。
+
+```typescript
+CustomDraw({
+  width: 200,
+  height: 100,
+  draw: (ctx, options) => {
+    // 使用原生 Canvas API 进行绘制
+    ctx.fillStyle = "#667eea";
+    ctx.fillRect(10, 10, 180, 80);
+    ctx.fillStyle = "#ffffff";
+    ctx.font = "bold 16px sans-serif";
+    ctx.textAlign = "center";
+    ctx.fillText("Custom Draw", 100, 60);
+  },
+});
+```
+
 ## 🎨 样式
 
 ### 尺寸
@@ -373,6 +413,9 @@ console.log(layoutNode.layout.y);       // 0
 
 - [demo.ts](examples/demo.ts) - 浏览器环境演示
 - [card.ts](examples/card.ts) - Node.js 环境卡片示例
+- [richtext.ts](examples/richtext.ts) - 富文本示例
+- [transform.ts](examples/transform.ts) - 2D 变换示例
+- [customdraw.ts](examples/customdraw.ts) - 自定义绘制示例
 
 ## 🤝 贡献
 

package/canvas.d.cts

@@ -67,6 +67,19 @@ interface Bounds {
   height: number;
 }
 //#endregion
+//#region src/layout/utils/measure.d.ts
+interface MeasureTextResult {
+  width: number;
+  height: number;
+  offset: number;
+  ascent: number;
+  descent: number;
+}
+interface MeasureContext {
+  measureText(text: string, font: FontProps): MeasureTextResult;
+}
+declare function createCanvasMeasureContext(ctx: CanvasRenderingContext2D): MeasureContext;
+//#endregion
 //#region src/types/layout.d.ts
 type FlexDirection = "row" | "column" | "row-reverse" | "column-reverse";
 type JustifyContent = "start" | "end" | "center" | "space-between" | "space-around" | "space-evenly";
@@ -136,7 +149,12 @@ interface LayoutConstraints {
 }
 //#endregion
 //#region src/types/components.d.ts
-type ElementType = "box" | "text" | "richtext" | "image" | "svg" | "stack";
+type ElementType = "box" | "text" | "richtext" | "image" | "svg" | "stack" | "transform" | "customdraw";
+interface ProxiedCanvasContextOptions {
+  inner?: () => void;
+  width: number;
+  height: number;
+}
 interface ElementBase {
   type: ElementType;
 }
@@ -209,10 +227,10 @@ interface SvgStyleProps {
 }
 interface SvgTransformProps {
   transform?: {
-    translate?: [number, number];
+    translate?: [number, number]; /** 旋转角度（弧度）或 [angle(弧度), cx, cy](绕点旋转) */
     rotate?: number | [number, number, number];
-    scale?: number | [number, number];
-    skewX?: number;
+    scale?: number | [number, number]; /** 水平偏移角度（弧度） */
+    skewX?: number; /** 垂直偏移角度（弧度） */
     skewY?: number;
     matrix?: [number, number, number, number, number, number];
   };
@@ -307,7 +325,43 @@ interface StackProps extends LayoutProps {
 interface StackElement extends ElementBase, StackProps {
   type: "stack";
 }
-type Element = BoxElement | TextElement | RichTextElement | ImageElement | SvgElement | StackElement;
+interface TransformSimpleObject {
+  translate?: [number, number];
+  /** 旋转角度（弧度）或 [angle(弧度), cx, cy](绕点旋转) */
+  rotate?: number | [number, number, number];
+  scale?: number | [number, number];
+  /** 水平偏移角度（弧度） */
+  skewX?: number;
+  /** 垂直偏移角度（弧度） */
+  skewY?: number;
+}
+interface DOMMatrix2DInit {
+  a?: number;
+  b?: number;
+  c?: number;
+  d?: number;
+  e?: number;
+  f?: number;
+}
+type TransformValue = TransformSimpleObject | DOMMatrix2DInit | [number, number, number, number, number, number];
+interface TransformProps {
+  children: Element;
+  /** 变换值（rotate/skew 使用弧度） */
+  transform?: TransformValue;
+  /** 变换原点，默认为 [0, 0]（左上角） */
+  transformOrigin?: [number | string, number | string];
+}
+interface TransformElement extends ElementBase, TransformProps {
+  type: "transform";
+}
+interface CustomDrawProps extends LayoutProps {
+  draw: (ctx: CanvasRenderingContext2D, options: ProxiedCanvasContextOptions) => void;
+  children?: Element;
+}
+interface CustomDrawElement extends ElementBase, CustomDrawProps {
+  type: "customdraw";
+}
+type Element = BoxElement | TextElement | RichTextElement | ImageElement | SvgElement | StackElement | TransformElement | CustomDrawElement;
 //#endregion
 //#region src/canvas.d.ts
 interface CanvasOptions {
@@ -342,4 +396,4 @@ interface DrawCallCanvas {
  */
 declare function createCanvas(options: CanvasOptions): DrawCallCanvas;
 //#endregion
-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 };
+export { GradientDescriptor as $, SvgRectChild as A, ContainerLayoutProps as B, SvgEllipseChild as C, SvgPolygonChild as D, SvgPathChild as E, TextProps as F, LayoutProps as G, JustifyContent as H, TransformElement as I, Border as J, MeasureContext as K, TransformProps as L, SvgTextChild as M, SvgTransformProps as N, SvgPolylineChild as O, TextElement as P, FontProps as Q, AlignItems as R, SvgElement as S, SvgLineChild as T, LayoutConstraints as U, FlexDirection as V, LayoutNode as W, Color as X, Bounds as Y, ColorStop as Z, StackElement as _, BoxElement as a, StrokeProps as at, SvgChild as b, CustomDrawProps as c, ImageProps as d, LinearGradientDescriptor as et, ProxiedCanvasContextOptions as f, StackAlign as g, RichTextSpan as h, createCanvas as i, Spacing as it, SvgStyleProps as j, SvgProps as k, Element as l, RichTextProps as m, DrawCallCanvas as n, Shadow as nt, BoxProps as o, linearGradient as ot, RichTextElement as p, createCanvasMeasureContext as q, LayoutSize as r, Size as rt, CustomDrawElement as s, radialGradient as st, CanvasOptions as t, RadialGradientDescriptor as tt, ImageElement as u, StackProps as v, SvgGroupChild as w, SvgCircleChild as x, SvgAlign as y, AlignSelf as z };

package/canvas.d.mts

@@ -67,6 +67,19 @@ interface Bounds {
   height: number;
 }
 //#endregion
+//#region src/layout/utils/measure.d.ts
+interface MeasureTextResult {
+  width: number;
+  height: number;
+  offset: number;
+  ascent: number;
+  descent: number;
+}
+interface MeasureContext {
+  measureText(text: string, font: FontProps): MeasureTextResult;
+}
+declare function createCanvasMeasureContext(ctx: CanvasRenderingContext2D): MeasureContext;
+//#endregion
 //#region src/types/layout.d.ts
 type FlexDirection = "row" | "column" | "row-reverse" | "column-reverse";
 type JustifyContent = "start" | "end" | "center" | "space-between" | "space-around" | "space-evenly";
@@ -136,7 +149,12 @@ interface LayoutConstraints {
 }
 //#endregion
 //#region src/types/components.d.ts
-type ElementType = "box" | "text" | "richtext" | "image" | "svg" | "stack";
+type ElementType = "box" | "text" | "richtext" | "image" | "svg" | "stack" | "transform" | "customdraw";
+interface ProxiedCanvasContextOptions {
+  inner?: () => void;
+  width: number;
+  height: number;
+}
 interface ElementBase {
   type: ElementType;
 }
@@ -209,10 +227,10 @@ interface SvgStyleProps {
 }
 interface SvgTransformProps {
   transform?: {
-    translate?: [number, number];
+    translate?: [number, number]; /** 旋转角度（弧度）或 [angle(弧度), cx, cy](绕点旋转) */
     rotate?: number | [number, number, number];
-    scale?: number | [number, number];
-    skewX?: number;
+    scale?: number | [number, number]; /** 水平偏移角度（弧度） */
+    skewX?: number; /** 垂直偏移角度（弧度） */
     skewY?: number;
     matrix?: [number, number, number, number, number, number];
   };
@@ -307,7 +325,43 @@ interface StackProps extends LayoutProps {
 interface StackElement extends ElementBase, StackProps {
   type: "stack";
 }
-type Element = BoxElement | TextElement | RichTextElement | ImageElement | SvgElement | StackElement;
+interface TransformSimpleObject {
+  translate?: [number, number];
+  /** 旋转角度（弧度）或 [angle(弧度), cx, cy](绕点旋转) */
+  rotate?: number | [number, number, number];
+  scale?: number | [number, number];
+  /** 水平偏移角度（弧度） */
+  skewX?: number;
+  /** 垂直偏移角度（弧度） */
+  skewY?: number;
+}
+interface DOMMatrix2DInit {
+  a?: number;
+  b?: number;
+  c?: number;
+  d?: number;
+  e?: number;
+  f?: number;
+}
+type TransformValue = TransformSimpleObject | DOMMatrix2DInit | [number, number, number, number, number, number];
+interface TransformProps {
+  children: Element;
+  /** 变换值（rotate/skew 使用弧度） */
+  transform?: TransformValue;
+  /** 变换原点，默认为 [0, 0]（左上角） */
+  transformOrigin?: [number | string, number | string];
+}
+interface TransformElement extends ElementBase, TransformProps {
+  type: "transform";
+}
+interface CustomDrawProps extends LayoutProps {
+  draw: (ctx: CanvasRenderingContext2D, options: ProxiedCanvasContextOptions) => void;
+  children?: Element;
+}
+interface CustomDrawElement extends ElementBase, CustomDrawProps {
+  type: "customdraw";
+}
+type Element = BoxElement | TextElement | RichTextElement | ImageElement | SvgElement | StackElement | TransformElement | CustomDrawElement;
 //#endregion
 //#region src/canvas.d.ts
 interface CanvasOptions {
@@ -342,4 +396,4 @@ interface DrawCallCanvas {
  */
 declare function createCanvas(options: CanvasOptions): DrawCallCanvas;
 //#endregion
-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 };
+export { GradientDescriptor as $, SvgRectChild as A, ContainerLayoutProps as B, SvgEllipseChild as C, SvgPolygonChild as D, SvgPathChild as E, TextProps as F, LayoutProps as G, JustifyContent as H, TransformElement as I, Border as J, MeasureContext as K, TransformProps as L, SvgTextChild as M, SvgTransformProps as N, SvgPolylineChild as O, TextElement as P, FontProps as Q, AlignItems as R, SvgElement as S, SvgLineChild as T, LayoutConstraints as U, FlexDirection as V, LayoutNode as W, Color as X, Bounds as Y, ColorStop as Z, StackElement as _, BoxElement as a, StrokeProps as at, SvgChild as b, CustomDrawProps as c, ImageProps as d, LinearGradientDescriptor as et, ProxiedCanvasContextOptions as f, StackAlign as g, RichTextSpan as h, createCanvas as i, Spacing as it, SvgStyleProps as j, SvgProps as k, Element as l, RichTextProps as m, DrawCallCanvas as n, Shadow as nt, BoxProps as o, linearGradient as ot, RichTextElement as p, createCanvasMeasureContext as q, LayoutSize as r, Size as rt, CustomDrawElement as s, radialGradient as st, CanvasOptions as t, RadialGradientDescriptor as tt, ImageElement as u, StackProps as v, SvgGroupChild as w, SvgCircleChild as x, SvgAlign as y, AlignSelf as z };

package/examples/customdraw-basic.ts

@@ -0,0 +1,269 @@
+/**
+ * 示例：CustomDraw 基础用法
+ * 展示如何使用 CustomDraw 进行简单的自定义绘制
+ * 运行: bun examples/customdraw-basic.ts
+ */
+import { Box, CustomDraw, printLayout, Text } from "@codehz/draw-call";
+import { createNodeCanvas } from "@codehz/draw-call/node";
+import { GlobalFonts } from "@napi-rs/canvas";
+import { fileURLToPath } from "bun";
+
+GlobalFonts.registerFromPath(fileURLToPath(import.meta.resolve("@fontpkg/unifont/unifont-15.0.01.ttf")), "unifont");
+
+const canvas = createNodeCanvas({
+  width: 600,
+  height: 1000,
+  pixelRatio: 2,
+});
+
+// 1. 最基础的例子：简单矩形
+const SimpleRect = CustomDraw({
+  width: 150,
+  height: 80,
+  draw(ctx, { width, height }) {
+    ctx.fillStyle = "#667eea";
+    ctx.fillRect(0, 0, width, height);
+    ctx.fillStyle = "#000000";
+    ctx.font = "bold 16px sans-serif";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText("Simple Rect", width / 2, height / 2);
+  },
+});
+
+// 2. 使用 save/restore 的例子：旋转的矩形
+const RotatedRect = CustomDraw({
+  width: 150,
+  height: 80,
+  draw(ctx, { width, height }) {
+    // save/restore 会自动平衡，即使不显式调用也能正确恢复
+    ctx.save();
+    ctx.translate(width / 2, height / 2);
+    ctx.rotate((Math.PI / 4) * 0.3); // 15 度
+    ctx.fillStyle = "#764ba2";
+    ctx.fillRect(-width / 2, -height / 2, width, height);
+    ctx.restore();
+
+    // 恢复后可以正常绘制
+    ctx.fillStyle = "#000000";
+    ctx.font = "16px sans-serif";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText("Rotated", width / 2, height / 2);
+  },
+});
+
+// 3. 圆形进度条（使用子元素）
+const CircleProgress = CustomDraw({
+  width: 140,
+  height: 140,
+  draw(ctx, { width, height, inner }) {
+    const centerX = width / 2;
+    const centerY = height / 2;
+    const radius = Math.min(width, height) / 2 - 8;
+
+    // 绘制背景圆
+    ctx.strokeStyle = "rgba(0, 0, 0, 0.1)";
+    ctx.lineWidth = 8;
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+    ctx.stroke();
+
+    // 绘制进度圆（65% 完成）
+    const percentage = 65;
+    ctx.strokeStyle = "#ff6b6b";
+    ctx.lineCap = "round";
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, radius, -Math.PI / 2, -Math.PI / 2 + (percentage / 100) * Math.PI * 2);
+    ctx.stroke();
+
+    // 调用 inner() 在中央渲染子元素（百分比文本）
+    inner?.();
+  },
+  children: Box({
+    width: "fill",
+    height: "fill",
+    justify: "center",
+    align: "center",
+    children: [
+      Text({
+        content: "65%",
+        font: { size: 24, weight: "bold", family: "unifont" },
+        color: "#ff6b6b",
+      }),
+    ],
+  }),
+});
+
+// 4. 星形图案
+const StarShape = CustomDraw({
+  width: 150,
+  height: 150,
+  draw(ctx, { width, height }) {
+    const centerX = width / 2;
+    const centerY = height / 2;
+    const points = 5;
+    const outerRadius = Math.min(width, height) / 2 - 5;
+    const innerRadius = outerRadius * 0.4;
+
+    ctx.fillStyle = "#ffd93d";
+    ctx.beginPath();
+
+    for (let i = 0; i < points * 2; i++) {
+      const radius = i % 2 === 0 ? outerRadius : innerRadius;
+      const angle = (i * Math.PI) / points - Math.PI / 2;
+      const x = centerX + radius * Math.cos(angle);
+      const y = centerY + radius * Math.sin(angle);
+
+      if (i === 0) {
+        ctx.moveTo(x, y);
+      } else {
+        ctx.lineTo(x, y);
+      }
+    }
+
+    ctx.closePath();
+    ctx.fill();
+
+    // 描边
+    ctx.strokeStyle = "#fa8c16";
+    ctx.lineWidth = 2;
+    ctx.stroke();
+  },
+});
+
+const layout = canvas.render(
+  Box({
+    width: "fill",
+    height: "fill",
+    background: "#f5f7fa",
+    padding: 20,
+    direction: "column",
+    gap: 20,
+    children: [
+      // 标题
+      Text({
+        content: "CustomDraw 基础用法",
+        font: { size: 24, weight: "bold", family: "unifont" },
+        color: "#333333",
+      }),
+
+      // 示例 1：简单矩形
+      Box({
+        direction: "column",
+        gap: 10,
+        children: [
+          Text({
+            content: "1. 简单的自定义绘制",
+            font: { size: 14, weight: "bold", family: "unifont" },
+            color: "#666666",
+          }),
+          Box({
+            background: "#ffffff",
+            border: { radius: 8 },
+            padding: 20,
+            justify: "center",
+            align: "center",
+            children: [SimpleRect],
+          }),
+        ],
+      }),
+
+      // 示例 2：旋转矩形（save/restore 管理）
+      Box({
+        direction: "column",
+        gap: 10,
+        children: [
+          Text({
+            content: "2. Transform 和 Save/Restore 管理",
+            font: { size: 14, weight: "bold", family: "unifont" },
+            color: "#666666",
+          }),
+          Box({
+            background: "#ffffff",
+            border: { radius: 8 },
+            padding: 20,
+            justify: "center",
+            align: "center",
+            children: [RotatedRect],
+          }),
+        ],
+      }),
+
+      // 示例 3：进度条（子元素）
+      Box({
+        direction: "column",
+        gap: 10,
+        children: [
+          Text({
+            content: "3. CustomDraw 包含子元素（inner 函数）",
+            font: { size: 14, weight: "bold", family: "unifont" },
+            color: "#666666",
+          }),
+          Box({
+            background: "#ffffff",
+            border: { radius: 8 },
+            padding: 20,
+            justify: "center",
+            align: "center",
+            children: [CircleProgress],
+          }),
+        ],
+      }),
+
+      // 示例 4：星形（复杂路径）
+      Box({
+        direction: "column",
+        gap: 10,
+        children: [
+          Text({
+            content: "4. 复杂形状（五角星）",
+            font: { size: 14, weight: "bold", family: "unifont" },
+            color: "#666666",
+          }),
+          Box({
+            background: "#ffffff",
+            border: { radius: 8 },
+            padding: 20,
+            justify: "center",
+            align: "center",
+            children: [StarShape],
+          }),
+        ],
+      }),
+
+      // 说明
+      Box({
+        background: "#e8f4ff",
+        border: { radius: 8, color: "#1890ff" },
+        padding: 15,
+        direction: "column",
+        gap: 8,
+        children: [
+          Text({
+            content: "提示：",
+            font: { size: 12, weight: "bold", family: "unifont" },
+            color: "#1890ff",
+          }),
+          Text({
+            content:
+              "CustomDraw 支持直接调用 Canvas API。内部的 save/restore 会自动平衡，transform 也会自动相对处理。使用 inner() 方法可以在自定义绘制中渲染子元素。",
+            font: { size: 12, family: "unifont" },
+            color: "#1890ff",
+            wrap: true,
+            lineHeight: 1.5,
+          }),
+        ],
+      }),
+    ],
+  })
+);
+
+// 保存文件
+const buffer = await canvas.toBuffer("image/png");
+await Bun.write("examples/customdraw-basic.png", buffer);
+console.log("✅ CustomDraw basic demo saved to examples/customdraw-basic.png");
+
+// 打印布局树
+console.log("\n=== Layout Tree ===");
+printLayout(layout);