拆分图片画布素材拖拽桥接

新增素材拖拽桥接 hook，承接素材拖向画布或文件夹的全局 pointer 监听

恢复认证弹窗 portal 渲染，避免全屏画布遮住账号入口

优化画布背景设置面板，补回当前色、色域、色相、预设、HEX 和恢复默认

补充素材拖拽、认证弹窗和背景面板回归测试并更新文档与 TRACKING

src/components/image-editor/ImageCanvasEditorView.test.tsx

@@ -2025,7 +2025,11 @@ describe('ImageCanvasEditorView', () => {
     const settingsPanel = screen.getByRole('dialog', {
       name: '画布背景设置',
     });
-    expect(within(settingsPanel).getByText('画布背景色')).toBeTruthy();
+    expect(within(settingsPanel).getByText('画布背景')).toBeTruthy();
+    expect(within(settingsPanel).getByLabelText('画布背景色相')).toBeTruthy();
+    expect(
+      within(settingsPanel).getByLabelText('画布背景十六进制颜色'),
+    ).toBeTruthy();
 
     fireEvent.click(
       within(settingsPanel).getByRole('button', { name: '暖灰' }),

src/components/image-editor/ImageCanvasEditorView.tsx

@@ -51,6 +51,7 @@ import { useCanvasHistory } from './useCanvasHistory';
 import { useCanvasGenerationDialogs } from './useCanvasGenerationDialogs';
 import { useImageCanvasAssetLibrary } from './useImageCanvasAssetLibrary';
 import { useImageCanvasAssetExportWorkflow } from './useImageCanvasAssetExportWorkflow';
+import { useImageCanvasAssetPointerDragBridge } from './useImageCanvasAssetPointerDragBridge';
 import { useImageCanvasCanvasDropWorkflow } from './useImageCanvasCanvasDropWorkflow';
 import { useImageCanvasEditorChrome } from './useImageCanvasEditorChrome';
 import { useImageCanvasGenerationWorkflow } from './useImageCanvasGenerationWorkflow';
@@ -124,13 +125,6 @@ export function ImageCanvasEditorView() {
   selectedLayerIdsRef.current = selectedLayerIds;
   layersRef.current = layers;
   viewportRef.current = viewport;
-  const assetsRef = useRef<EditorAsset[]>([]);
-  const addAssetLayerRef = useRef<
-    (asset: EditorAsset, screenCenter?: { x: number; y: number }) => void
-  >(() => {});
-  const moveAssetToFolderRef = useRef<
-    (assetId: string, folderId: string) => void
-  >(() => {});
   authUiRef.current = authUi;
   const openEditorLoginModal = useCallback(
     (postLoginAction?: (() => void) | null) => {
@@ -268,10 +262,6 @@ export function ImageCanvasEditorView() {
     onDeleteAssets: removeCanvasLayersLinkedToAssets,
   });
 
-  useEffect(() => {
-    assetsRef.current = assets;
-  }, [assets]);
-
   const handleActivateCanvasGenerationDialog = useCallback(() => {
     setSelectedLayerId(null);
     setSelectedLayerIds([]);
@@ -723,74 +713,6 @@ export function ImageCanvasEditorView() {
     };
   }, []);
 
-  useEffect(() => {
-    const updatePointerDrag = (event: PointerEvent) => {
-      const currentDrag = assetPointerDragRef.current;
-      if (!currentDrag || currentDrag.pointerId !== event.pointerId) {
-        return;
-      }
-      const distance = Math.hypot(
-        event.clientX - currentDrag.startClientX,
-        event.clientY - currentDrag.startClientY,
-      );
-      const dropFolderId = resolveAssetFolderId(event.clientX, event.clientY);
-      const nextDrag: AssetPointerDragState = {
-        ...currentDrag,
-        currentClientX: event.clientX,
-        currentClientY: event.clientY,
-        active: currentDrag.active || distance > 4,
-        dropFolderId,
-      };
-      assetPointerDragRef.current = nextDrag;
-      setAssetPointerDrag(nextDrag);
-      setUploadDropTarget(
-        resolveCanvasPoint(event.clientX, event.clientY) ? 'canvas' : null,
-      );
-      updateAssetMoveDropFolder(dropFolderId);
-    };
-
-    const finishPointerDrag = (event: PointerEvent) => {
-      const currentDrag = assetPointerDragRef.current;
-      if (!currentDrag || currentDrag.pointerId !== event.pointerId) {
-        return;
-      }
-      const canvasPoint = resolveCanvasPoint(event.clientX, event.clientY);
-      const dropFolderId =
-        resolveAssetFolderId(event.clientX, event.clientY) ??
-        currentDrag.dropFolderId;
-      const draggedAsset = assetsRef.current.find(
-        (asset) => asset.id === currentDrag.assetId,
-      );
-      assetPointerDragRef.current = null;
-      setAssetPointerDrag(null);
-      setUploadDropTarget(null);
-      updateAssetMoveDropFolder(null);
-      if (!currentDrag.active || !draggedAsset) {
-        return;
-      }
-      suppressAssetClickRef.current = true;
-      window.setTimeout(() => {
-        suppressAssetClickRef.current = false;
-      }, 0);
-      if (dropFolderId && dropFolderId !== draggedAsset.folderId) {
-        moveAssetToFolderRef.current(draggedAsset.id, dropFolderId);
-        return;
-      }
-      if (canvasPoint) {
-        addAssetLayerRef.current(draggedAsset, canvasPoint);
-      }
-    };
-
-    window.addEventListener('pointermove', updatePointerDrag);
-    window.addEventListener('pointerup', finishPointerDrag);
-    window.addEventListener('pointercancel', finishPointerDrag);
-    return () => {
-      window.removeEventListener('pointermove', updatePointerDrag);
-      window.removeEventListener('pointerup', finishPointerDrag);
-      window.removeEventListener('pointercancel', finishPointerDrag);
-    };
-  }, []);
-
   const addAssetLayer = (
     asset: EditorAsset,
     position?: { x: number; y: number },
@@ -811,9 +733,19 @@ export function ImageCanvasEditorView() {
     selectSingleLayer(nextLayer.id);
     setHoveredLayerId(null);
   };
-  addAssetLayerRef.current = addAssetLayer;
 
-  moveAssetToFolderRef.current = moveAssetToFolder;
+  useImageCanvasAssetPointerDragBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets,
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  });
 
   deleteLayerByIdRef.current = deleteLayerById;
 

src/components/image-editor/ImageCanvasStageView.tsx

@@ -881,7 +881,7 @@ export function ImageCanvasStageView({
               aria-label="画布背景设置"
             >
               <div className="image-canvas-editor__background-panel-head">
-                <span>画布背景色</span>
+                <span>画布背景</span>
                 <button
                   type="button"
                   className="image-canvas-editor__background-close"
@@ -891,6 +891,14 @@ export function ImageCanvasStageView({
                   <X className="h-4 w-4" aria-hidden="true" />
                 </button>
               </div>
+              <div className="image-canvas-editor__background-current-row">
+                <span
+                  className="image-canvas-editor__background-current-preview"
+                  style={{ backgroundColor: canvasBackgroundColor }}
+                  aria-hidden="true"
+                />
+                <span>{canvasBackgroundColor}</span>
+              </div>
               <label className="image-canvas-editor__background-spectrum">
                 <input
                   type="color"
@@ -939,27 +947,29 @@ export function ImageCanvasStageView({
                   </button>
                 ))}
               </div>
-              <label className="image-canvas-editor__background-hex-field">
-                <span>HEX</span>
-                <input
-                  aria-label="画布背景十六进制颜色"
-                  value={canvasBackgroundHexValue}
-                  spellCheck={false}
-                  onChange={(event) =>
-                    onCanvasBackgroundHexChange(event.currentTarget.value)
+              <div className="image-canvas-editor__background-footer">
+                <label className="image-canvas-editor__background-hex-field">
+                  <span>HEX</span>
+                  <input
+                    aria-label="画布背景十六进制颜色"
+                    value={canvasBackgroundHexValue}
+                    spellCheck={false}
+                    onChange={(event) =>
+                      onCanvasBackgroundHexChange(event.currentTarget.value)
+                    }
+                  />
+                </label>
+                <button
+                  type="button"
+                  className="image-canvas-editor__background-reset"
+                  onClick={() =>
+                    onApplyCanvasBackgroundColor(DEFAULT_CANVAS_BACKGROUND_COLOR)
                   }
-                />
-              </label>
-              <button
-                type="button"
-                className="image-canvas-editor__background-reset"
-                onClick={() =>
-                  onApplyCanvasBackgroundColor(DEFAULT_CANVAS_BACKGROUND_COLOR)
-                }
-              >
-                <RotateCcw className="h-3.5 w-3.5" aria-hidden="true" />
-                恢复默认
-              </button>
+                >
+                  <RotateCcw className="h-3.5 w-3.5" aria-hidden="true" />
+                  恢复默认
+                </button>
+              </div>
             </div>
           ) : null}
         </div>

src/components/image-editor/useImageCanvasAssetPointerDragBridge.test.tsx

@@ -0,0 +1,263 @@
+/* @vitest-environment jsdom */
+
+import { act, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type {
+  AssetPointerDragState,
+  EditorAsset,
+} from './ImageCanvasEditorTypes';
+import { useImageCanvasAssetPointerDragBridge } from './useImageCanvasAssetPointerDragBridge';
+
+const defaultAssets: EditorAsset[] = [
+  {
+    id: 'asset-1',
+    label: '素材一',
+    src: 'data:image/png;base64,asset-1',
+    width: 320,
+    height: 240,
+    folderId: 'project',
+    sourceKind: 'uploaded',
+    sourceType: 'uploaded',
+    persisted: true,
+  },
+];
+
+function dispatchPointerEvent(
+  type: string,
+  init: MouseEventInit & { pointerId: number },
+) {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  Object.defineProperty(event, 'pointerId', { value: init.pointerId });
+  window.dispatchEvent(event);
+}
+
+function AssetPointerDragBridgeHarness({
+  initialDrag,
+  assets = defaultAssets,
+  resolveAssetFolderId = vi.fn(() => null),
+  resolveCanvasPoint = vi.fn(() => null),
+  moveAssetToFolder = vi.fn(),
+  addAssetLayer = vi.fn(),
+}: {
+  initialDrag?: AssetPointerDragState | null;
+  assets?: EditorAsset[];
+  resolveAssetFolderId?: (clientX: number, clientY: number) => string | null;
+  resolveCanvasPoint?: (
+    clientX: number,
+    clientY: number,
+  ) => { x: number; y: number } | null;
+  moveAssetToFolder?: (assetId: string, folderId: string) => void;
+  addAssetLayer?: (asset: EditorAsset, position?: { x: number; y: number }) => void;
+}) {
+  const assetPointerDragRef = useRef<AssetPointerDragState | null>(
+    initialDrag ?? {
+      assetId: 'asset-1',
+      pointerId: 7,
+      startClientX: 10,
+      startClientY: 10,
+      currentClientX: 10,
+      currentClientY: 10,
+      active: false,
+      dropFolderId: null,
+    },
+  );
+  const suppressAssetClickRef = useRef(false);
+  const [assetPointerDrag, setAssetPointerDrag] =
+    useState<AssetPointerDragState | null>(assetPointerDragRef.current);
+  const [uploadDropTarget, setUploadDropTarget] = useState<
+    'canvas' | 'assets' | null
+  >(null);
+  const [dropFolderId, updateAssetMoveDropFolder] = useState<string | null>(
+    null,
+  );
+
+  useImageCanvasAssetPointerDragBridge({
+    assetPointerDragRef,
+    suppressAssetClickRef,
+    assets,
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  });
+
+  return (
+    <div>
+      <span data-testid="drag-active">
+        {assetPointerDrag ? String(assetPointerDrag.active) : 'none'}
+      </span>
+      <span data-testid="drag-x">
+        {assetPointerDrag ? assetPointerDrag.currentClientX : 'none'}
+      </span>
+      <span data-testid="drop-target">{uploadDropTarget ?? '-'}</span>
+      <span data-testid="drop-folder">{dropFolderId ?? '-'}</span>
+      <span data-testid="suppressed">{String(suppressAssetClickRef.current)}</span>
+    </div>
+  );
+}
+
+describe('useImageCanvasAssetPointerDragBridge', () => {
+  it('activates sidebar asset drags and updates canvas and folder drop hints', () => {
+    const resolveAssetFolderId = vi.fn(() => 'folder-1');
+    const resolveCanvasPoint = vi.fn(() => ({ x: 100, y: 80 }));
+    render(
+      <AssetPointerDragBridgeHarness
+        resolveAssetFolderId={resolveAssetFolderId}
+        resolveCanvasPoint={resolveCanvasPoint}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointermove', {
+        pointerId: 7,
+        clientX: 18,
+        clientY: 18,
+      });
+    });
+
+    expect(screen.getByTestId('drag-active').textContent).toBe('true');
+    expect(screen.getByTestId('drag-x').textContent).toBe('18');
+    expect(screen.getByTestId('drop-target').textContent).toBe('canvas');
+    expect(screen.getByTestId('drop-folder').textContent).toBe('folder-1');
+  });
+
+  it('moves an active asset drag into a different folder on pointer up', () => {
+    const moveAssetToFolder = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 7,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 30,
+          currentClientY: 30,
+          active: true,
+          dropFolderId: 'folder-1',
+        }}
+        resolveAssetFolderId={() => 'folder-1'}
+        moveAssetToFolder={moveAssetToFolder}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 30,
+        clientY: 30,
+      });
+    });
+
+    expect(moveAssetToFolder).toHaveBeenCalledWith('asset-1', 'folder-1');
+    expect(screen.getByTestId('drag-active').textContent).toBe('none');
+    expect(screen.getByTestId('drop-target').textContent).toBe('-');
+    expect(screen.getByTestId('drop-folder').textContent).toBe('-');
+    expect(screen.getByTestId('suppressed').textContent).toBe('true');
+  });
+
+  it('adds an active dragged asset to the canvas when released over the canvas', () => {
+    const addAssetLayer = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 7,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 48,
+          currentClientY: 64,
+          active: true,
+          dropFolderId: null,
+        }}
+        resolveCanvasPoint={() => ({ x: 480, y: 640 })}
+        addAssetLayer={addAssetLayer}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 48,
+        clientY: 64,
+      });
+    });
+
+    expect(addAssetLayer).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'asset-1' }),
+      { x: 480, y: 640 },
+    );
+  });
+
+  it('cleans up inactive drags without moving or adding assets', () => {
+    const moveAssetToFolder = vi.fn();
+    const addAssetLayer = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 7,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 10,
+          currentClientY: 10,
+          active: false,
+          dropFolderId: 'folder-1',
+        }}
+        moveAssetToFolder={moveAssetToFolder}
+        addAssetLayer={addAssetLayer}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointerup', {
+        pointerId: 7,
+        clientX: 10,
+        clientY: 10,
+      });
+    });
+
+    expect(moveAssetToFolder).not.toHaveBeenCalled();
+    expect(addAssetLayer).not.toHaveBeenCalled();
+    expect(screen.getByTestId('drag-active').textContent).toBe('none');
+  });
+
+  it('uses the same finish path for pointer cancellation', () => {
+    const moveAssetToFolder = vi.fn();
+    const addAssetLayer = vi.fn();
+    render(
+      <AssetPointerDragBridgeHarness
+        initialDrag={{
+          assetId: 'asset-1',
+          pointerId: 8,
+          startClientX: 10,
+          startClientY: 10,
+          currentClientX: 24,
+          currentClientY: 24,
+          active: true,
+          dropFolderId: 'folder-1',
+        }}
+        moveAssetToFolder={moveAssetToFolder}
+        addAssetLayer={addAssetLayer}
+      />,
+    );
+
+    act(() => {
+      dispatchPointerEvent('pointercancel', {
+        pointerId: 8,
+        clientX: 24,
+        clientY: 24,
+      });
+    });
+
+    expect(moveAssetToFolder).toHaveBeenCalledWith('asset-1', 'folder-1');
+  });
+});

src/components/image-editor/useImageCanvasAssetPointerDragBridge.ts

@@ -0,0 +1,140 @@
+import { type RefObject, useEffect, useRef } from 'react';
+
+import type {
+  AssetPointerDragState,
+  EditorAsset,
+} from './ImageCanvasEditorTypes';
+
+type CanvasPoint = { x: number; y: number };
+
+type UseImageCanvasAssetPointerDragBridgeOptions = {
+  assetPointerDragRef: RefObject<AssetPointerDragState | null>;
+  suppressAssetClickRef: RefObject<boolean>;
+  assets: EditorAsset[];
+  resolveAssetFolderId: (clientX: number, clientY: number) => string | null;
+  resolveCanvasPoint: (clientX: number, clientY: number) => CanvasPoint | null;
+  setAssetPointerDrag: (dragState: AssetPointerDragState | null) => void;
+  setUploadDropTarget: (target: 'canvas' | 'assets' | null) => void;
+  updateAssetMoveDropFolder: (folderId: string | null) => void;
+  moveAssetToFolder: (assetId: string, folderId: string) => void;
+  addAssetLayer: (asset: EditorAsset, position?: CanvasPoint) => void;
+};
+
+export function useImageCanvasAssetPointerDragBridge({
+  assetPointerDragRef,
+  suppressAssetClickRef,
+  assets,
+  resolveAssetFolderId,
+  resolveCanvasPoint,
+  setAssetPointerDrag,
+  setUploadDropTarget,
+  updateAssetMoveDropFolder,
+  moveAssetToFolder,
+  addAssetLayer,
+}: UseImageCanvasAssetPointerDragBridgeOptions) {
+  const assetsRef = useRef(assets);
+  const callbacksRef = useRef({
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  });
+
+  useEffect(() => {
+    assetsRef.current = assets;
+  }, [assets]);
+
+  callbacksRef.current = {
+    resolveAssetFolderId,
+    resolveCanvasPoint,
+    setAssetPointerDrag,
+    setUploadDropTarget,
+    updateAssetMoveDropFolder,
+    moveAssetToFolder,
+    addAssetLayer,
+  };
+
+  useEffect(() => {
+    const updatePointerDrag = (event: PointerEvent) => {
+      const currentDrag = assetPointerDragRef.current;
+      if (!currentDrag || currentDrag.pointerId !== event.pointerId) {
+        return;
+      }
+      const {
+        resolveAssetFolderId: resolveFolder,
+        resolveCanvasPoint: resolvePoint,
+        setAssetPointerDrag: setPointerDrag,
+        setUploadDropTarget: setDropTarget,
+        updateAssetMoveDropFolder: updateDropFolder,
+      } = callbacksRef.current;
+      const distance = Math.hypot(
+        event.clientX - currentDrag.startClientX,
+        event.clientY - currentDrag.startClientY,
+      );
+      const dropFolderId = resolveFolder(event.clientX, event.clientY);
+      const nextDrag: AssetPointerDragState = {
+        ...currentDrag,
+        currentClientX: event.clientX,
+        currentClientY: event.clientY,
+        active: currentDrag.active || distance > 4,
+        dropFolderId,
+      };
+      assetPointerDragRef.current = nextDrag;
+      setPointerDrag(nextDrag);
+      setDropTarget(resolvePoint(event.clientX, event.clientY) ? 'canvas' : null);
+      updateDropFolder(dropFolderId);
+    };
+
+    const finishPointerDrag = (event: PointerEvent) => {
+      const currentDrag = assetPointerDragRef.current;
+      if (!currentDrag || currentDrag.pointerId !== event.pointerId) {
+        return;
+      }
+      const {
+        resolveAssetFolderId: resolveFolder,
+        resolveCanvasPoint: resolvePoint,
+        setAssetPointerDrag: setPointerDrag,
+        setUploadDropTarget: setDropTarget,
+        updateAssetMoveDropFolder: updateDropFolder,
+        moveAssetToFolder: moveToFolder,
+        addAssetLayer: addLayer,
+      } = callbacksRef.current;
+      const canvasPoint = resolvePoint(event.clientX, event.clientY);
+      const dropFolderId =
+        resolveFolder(event.clientX, event.clientY) ?? currentDrag.dropFolderId;
+      const draggedAsset = assetsRef.current.find(
+        (asset) => asset.id === currentDrag.assetId,
+      );
+      assetPointerDragRef.current = null;
+      setPointerDrag(null);
+      setDropTarget(null);
+      updateDropFolder(null);
+      if (!currentDrag.active || !draggedAsset) {
+        return;
+      }
+      suppressAssetClickRef.current = true;
+      window.setTimeout(() => {
+        suppressAssetClickRef.current = false;
+      }, 0);
+      if (dropFolderId && dropFolderId !== draggedAsset.folderId) {
+        moveToFolder(draggedAsset.id, dropFolderId);
+        return;
+      }
+      if (canvasPoint) {
+        addLayer(draggedAsset, canvasPoint);
+      }
+    };
+
+    window.addEventListener('pointermove', updatePointerDrag);
+    window.addEventListener('pointerup', finishPointerDrag);
+    window.addEventListener('pointercancel', finishPointerDrag);
+    return () => {
+      window.removeEventListener('pointermove', updatePointerDrag);
+      window.removeEventListener('pointerup', finishPointerDrag);
+      window.removeEventListener('pointercancel', finishPointerDrag);
+    };
+  }, [assetPointerDragRef, suppressAssetClickRef]);
+}