From 1c832988a2d31ea6f7a56ea249dd19038831b908 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 02:21:27 +0800 Subject: [PATCH] docs(canvas): explain legacy editor tools and subgraph interactions --- src/components/canvas/graph-canvas.tsx | 84 ++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/src/components/canvas/graph-canvas.tsx b/src/components/canvas/graph-canvas.tsx index 716a902..14c9bf4 100644 --- a/src/components/canvas/graph-canvas.tsx +++ b/src/components/canvas/graph-canvas.tsx @@ -1,3 +1,9 @@ +/** + * 旧版主画布的界面装配与交互控制。useCanvasTree拥有旧快照、writer、历史和子图事务，组件把其投影交给ReactFlow。 + * 本地state管理工具、模式、菜单与提示，refs保存拖动/连线起点及文件选择上下文；真实上传与演示Data URL分别处理。 + * 节点/连线组件通过Context调用适配动作，不直接修改投影；子图归属、端口连线和解散优先使用服务端能力与事务。 + * 迁移门闩暂停旧编辑和创作入口，给迁移协调组件提供检查、保存排空与备份；本文件不自行切换到新版engine。 + */ "use client"; import { useImageUploads } from "./use-image-uploads"; import {LegacyCanvasMigration} from "./legacy-canvas-migration"; @@ -41,15 +47,21 @@ import type { NodeTransform } from "@/lib/canvas-geometry"; import { MaterialNode, NodeEditing } from "./material-node"; import styles from "./canvas.module.css"; +/** 旧边统一使用可编辑贝塞尔组件，节点按旧type名称分派；类型映射本身不持有元素实例数据。 */ const edgeTypes = { default: CanvasEdge }; +/** 图标面板延迟在客户端加载，避免首屏加载目录面板及其交互代码；加载中提供可访问状态。 */ const IconPicker = dynamic(() => import("./icon-picker").then((module) => module.IconPicker), { ssr: false, loading: () =>
正在加载图标面板…
}); +/** ReactFlow type到节点展示组件的固定表，须与makeCanvasNode/投影生成的type保持一致。 */ const nodeTypes = { material: MaterialNode, plainText: PlainTextNode, icon: IconNode, frame: FrameNode, plainImage: PlainImageNode }; +/** 每个挂载对应一个board身份，初始快照/草稿只在useState初始化时采用；切画布应由上层key重挂载。 */ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: CanvasSnapshot; migration?:LegacyMigrationContext }) { const flow = useReactFlow(); const { zoom } = useViewport(); const reduceMotion = useReducedMotion(); const storageKey = canvasStorageKey(board.workspace_id, board.id); + // 服务端快照优先，另有不同本地内容则等待恢复选择；无快照可直接用草稿。 + // 视口独立读本地键并限制范围，损坏视口不阻断文档；草稿解码失败回退快照/空文档并提示。 const [initial] = useState(() => { try { const local = readLocalRecovery(localStorage, storageKey, snapshot); @@ -62,6 +74,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: } catch { return { document: snapshot?.document || emptyCanvas(), recovery: null, error: "无法读取此浏览器的图谱草稿，可通过导入恢复备份。" }; } }); + // 工具与变换模式是界面状态，不放入文档；draggedIds仅驱动成员预览，membershipNotice短暂展示结果。 const [tool, setTool] = useState<"select" | "hand">("select"); const [error, setError] = useState(initial.error); const feedback = useContext(FeedbackContext); @@ -72,26 +85,35 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: const [rotating, setRotating] = useState(null); const [draggedIds, setDraggedIds] = useState([]); const [membershipNotice, setMembershipNotice] = useState(""); + // 防节点拖动与多选拖动回调重复进入；起点按显示ID保存，连线屏幕起点用于区分点击与拉出新分支。 const dragSession = useRef<"idle" | "active" | "finishing">("idle"); const dragOrigins = useRef(new Map()); const draggingFrame = useRef(false); const connectionStart = useRef<{ id: string; direction: NodeDirection; point: XYPosition } | null>(null); + // 图片分支先保留源节点/方向/位置，等文件选择返回；cancel事件要清它，不能沿用上次创建意图。 const pendingImage = useRef(null); + /** 稳定关闭回调供Portal菜单与画布事件共用，避免菜单因每次渲染重新安装监听。 */ const closeBranch = useCallback(() => setBranchRequest(null), []); const imageKind = useRef<"image" | "plain-image">("image"); const imageInput = useRef(null); const projectInput = useRef(null); const [recovery, setRecovery] = useState(initial.recovery); + // 根恢复待决时暂停保存；tree负责真实owner文档，UI显示节点来自其树投影。子图恢复按Map首项逐个处理。 const tree = useCanvasTree(board.id, board.workspace_id, initial.document, snapshot, Boolean(recovery), board.parent_board_id, migration); const childRecovery = [...tree.recoveries][0]; + /** 下载单份内存文档JSON备份，稍后释放Blob URL；不修改草稿选择，也不保证包含所有子图。 */ const downloadDraft = (document: import("@/lib/canvas").CanvasDocument) => { const url = URL.createObjectURL(new Blob([JSON.stringify(document, null, 2)], { type: "application/json" })); const link = window.document.createElement("a"); link.href = url; link.download = "画布本地草稿.json"; link.click(); setTimeout(() => URL.revokeObjectURL(url), 1000); }; const sync = tree; + // snapshot存在才执行真实AI；state.present组合根元数据与整树显示节点/边，不能把它当单board持久快照。 const ai = useCanvasAI(board.workspace_id, board.id, !!snapshot, tree); const state = { present: { ...tree.rootDocument, nodes: tree.views.nodes, edges: tree.views.edges } }; const treeRef = useRef(tree); treeRef.current = tree; + // 上传完成回调通过treeRef定位当前归属，并更新当前文档与历史；job.owner可能已不再是最新owner。 const uploads = useImageUploads(board.workspace_id, (job, asset) => treeRef.current.resolveImageUpload(job.node.id, asset,{width:job.node.width!,height:job.node.height!})); const imageUploading = demoImageUploading; + // 文件导入等待期间的迁移检查标记；这不是通用导入队列，也不提供并发文件事务锁。 const ioActive=useRef(false); + // 上传任务与文档都可能变化：按pendingUpload重新找owner，补资源或纯图片默认尺寸，避免移动/撤销后遗漏占位。 useEffect(() => { const current = treeRef.current; for (const job of uploads.jobs) { @@ -102,38 +124,48 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: if (node.data.kind==="plain-image"&&node.width===320&&node.height===240&&(job.node.width!==320||job.node.height!==240)) current.resolveImageUpload(job.node.id,undefined,{width:job.node.width!,height:job.node.height!}); } }, [uploads.jobs,tree.documents]); + /** undo/redo走异步树历史接口并显示失败，其余动作走根document reducer；不把服务端事务撤销当普通reducer动作。 */ function dispatch(action: CanvasAction) { if (action.type === "undo" || action.type === "redo") { void treeRef.current[action.type]().catch((error) => setError(error.message)); return; } treeRef.current.dispatch(action); } + // 浏览器文件选择取消不触发普通onChange，单独监听cancel清理待建图片分支；卸载拆监听。 useEffect(() => { const input = imageInput.current; + /** 取消本次选择意图，不删除已经存在的图片节点或中止已启动上传。 */ const cancel = () => { pendingImage.current = null; }; input?.addEventListener("cancel", cancel); return () => input?.removeEventListener("cancel", cancel); }, []); const { nodes: displayNodes, edges } = state.present; + // 对成员任务保护节点关闭拖动/删除/连接；tree.update内部仍保护相应数据，界面禁用不是唯一护栏。 const nodes = displayNodes.map((node) => { const ref = tree.views.nodeRefs.get(node.id); const blocked = ref && tree.protectedNodes(ref.boardId).has(ref.id); return blocked ? { ...node, draggable: false, deletable: false, connectable: false } : node; }); + /** 上传任务的本地nodeID映射到当前场景ID；尚无投影时按根/原owner构造兼容显示ID。 */ const uploadDisplayID = (job: typeof uploads.jobs[number]) => [...tree.views.nodeRefs].find(([,ref])=>ref.id===job.node.id)?.[0] || displayID(board.id,job.owner,job.node.id); + // 预览URL按显示ID提供；正式图片onLoad再映射回job，上传完成的任务才回收本地URL。 const imagePreviews = { sources: new Map(uploads.jobs.map((job) => [uploadDisplayID(job),job.localURL])), loaded: (id: string) => { const job = uploads.jobs.find((job) => uploadDisplayID(job)===id);if(job) uploads.loaded(job.node.id); } }; + // 从场景节点派生分区名称、已有frameId计数与本次拖入/拖出候选，只作显示，不在此改变owner。 const frameFeedback = useMemo(() => { const names = new Map(nodes.filter((node) => node.data.kind === "frame").map((node) => [node.id, node.data.title])); const counts = new Map(); for (const node of nodes) if (node.data.frameId) counts.set(node.data.frameId, (counts.get(node.data.frameId) || 0) + 1); return { names, counts, drops: frameDropFeedback(nodes, draggedIds) }; }, [nodes, draggedIds]); + // 成员提示四秒后清理；重新提示重置计时器，卸载取消。 useEffect(() => { if (!membershipNotice) return; const timer = setTimeout(() => setMembershipNotice(""), 4000); return () => clearTimeout(timer); }, [membershipNotice]); + // 全局反馈可用时把本地错误转成稳定ID通知并清本地error；无Provider时保留底部内联提示。 useEffect(() => { if (!feedback || !error) return; const id = `canvas:${board.id}:error`; notify({ id, level: "error", title: error }); setError(""); }, [feedback, error, board.id]); + // 成员通知使用board级稳定ID，内容变化替换旧通知，清理时显式dismiss。 useEffect(() => { if (!feedback || !membershipNotice) return; const id = `canvas:${board.id}:membership`; @@ -141,29 +173,40 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: return () => dismissNotification(id); }, [feedback, membershipNotice, board.id]); const duration = reduceMotion ? 0 : 180; + /** 视口派发给根并独立写本地键；存储失败不打断浏览，内容writer自行判断是否需要服务端保存。 */ const rememberViewport = (viewport: import("@xyflow/react").Viewport) => { treeRef.current.dispatch({ type: "viewport", viewport }); try { localStorage.setItem(storageKey + ":viewport", JSON.stringify(viewport)); } catch { /* View changes do not require server writes. */ } }; + /** 工具栏视口动画完成后保存实际视口；错误转界面提示，不提前记录尚未完成的目标值。 */ const changeView = (operation: () => Promise) => { void operation().then(() => rememberViewport(flow.getViewport())).catch((error) => setError(error.message)); }; + // latest保留当前显示几何，拖动结束基于最新节点计算成员反馈，避免只使用开始时的闭包。 const latest = useRef(state.present); latest.current = state.present; + /** 显示ID的选择交tree解析owner；稳定回调通过treeRef避免每次文档更新重建编辑上下文。 */ const select = useCallback((id: string) => treeRef.current.select(id), []); + /** 对目标owner建立checkpoint，把后续连续编辑归到同一撤销起点；缺目标时使用根board。 */ const beginEdit = useCallback((id?: string) => { const current = treeRef.current; const ref = id ? current.views.nodeRefs.get(id) || current.views.edgeRefs.get(id) : undefined; current.dispatch({ type: "checkpoint" }, ref?.boardId || board.id); }, [board.id]); + /** 正文动作按投影ID定位原节点，reducer处理文本值与历史。 */ const edit = useCallback((id: string, text: string) => treeRef.current.nodeAction(id, (id) => ({ type: "edit", id, text })), []); + /** 打开分支类型菜单并退出变换模式，point用于屏幕定位。 */ const branch = useCallback((id: string, direction: NodeDirection, point: XYPosition) => { setBranchRequest({ id, direction, point }); setRotating(null); setResizing(null); }, []); + /** 将场景位置减owner原点再除scale，宽高也除scale；旋转等其余字段直接交旧transform动作。 */ const transform = useCallback((id: string, transform: NodeTransform) => { const ref = treeRef.current.views.nodeRefs.get(id); if (!ref) return; treeRef.current.nodeAction(id, (id) => ({ type: "transform", id, transform: { ...transform, ...(transform.position ? { position: { x: (transform.position.x - ref.origin.x) / ref.scale, y: (transform.position.y - ref.origin.y) / ref.scale } } : {}), ...(transform.width !== undefined ? { width: transform.width / ref.scale, height: transform.height! / ref.scale } : {}) } })); }, []); + /** 样式适配只构造旧style动作，具体字段合并由reducer处理。 */ const style = useCallback((id: string, style: TextStyle, fontSize?: number) => treeRef.current.nodeAction(id, (id) => ({ type: "style", id, style, fontSize })), []); + /** 节点名称通过owner映射更新，避免将显示复合ID当持久ID。 */ const rename = useCallback((id: string, title: string) => treeRef.current.nodeAction(id, (id) => ({ type: "rename-node", id, title })), []); + /** 分区属性以replace提交；折叠切换从已保存expanded/collapsedSize或默认值恢复尺寸，并写node与style。 */ const frame = useCallback((id: string, patch: { title?: string; labelMode?: FrameLabelMode; presentation?: import("@/lib/canvas-v2").FramePresentation }) => { const current = treeRef.current, ref = current.views.nodeRefs.get(id); if (!ref) return; const document = current.documents.get(ref.boardId)!; @@ -174,7 +217,9 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: return { ...node, ...(size ? { ...size, style: { ...node.style, ...size } } : {}), data: { ...node.data, ...patch } }; }) } }, ref.boardId); }, []); + // 注入节点动作及本地旋转/拉伸模式，两模式互斥；旧版接口没有新版手势token租约。 const editing = useMemo(() => ({ begin: beginEdit, select, edit, branch, transform, style, rename, frame, workspace: board.workspace_id, schema: 2 as const, rotating, resizing, resize: (id: string | null) => { setResizing(id); setRotating(null); }, rotate: (id: string | null) => { setRotating(id); setResizing(null); } }), [beginEdit, select, edit, branch, transform, style, rename, frame, rotating, resizing, board.workspace_id, state.present.schema_version]); + /** 在源owner文档创建节点与连线，at从场景坐标转局部；发布后尝试把视口移向新节点，异常留作提示。 */ function createBranch(request: BranchRequest, kind: "text" | "image" | "script", src?: string) { try { const document = branchCanvasNode(tree.documents.get(tree.views.nodeRefs.get(request.id)!.boardId)!, tree.views.nodeRefs.get(request.id)!.id, request.direction, kind, src, request.at ? { x: (request.at.x - tree.views.nodeRefs.get(request.id)!.origin.x) / tree.views.nodeRefs.get(request.id)!.scale, y: (request.at.y - tree.views.nodeRefs.get(request.id)!.origin.y) / tree.views.nodeRefs.get(request.id)!.scale } : undefined); @@ -184,11 +229,13 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: setBranchRequest(null); } catch (error) { setError(error instanceof Error ? error.message : "无法创建节点。"); } } + /** 图片分支需要文件选择才能创建，先保存request并关菜单；文本/脚本立即创建。 */ function chooseBranch(kind: "text" | "image" | "script") { if (!branchRequest) return; if (kind === "image") { pendingImage.current = branchRequest; imageKind.current = "image"; setBranchRequest(null); imageInput.current?.click(); } else createBranch(branchRequest, kind); } + /** 无有效目标的连接拖动若移动至少5px并落到空白pane，且源仍选中，则在落点打开分支菜单。 */ const connectionEnd: OnConnectEnd = (event, connection) => { const start = connectionStart.current; connectionStart.current = null; @@ -201,11 +248,13 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: setBranchRequest({ id: start.id, direction: start.direction, point: { x: point.clientX, y: point.clientY }, at }); }; + /** 按窗口中心转换为场景点并加六档偏移，减少连续添加完全重叠；不是按编辑器容器中心计算。 */ const center = () => { const point = flow.screenToFlowPosition({ x: window.innerWidth / 2, y: window.innerHeight / 2 }); const offset = (nodes.length % 6) * 18; return { x: point.x - 130 + offset, y: point.y - 80 + offset }; }; + /** 根节点上限500；真实分区走subgraphs命令创建子画布，其它节点本地加入，演示frame也走本地模型。 */ function addNode(kind: CanvasNode["data"]["kind"], src?: string, size?: { width: number; height: number }, title?: string) { if (tree.rootDocument.nodes.length >= 500) { setError("当前图谱已达到 500 个节点，请新建图谱继续创作。"); return; } const node = makeCanvasNode(kind, center(), src); @@ -218,6 +267,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: dispatch({ type: "nodes", changes: [{ type: "add", item: node }] }); setTool("select"); } + /** 一次replace插入三张预填卡片和两条连线，预留三个节点容量并切回选择工具；不触发AI生成。 */ function addTemplate() { if (tree.rootDocument.nodes.length > 497) { setError("当前图谱没有足够空间插入模板。"); return; } const position = center(); @@ -233,6 +283,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: ] } }); setTool("select"); } + /** idle才建立checkpoint与拖动起点；有frame参与则不显示普通拖入预览，防止移动分区误收纳覆盖内容。 */ function beginDrag(node: CanvasNode, dragged: CanvasNode[]) { if (dragSession.current !== "idle") return; dragSession.current = "active"; tree.setDragging(true); beginEdit(node.id); closeBranch(); setRotating(null); setResizing(null); @@ -242,6 +293,8 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: setDraggedIds(draggingFrame.current ? [] : [...dragOrigins.current.keys()]); setMembershipNotice(""); } + /** 只结束active拖动，先清拖动/保存暂停标记，再按真实位移计算归属；真实子图与旧frameId归属分路处理。 + * 异步移动失败保留错误提示，不宣称所有跨分区步骤一起回滚。 */ async function finishDrag(node: CanvasNode, dragged: CanvasNode[]) { if (dragSession.current !== "active") return; const origins = new Map(dragOrigins.current); @@ -252,19 +305,23 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: if (ids.length) { const positions = new Map(items.map((item) => [item.id, item.position])); const dropped = latest.current.nodes.map((item) => positions.has(item.id) ? { ...item, position: positions.get(item.id)! } : item); + // 先生成“加入/移出”展示文案；实际owner由下面的真实子图路径重新判定，成功后才显示结果通知。 const changed = frameDropFeedback(dropped, ids).filter((item) => item.from !== item.to); const messages = changed.map((item) => item.to ? `已加入「${frameFeedback.names.get(item.to) || "分区"}」` : `已移出「${frameFeedback.names.get(item.from!) || "分区"}」`); const notice = messages.length ? `${changed.length > 1 ? `${changed.length} 项内容：` : ""}${[...new Set(messages)].join("；")}` : ""; if (snapshot && tree.rootDocument.schema_version === 2) { try { + // 按source/target分组，同组节点一起迁移；候选分区按面积升序，优先最小包围分区。 const byOwner = new Map(); const parents = subgraphParents(tree.current.current); for (const item of items.filter((item) => ids.includes(item.id))) { const ref = tree.views.nodeRefs.get(item.id); if (!ref) continue; const center = { x: item.position.x + (item.width || 260) / 2, y: item.position.y + (item.height || 200) / 2 }; + /** 沿子图父链防环检查，不能把分区入口移动进自己的后代，形成结构循环。 */ const inMovingSubtree = (child: string) => { const seen = new Set(); let cursor: string | undefined = child; while (cursor && !seen.has(cursor)) { if (cursor === item.data.subgraph?.boardId) return true; seen.add(cursor); cursor = parents.get(cursor)?.boardId; } return false; }; const candidates = dropped.filter((candidate) => candidate.id !== item.id && candidate.data.subgraph && !inMovingSubtree(candidate.data.subgraph.boardId) && center.x >= candidate.position.x && center.y >= candidate.position.y && center.x <= candidate.position.x + (candidate.width || 640) && center.y <= candidate.position.y + (candidate.height || 400)).sort((a, b) => (a.width || 640) * (a.height || 400) - (b.width || 640) * (b.height || 400)); const target = candidates[0]?.data.subgraph?.boardId || (ref.boardId === board.id ? board.id : parents.get(ref.boardId)?.boardId) || board.id; + // 未上传且满足条件的占位图片先走本地迁移；其它节点需要服务端成员事务。 if (target !== ref.boardId && tree.current.current.get(ref.boardId)?.nodes.find((node)=>node.id===ref.id)?.pendingUpload) { tree.movePendingImage(ref.boardId,target,ref.id);continue; } @@ -272,6 +329,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: const key = ref.boardId + "/" + target, group = byOwner.get(key) || { ids: [], target }; group.ids.push(ref.id); byOwner.set(key, group); } } + // 不同owner组并行提出任务，每组沿父子路径逐跳等待；tree内部队列仍串行发送成员请求。 await Promise.all([...byOwner].map(async ([key, group]) => { let source = key.split("/")[0]; for (const hop of subgraphMovePath(tree.current.current, source, group.target)) { @@ -287,10 +345,12 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: } } } + /** 先把入口端口解析成实际内部节点；同owner本地加边，跨owner优先服务端connections事务，缺能力时尝试暴露端口适配。 */ async function connect(connection: Connection) { const source = tree.views.nodeRefs.get(connection.source), target = tree.views.nodeRefs.get(connection.target); if (!source || !target) return; try { + /** 按深度计数0—8解析子图入口，每层必须找到明确port映射；仍未到实际节点或缺端口则拒绝。 */ const resolve = async (ref: typeof source, handle: string | null | undefined): Promise<{ boardId: string; id: string; handle: string }> => { let endpoint = { boardId: ref!.boardId, id: ref!.id, handle: handle || "right" }; for (let depth = 0; depth <= 8; depth++) { @@ -303,6 +363,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: throw new Error("subgraph_cycle"); }; const realSource = await resolve(source, connection.sourceHandle), realTarget = await resolve(target, connection.targetHandle || "left"); + // 同一canvas快照可直接加边；跨canvas需要共同上层/边界端口关系，不能把显示端点直接写进任一子快照。 if (realSource.boardId === realTarget.boardId) { const document = tree.current.current.get(realSource.boardId)!; tree.dispatch({ type: "replace", document: { ...document, schema_version: 2, edges: addEdge({ id: crypto.randomUUID(), source: realSource.id, target: realTarget.id, sourceHandle: realSource.handle, targetHandle: realTarget.handle }, document.edges) } }, realSource.boardId); @@ -316,11 +377,13 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: return; } } + // 兼容路径由exposedConnection提供可寻址端点与owner，失败提示跨画布连接暂不可用。 const exposed = exposedConnection(tree.current.current, realSource, realTarget); const document = tree.current.current.get(exposed.boardId)!; tree.dispatch({ type: "replace", document: { ...document, schema_version: 2, edges: addEdge({ ...connection, source: exposed.source.id, target: exposed.target.id, sourceHandle: exposed.source.handle, targetHandle: exposed.target.handle, id: crypto.randomUUID() }, document.edges) } }, exposed.boardId); } catch (error) { setError(error instanceof Error && error.message === "boundary_port_required" ? "跨画布连接暂不可用，请稍后重试。" : errorText(error)); } } + /** 校验MIME与大小并清文件input；迁移期间拒绝。真实画布通过上传占位，演示以Data URL直接加入。 */ async function readImage(event: ChangeEvent) { const file = event.target.files?.[0]; event.target.value = ""; @@ -331,6 +394,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: } const request = pendingImage.current; pendingImage.current = null; const kind = imageKind.current; + // 真实图片上传先取得本地Blob预览并构造draft，随后把pendingUpload节点及可选分支边发布到owner。 if (snapshot) { try { const job = uploads.start(file, (src) => { const current = treeRef.current; @@ -343,12 +407,14 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: const node=makeCanvasNode(kind,center(),src);if(kind==='plain-image')node.data.title=file.name.slice(0,300); return {owner:board.id,node}; }); + // pendingUpload以node.id标记，后续资源完成/跨区移动/历史恢复都按这个身份找到占位。 const current=treeRef.current,doc=current.current.current.get(job.owner)!; const node={...job.node,pendingUpload:job.node.id}; current.dispatch({type:"replace",document:{...doc,nodes:[...doc.nodes,node],edges:[...doc.edges,...(job.edge?[job.edge]:[])]}},job.owner); setTool("select"); } catch(error) {setError(errorText(error));} return; } + // 演示不上传服务端，FileReader读取全部字节为Data URL；纯图片另解码初始尺寸，finally释放读取中UI状态。 setImageUploading(true); try { const src = await new Promise((resolve, reject) => { @@ -370,6 +436,8 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: } catch (error) { pendingImage.current = null; setError(errorText(error)); } finally { setImageUploading(false); } } + /** 旧版导入最多5MB并全量读取解码，替换当前根快照；任一方含真实子图时拒绝，避免破坏跨board关系。 + * ioActive用于阻止迁移交接；这条路径不是新版渐进导入，也不会自动重建bundle子图。 */ async function importProject(event: ChangeEvent) { const file = event.target.files?.[0]; event.target.value = ""; @@ -387,6 +455,8 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: } catch (error) { setError(error instanceof Error ? error.message : "导入失败。"); } finally{ioActive.current=false;} } + /** 有上传占位则先等待用户完成；树导出完整可达文档，多board写bundle，单board写当前视口。 + * 下载名清理文件名非法字符，Blob URL延迟释放；不额外打包File/Blob，已有演示Data URL仍随src导出。 */ async function exportProject() { let documents: Map; try { if([...tree.current.current.values()].some((doc)=>doc.nodes.some((node)=>node.pendingUpload))) throw new Error("图片仍在上传，完成后即可导出。"); documents = await tree.exportDocuments(); } catch (error) { setError(error instanceof Error ? error.message : "导出未完成"); return; } @@ -399,7 +469,9 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: setTimeout(() => URL.revokeObjectURL(url), 1000); } + // 旧版全局快捷键：跳过输入框、文本编辑、对话框和打开的popover，支持撤销/重做与V/H；卸载移除。 useEffect(() => { + /** 按DOM目标过滤后处理键；此旧路径没有新版routeCanvasKey的组合输入/认领优先级模型。 */ const keydown = (event: KeyboardEvent) => { const target = event.target; if (!(target instanceof HTMLElement)) return; @@ -417,6 +489,11 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: return () => window.removeEventListener("keydown", keydown); }, []); + // Provider把图片预览、节点动作、分区反馈及活动连线接到renderer；迁移时surface与底部创作栏设inert。 + // ReactFlow删除由onBeforeDelete拦截真实子图/暴露端口节点，避免默认删除破坏结构；普通元素沿tree变化入口。 + // 选择工具允许拖动/连接，抓手只平移；Space临时平移、Shift部分框选，滚轮默认平移、修饰键缩放。 + // 工具栏创建/模板/导入走上述入口，顶部视口操作保存本地viewport；AI只给选中且支持的节点显示。 + // 恢复弹窗先根再子，逐项核查canRestore；迁移组件检查草稿、文件IO和未完成上传再排空writer。 return (
@@ -427,6 +504,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: nodes={nodes} edges={edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes} onBeforeDelete={async ({ nodes: removing }) => { if (tree.busy || tree.transactionBusy) return false; + // 选中分区入口要先dissolve保留内容；内部节点若被父port引用，先移回父board再删，清理边界引用。 const linked = removing.filter((node) => node.data.subgraph); const parents = subgraphParents(tree.current.current); const referenced = removing.filter((node) => { @@ -436,6 +514,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: }); if (!linked.length && !referenced.length) return true; try { + // 分区逐个事务解散，参与者包含父、子、孙及需要调整引用的祖先；并非一批选择全体原子操作。 for (const node of linked) { const ref = tree.views.nodeRefs.get(node.id)!; await tree.ensure(node.data.subgraph!.boardId); @@ -445,6 +524,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: if (ancestor && subgraphMoveParticipants(tree.current.current, ref.boardId, node.data.subgraph!.boardId, ref.boardId, child.nodes.map((item) => item.id)).includes(ancestor)) participants.add(ancestor); await tree.command(ref.boardId, `subgraphs/${ref.id}/dissolve`, {}, [...participants]); } + // 解散后owner可能变化，按原ID重新查唯一归属；找不到唯一目标就跳过，不误删同ID的其它节点。 for (const node of removing.filter((node) => !node.data.subgraph)) { const ref = tree.views.nodeRefs.get(node.id); if (!ref) continue; let owner = ref.boardId; @@ -461,6 +541,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: } if (linked.length) setMembershipNotice("已解散选框，子画布内容已保留"); } catch (error) { setError(error instanceof Error ? error.message : "删除未完成"); } + // 结构分支已自行执行删除/解散，阻止ReactFlow再按旧投影默认删一遍。 return false; }} onNodesChange={tree.nodesChanged} @@ -486,6 +567,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: defaultEdgeOptions={{ style: { stroke: "#aa968b", strokeWidth: 1.5 } }}> {ai.enabled && nodes.filter((node) => node.selected && ["text", "script", "plain-text", "image", "plain-image"].includes(node.data.kind)).map((node) => { + // AIPanel收到owner原始节点，显示ID仅用于NodeToolbar定位；save仍经tree.nodeAction回写owner。 const ref = tree.views.nodeRefs.get(node.id)!; const owned = tree.documents.get(ref.boardId)?.nodes.find((item) => item.id === ref.id); return owned && tree.nodeAction(node.id, (id) => ({ type: "node-data", id, patch: { ai: config } }))} />; @@ -558,6 +640,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?:
} {tree.memberJobs.map((job, index) => job.ids.map((id) => { + // 成员任务提示跟随当前source/target中的场景节点，队首同步、后续等待，失败通过retryMembers继续。 const node = [...tree.views.nodeRefs].find(([, ref]) => ref.id === id && [job.source, job.target].includes(ref.boardId)); return node &&
@@ -577,6 +660,7 @@ function CanvasEditor({ board, snapshot, migration }: { board: Board; snapshot?: ); } +/** 为单个旧编辑器建立独立ReactFlow store；board/snapshot身份切换的重挂载由路由调用方负责。 */ export default function GraphCanvas({ board, snapshot, migration }: { board: Board; snapshot?: CanvasSnapshot; migration?:LegacyMigrationContext }) { return ; }