@jiujue/react-canvas-fiber 2.0.4 → 2.0.6

package/README.md

@@ -1,6 +1,6 @@
 # react-canvas-fiber
 
-[中文](./README.zh.md.md) | English
+[中文](./README.zh.md) | English
 
 A Canvas custom renderer (2D) based on `react-reconciler`, integrated with Yoga Flexbox layout.
 
@@ -19,7 +19,7 @@ Inside this monorepo, it is referenced via pnpm workspace (see the demo).
 ## Usage
 
 ```tsx
-import { Canvas, Rect, Text, View } from '@jiujue/react-canvas-fiber'
+import { Canvas, Image, Rect, Text, View } from '@jiujue/react-canvas-fiber'
 
 export function Example() {
 	return (
@@ -27,17 +27,99 @@ export function Example() {
 			<View style={{ width: 600, height: 400, padding: 16, flexDirection: 'column', gap: 12 }}>
 				<Text text="Hello" style={{ fontSize: 24, fontWeight: 700 }} color="#e6edf7" />
 				<Rect style={{ width: 180, height: 44 }} borderRadius={10} fill="#2b6cff" />
+				<Image
+					src="https://gw.alipayobjects.com/zos/antfincdn/LlvErxo8H9/photo-1503149779833-1de50ebe5f8a.webp"
+					style={{ width: 100, height: 100 }}
+					borderRadius={12}
+					objectFit="cover"
+				/>
 			</View>
 		</Canvas>
 	)
 }
 ```
 
-## Supported Nodes
+## Components
 
-- `View`: layout container, supports `background/borderRadius`
-- `Rect`: rounded rectangle (fill/stroke/lineWidth/borderRadius)
-- `Text`: text (`text/color` + a subset of font styles)
+### `Canvas`
+
+Bridge component that owns a DOM `<canvas>`, creates the custom renderer root, and forwards pointer/wheel events.
+
+Common props:
+
+- `width: number` / `height: number`: logical size (CSS pixels)
+- `dpr?: number` (default `1`): device pixel ratio; the backing canvas uses `width * dpr`, `height * dpr`
+- `clearColor?: string`: clears the whole canvas each frame
+- `fontFamily?: string`, `fontSize?: number`, `fontWeight?: number | string`, `lineHeight?: number`: default text style (used when `Text`/ancestors don't provide them)
+- `style?: CSSProperties`: applied to the DOM `<canvas>` (logical size, display, etc.)
+- `children?: ReactNode`: scene tree
+
+### `View`
+
+Layout container (Yoga) + optional background/border + optional scrolling.
+
+Common props:
+
+- `style?: YogaStyle`: layout box; see Layout section below
+- `background?: string`: background fill color
+- `border?: string`: CSS-like border. Supported forms:
+  - `"<number>px solid <color>"` (e.g. `1px solid rgba(255,255,255,0.2)`)
+  - `"<number> <color>"` (e.g. `2 #fff`)
+  - `"<color>"` (means `1px`, e.g. `#fff`)
+- `borderRadius?: number`
+- `scrollX?: boolean`, `scrollY?: boolean`: enable scrolling + clipping
+- `scrollbarX?: boolean`, `scrollbarY?: boolean`: show scrollbars (default `true` when scrolling is enabled)
+- `scrollbarWidth?: number` (default `10`)
+- `scrollbarInset?: number` (default `6`)
+- `scrollbarTrackColor?: string` (default `rgba(255,255,255,0.12)`)
+- `scrollbarThumbColor?: string` (default `rgba(255,255,255,0.35)`)
+- `onScrollX?: (scrollLeft: number) => void`
+- `onScroll?: (scrollTop: number) => void`
+
+### `Rect`
+
+Rounded rectangle primitive (can also contain children).
+
+Common props:
+
+- `style?: YogaStyle`
+- `fill?: string` (default `#ffffff`)
+- `stroke?: string`
+- `lineWidth?: number` (default `1`)
+- `borderRadius?: number`
+
+### `Text`
+
+Text primitive. Use `text`, do not pass children.
+
+Common props:
+
+- `text: string` (required). `\n` is supported for manual line breaks.
+- `style?: YogaStyle`: supports `fontSize/fontFamily/fontWeight/lineHeight` (also inherited from ancestors / `Canvas` defaults)
+- `color?: string` (default `#ffffff`)
+- `maxWidth?: number`: used by layout measurement to clamp measured width (does not auto-wrap during drawing)
+
+### `Image`
+
+Image primitive. Use `src`, do not pass children.
+
+Common props:
+
+- `src: string` (required)
+- `style?: YogaStyle`
+- `objectFit?: 'cover' | 'contain' | 'fill'` (default `contain`)
+- `borderRadius?: number`
+
+## Events
+
+`View` / `Rect` / `Text` / `Image` support pointer events:
+
+- Hit test respects `pointerEvents?: 'auto' | 'none'` (`none` makes the node transparent to hit testing).
+- Bubble + capture events: `onPointerDown/Move/Up/Cancel`, `onClick`, plus `*Capture` variants.
+- Hover events: `onPointerEnter`, `onPointerLeave` (no capture/bubble).
+- `click` fires on `pointerup` when the down/up target is the same node and `button === 0`.
+
+If an event handler calls `event.preventDefault()`, the DOM event will be `preventDefault()`'d on the underlying `<canvas>` when possible.
 
 ## Layout (Yoga Subset)
 
@@ -47,6 +129,7 @@ Provided mainly via `style`:
 - Flex: `flexDirection/justifyContent/alignItems/flexGrow/flexShrink/flexBasis/flexWrap/gap`
 - Spacing: `padding*`, `margin*`
 - Positioning: `position/top/right/bottom/left`
+- Text style (used by `Text`): `fontSize/fontFamily/fontWeight/lineHeight`
 
 ## Implementation Notes
 

package/README.zh.md

@@ -1,6 +1,6 @@
 # react-canvas-fiber
 
-中文 | [English](./README.en.md)
+中文 | [English](./README.md)
 
 基于 `react-reconciler` 的 Canvas 自定义渲染器（2D），并集成 Yoga Flexbox 布局。
 
@@ -19,7 +19,7 @@ pnpm add @jiujue/react-canvas-fiber
 ## 使用
 
 ```tsx
-import { Canvas, Rect, Text, View } from '@jiujue/react-canvas-fiber'
+import { Canvas, Image, Rect, Text, View } from '@jiujue/react-canvas-fiber'
 
 export function Example() {
 	return (
@@ -27,17 +27,99 @@ export function Example() {
 			<View style={{ width: 600, height: 400, padding: 16, flexDirection: 'column', gap: 12 }}>
 				<Text text="Hello" style={{ fontSize: 24, fontWeight: 700 }} color="#e6edf7" />
 				<Rect style={{ width: 180, height: 44 }} borderRadius={10} fill="#2b6cff" />
+				<Image
+					src="https://gw.alipayobjects.com/zos/antfincdn/LlvErxo8H9/photo-1503149779833-1de50ebe5f8a.webp"
+					style={{ width: 100, height: 100 }}
+					borderRadius={12}
+					objectFit="cover"
+				/>
 			</View>
 		</Canvas>
 	)
 }
 ```
 
-## 已支持的节点
+## 组件与属性
 
-- `View`：布局容器，可设置 `background/borderRadius`
-- `Rect`：圆角矩形（fill/stroke/lineWidth/borderRadius）
-- `Text`：文本（text/color + font style 子集）
+### `Canvas`
+
+桥接组件：负责创建/管理 DOM `<canvas>`、初始化自定义 renderer root，并转发 pointer/wheel 事件。
+
+常用 props：
+
+- `width: number` / `height: number`：逻辑尺寸（CSS 像素）
+- `dpr?: number`（默认 `1`）：设备像素比；真实像素尺寸为 `width * dpr`、`height * dpr`
+- `clearColor?: string`：每帧清屏颜色
+- `fontFamily?: string`、`fontSize?: number`、`fontWeight?: number | string`、`lineHeight?: number`：文本默认样式（当 `Text`/祖先未提供时生效）
+- `style?: CSSProperties`：应用到 DOM `<canvas>` 的样式（逻辑尺寸、display 等）
+- `children?: ReactNode`：场景树
+
+### `View`
+
+布局容器（Yoga）+ 可选背景/边框 + 可选滚动。
+
+常用 props：
+
+- `style?: YogaStyle`：布局样式，见下方「布局（Yoga 子集）」
+- `background?: string`：背景填充色
+- `border?: string`：类似 CSS 的 border，支持：
+  - `"<number>px solid <color>"`（例如 `1px solid rgba(255,255,255,0.2)`）
+  - `"<number> <color>"`（例如 `2 #fff`）
+  - `"<color>"`（等价于 `1px`，例如 `#fff`）
+- `borderRadius?: number`
+- `scrollX?: boolean`、`scrollY?: boolean`：开启滚动与裁剪
+- `scrollbarX?: boolean`、`scrollbarY?: boolean`：是否显示滚动条（开启滚动时默认 `true`）
+- `scrollbarWidth?: number`（默认 `10`）
+- `scrollbarInset?: number`（默认 `6`）
+- `scrollbarTrackColor?: string`（默认 `rgba(255,255,255,0.12)`）
+- `scrollbarThumbColor?: string`（默认 `rgba(255,255,255,0.35)`）
+- `onScrollX?: (scrollLeft: number) => void`
+- `onScroll?: (scrollTop: number) => void`
+
+### `Rect`
+
+圆角矩形图元（也可以作为容器包含 children）。
+
+常用 props：
+
+- `style?: YogaStyle`
+- `fill?: string`（默认 `#ffffff`）
+- `stroke?: string`
+- `lineWidth?: number`（默认 `1`）
+- `borderRadius?: number`
+
+### `Text`
+
+文本图元。使用 `text`，不要传 children。
+
+常用 props：
+
+- `text: string`（必填）。支持 `\n` 手动换行。
+- `style?: YogaStyle`：支持 `fontSize/fontFamily/fontWeight/lineHeight`（也会从祖先 / `Canvas` 默认值继承）
+- `color?: string`（默认 `#ffffff`）
+- `maxWidth?: number`：用于布局测量时限制测得的宽度（绘制阶段不会自动换行）
+
+### `Image`
+
+图片图元。使用 `src`，不要传 children。
+
+常用 props：
+
+- `src: string`（必填）
+- `style?: YogaStyle`
+- `objectFit?: 'cover' | 'contain' | 'fill'`（默认 `contain`）
+- `borderRadius?: number`
+
+## 事件
+
+`View` / `Rect` / `Text` / `Image` 支持 pointer 事件：
+
+- 命中测试受 `pointerEvents?: 'auto' | 'none'` 影响（`none` 会让节点对命中测试“透明”）。
+- 支持冒泡 + 捕获：`onPointerDown/Move/Up/Cancel`、`onClick`，以及对应的 `*Capture`。
+- Hover 事件：`onPointerEnter`、`onPointerLeave`（不走捕获/冒泡）。
+- `click` 会在 `pointerup` 时触发：按下与抬起命中的是同一节点且 `button === 0`。
+
+如果在事件回调里调用 `event.preventDefault()`，底层 `<canvas>` 对应的 DOM 事件会尽可能执行 `preventDefault()`。
 
 ## 布局（Yoga 子集）
 
@@ -47,6 +129,7 @@ export function Example() {
 - Flex：`flexDirection/justifyContent/alignItems/flexGrow/flexShrink/flexBasis/flexWrap/gap`
 - 边距：`padding*`、`margin*`
 - 定位：`position/top/right/bottom/left`
+- 文本样式（供 `Text` 使用）：`fontSize/fontFamily/fontWeight/lineHeight`
 
 ## 实现说明
 

package/dist/index.cjs

@@ -94,14 +94,56 @@ function drawRoundedRect(ctx, x, y, w, h, r) {
 function rectsIntersect(ax, ay, aw, ah, bx, by, bw, bh) {
   return ax < bx + bw && ax + aw > bx && ay < by + bh && ay + ah > by;
 }
+function resolveBorder(value) {
+  if (typeof value !== "string") return null;
+  const raw = value.trim();
+  if (!raw) return null;
+  const normalized = raw.replace(/\s+/g, " ");
+  const match = normalized.match(/^([0-9]*\.?[0-9]+)(px)?\s+(?:solid\s+)?(.+)$/i);
+  if (match) {
+    const width = Number(match[1]);
+    const color = match[3]?.trim();
+    if (Number.isFinite(width) && width > 0 && color) return { width, color };
+    return null;
+  }
+  const withoutSolid = normalized.replace(/\bsolid\b/gi, " ").replace(/\s+/g, " ").trim();
+  const match2 = withoutSolid.match(/^([0-9]*\.?[0-9]+)(px)?\s+(.+)$/i);
+  if (match2) {
+    const width = Number(match2[1]);
+    const color = match2[3]?.trim();
+    if (Number.isFinite(width) && width > 0 && color) return { width, color };
+    return null;
+  }
+  if (/^[0-9]/.test(withoutSolid)) return null;
+  if (!withoutSolid) return null;
+  return { width: 1, color: withoutSolid };
+}
+function drawBorder(ctx, x, y, w, h, radius, border) {
+  if (!Number.isFinite(border.width) || border.width <= 0) return;
+  const inset = border.width / 2;
+  const bw = w - border.width;
+  const bh = h - border.width;
+  if (bw <= 0 || bh <= 0) return;
+  ctx.save();
+  ctx.strokeStyle = border.color;
+  ctx.lineWidth = border.width;
+  drawRoundedRect(ctx, x + inset, y + inset, bw, bh, Math.max(0, radius - inset));
+  ctx.stroke();
+  ctx.restore();
+}
 function drawNode(state, node, offsetX, offsetY) {
   const { ctx } = state;
   const x = offsetX + node.layout.x;
   const y = offsetY + node.layout.y;
   const w = node.layout.width;
   const h = node.layout.height;
+  let viewBorder = null;
+  let viewRadius = 0;
+  let viewIsScroll = false;
   if (node.type === "View") {
     const background = node.props.background;
+    viewBorder = resolveBorder(node.props.border);
+    viewRadius = node.props.borderRadius ?? 0;
     const scrollX = !!node.props?.scrollX;
     const scrollY = !!node.props?.scrollY;
     const scrollLeft = scrollX ? node.scrollLeft ?? 0 : 0;
@@ -117,14 +159,14 @@ function drawNode(state, node, offsetX, offsetY) {
     const maxScrollLeft = Math.max(0, contentWidth - w);
     const maxScrollTop = Math.max(0, contentHeight - h);
     if (background) {
-      const radius = node.props.borderRadius ?? 0;
       ctx.save();
       ctx.fillStyle = background;
-      drawRoundedRect(ctx, x, y, w, h, radius);
+      drawRoundedRect(ctx, x, y, w, h, viewRadius);
       ctx.fill();
       ctx.restore();
     }
     if (scrollX || scrollY) {
+      viewIsScroll = true;
       ctx.save();
       ctx.beginPath();
       ctx.rect(x, y, w, h);
@@ -201,6 +243,7 @@ function drawNode(state, node, offsetX, offsetY) {
         ctx.fill();
         ctx.restore();
       }
+      if (viewBorder) drawBorder(ctx, x, y, w, h, viewRadius, viewBorder);
       return;
     }
   }
@@ -240,6 +283,7 @@ function drawNode(state, node, offsetX, offsetY) {
     const { imageInstance } = node;
     if (imageInstance && imageInstance.complete && imageInstance.naturalWidth > 0) {
       const objectFit = node.props.objectFit || "contain";
+      const radius = node.props.borderRadius ?? 0;
       const srcW = imageInstance.naturalWidth;
       const srcH = imageInstance.naturalHeight;
       let dstX = x;
@@ -267,7 +311,7 @@ function drawNode(state, node, offsetX, offsetY) {
       }
       ctx.save();
       ctx.beginPath();
-      drawRoundedRect(ctx, x, y, w, h, 0);
+      drawRoundedRect(ctx, x, y, w, h, radius);
       ctx.clip();
       ctx.drawImage(imageInstance, srcX, srcY, finalSrcW, finalSrcH, dstX, dstY, dstW, dstH);
       ctx.restore();
@@ -276,6 +320,9 @@ function drawNode(state, node, offsetX, offsetY) {
   for (const child of node.children) {
     drawNode(state, child, x, y);
   }
+  if (node.type === "View" && !viewIsScroll && viewBorder) {
+    drawBorder(ctx, x, y, w, h, viewRadius, viewBorder);
+  }
 }
 function drawTree(root, ctx, dpr, clearColor, defaults) {
   const w = ctx.canvas.width;