@zhaoxiangjun/base44-konva 项目索引

这是 Base44 React App 和本地 React 项目共用的 Konva 画布编辑器组件库。
本项目只提供前端画布编辑组件、Hook、类型和工具函数，不负责 Base44 SDK、后端接口、文件上传、密钥、鉴权或业务数据请求。

package: @zhaoxiangjun/base44-konva
current: 1.1.0

1. 先看哪份文档

| 你是谁 / 你要做什么 | 应该看 | |---------------------|--------| | Base44 App 开发者 | docs/base44-usage.md | | Base44 AI Controls / AI Agent | docs/base44-usage.md | | 想知道组件怎么 import、props 怎么传 | docs/base44-usage.md | | 想复用 stage 数据工具、节点工具或 Hook | docs/base44-usage.md | | AI Agent 要快速定位修改入口 | docs/ai-development-guide.md | | 判断能力应该放在哪个公共模块 | docs/reuse-map.md | | 本地运行和验证 playground | docs/local-display.md | | 维护、构建、发布 npm 包 | docs/npm-package.md | | 查看当前项目功能与本轮修改内容 | docs/project-status.md | | 进入项目收尾审查 | docs/final-review-checklist.md | | 查看最近一次收尾结论 | docs/final-review-report.md | | 查看 Konva 编辑器功能设计 | docs/fun/konva-editor.md | | 查看工程修改记录 | docs/logs/ |

2. 快速安装

Base44 App 通过 npm registry 安装，不使用 git 依赖。

{
  "dependencies": {
    "@zhaoxiangjun/base44-konva": "^1.1.0",
    "@zhaoxiangjun/base44-ui": "^1.0.1"
  }
}

入口文件引入样式：

import "@zhaoxiangjun/base44-ui/styles.css";
import "@zhaoxiangjun/base44-konva/styles.css";

组件引入：

import { KonvaCanvasEditor } from "@zhaoxiangjun/base44-konva";

更完整的组件清单、props、类型、Hook 和工具函数见：

docs/base44-usage.md

3. 项目边界

可以包含：
React Konva 画布组件
前端编辑 Hook
组件类型定义
舞台数据工具函数
Konva 节点工具函数
playground 验证页面

不应该包含：
base44.entities 调用
base44.auth 调用
base44.functions.invoke 调用
外部后端接口请求
文件上传实现
密钥、Token、API Key
业务专属工程保存逻辑

业务逻辑应由使用方通过 props、callbacks、当前 App 的 src/api / src/hooks / src/lib 或 Base44 Backend Functions 接入。

4. 能力分组

Editor:
  KonvaCanvasEditor

Stage:
  KonvaStageCanvas / KonvaCanvasObject / KonvaTextObject / KonvaImageObject
  KonvaSelectionTransformer / KonvaStageRulers

Toolbar / Inspector:
  KonvaCanvasToolbar / KonvaInspectorPanel

Preview / Picker:
  KonvaPreviewCanvas / KonvaColorPicker

Hooks:
  useControllableStageValue / useContainerSize / useKonvaEditorCommands
  useKonvaImage / useKonvaNodeRegistry / useKonvaObjectNode / useKonvaObjectInteractions

Stage Data Utils:
  createDefaultStageValue / createRectElement / createTextElement / createImageElement
  addStageElement / changeStageElement / selectStageElement / getSelectedElement
  duplicateSelectedStageElement / deleteSelectedStageElement / moveSelectedStageElementOrder

Konva Node Utils:
  readNodeTransformPatch / readBoundedNodeTransformPatch / shouldKeepTransformBox
  isStageBlankTarget / clampNodeToStage

Shared Utils:
  createStageDebugInfo / createKonvaCanvasObjectProps / createFillPatch / createTextPatch
  calculateStageLayout / getStageLayoutBoundary
  drawKonvaPreviewCanvas / exportKonvaPreviewCanvasPng
  normalizeHexColor / hexToRgb / rgbToHex / hexToHsv / hsvToHex
  clampNumber / clampInteger

LED Playback:
  decodeDeviceProgram / encodeDeviceProgram / LedPlayProgramPlayer
  NovaPlaybackSimulator / resolveLedMoveTiming
  getAllLedMoveModeSpecs / renderLedMotionFrame

HZHX Font:
  HxFontBin / HxFontRepository / renderHxFontText / paintHxFontResult
  scanHxFontFaces / listAvailableHxFontFaces

5. 本地开发

npm install
npm run dev
npm run typecheck
npm run build
npm pack --dry-run

发布 npm 前必须查看：

docs/npm-package.md

本地 playground 验证方式见：

docs/local-display.md

当前项目功能、已实现内容和本轮修改说明见：

docs/project-status.md

6. 修改记录

所有重要调整都记录在：

docs/logs/

新增组件、修改公共 API、调整发布流程、重构公共复用逻辑或改变数据结构时，都需要新增或更新对应日志。