@arronqzy/react-view 1.0.3 → 1.0.5

package/src/panel/components/PanelCanvas.tsx

@@ -1,6 +1,5 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import InfiniteViewer from "react-infinite-viewer";
-import { TransformComponent, TransformWrapper } from "react-zoom-pan-pinch";
 
 import {
   clampViewportZoom,
@@ -23,6 +22,8 @@ export type PanelCanvasProps = {
   onDropMaterial?: (payload: { materialId: string; x: number; y: number }) => void;
   /** 渲染在 InfiniteViewer 内、画布 scale 层之外（如 Moveable 控制框） */
   viewportOverlay?: React.ReactNode;
+  /** 平移等视口变换后同步 Moveable 控制框（绕过 React scroll 节流） */
+  viewportSyncRef?: React.MutableRefObject<(() => void) | null>;
 };
 
 export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
@@ -40,12 +41,12 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
       onCanvasContextMenuCapture,
       onDropMaterial,
       viewportOverlay,
+      viewportSyncRef,
     },
     scrollRef
   ) => {
   const viewportRef = useRef<HTMLDivElement | null>(null);
   const viewerRef = useRef<any>(null);
-  const transformRef = useRef<any>(null);
   const canvasElRef = useRef<HTMLDivElement | null>(null);
   const syncingZoomRef = useRef(false);
   const didAutoCenterRef = useRef(false);
@@ -76,6 +77,14 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
     height: number;
   } | null>(null);
 
+  const applyCanvasTransform = useCallback((scale: number) => {
+    const el = canvasElRef.current;
+    if (!el) return;
+    el.style.transform = `scale(${scale})`;
+    el.style.transformOrigin = "0 0";
+    el.dataset.canvasScale = String(scale);
+  }, []);
+
   const commitScroll = useCallback(
     (left: number, top: number) => {
       const next = { left, top };
@@ -85,6 +94,10 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
     [onScrollChange]
   );
 
+  const notifyViewportSync = useCallback(() => {
+    viewportSyncRef?.current?.();
+  }, [viewportSyncRef]);
+
   useEffect(() => {
     zoomRef.current = zoom;
   }, [zoom]);
@@ -155,8 +168,6 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
     if (!el) return;
 
     const onWheelZoom = (e: WheelEvent) => {
-      const api = transformRef.current;
-      if (!api) return;
       const viewer = viewerRef.current as any;
       if (!viewer) return;
       const target = e.target as HTMLElement | null;
@@ -189,10 +200,12 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
       const worldY = (pointerY + currentScrollTop) / Math.max(0.0001, zy);
       const nextScrollLeft = worldX * nextZoom.x - pointerX;
       const nextScrollTop = worldY * nextZoom.y - pointerY;
+      const nextScale = uniformViewportZoom(nextZoom);
 
       syncingZoomRef.current = true;
+      zoomRef.current = nextZoom;
+      applyCanvasTransform(nextScale);
       viewer.scrollTo(nextScrollLeft, nextScrollTop);
-      commitScroll(nextScrollLeft, nextScrollTop);
       const { width: vw, height: vh } = viewportSizeRef.current;
       resizeLayoutAnchorRef.current = {
         viewportWidth: vw,
@@ -208,25 +221,22 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
         zoomX: nextZoom.x,
         zoomY: nextZoom.y,
       };
-      zoomRef.current = nextZoom;
       onZoomChange({
         x: Number(nextZoom.x.toFixed(4)),
         y: Number(nextZoom.y.toFixed(4)),
       });
-      requestAnimationFrame(() => {
-        syncingZoomRef.current = false;
-      });
     };
 
     el.addEventListener("wheel", onWheelZoom, { passive: false, capture: true });
     return () => {
       el.removeEventListener("wheel", onWheelZoom, true);
     };
-  }, [commitScroll, onZoomChange, viewport.width, viewport.height]);
+  }, [applyCanvasTransform, onZoomChange, viewport.width, viewport.height]);
 
   const applyViewportResizeZoom = useCallback(
     (w: number, h: number) => {
       if (w < 8 || h < 8) return;
+      if (syncingZoomRef.current) return;
 
       const viewer = viewerRef.current as {
         scrollTo?: (x: number, y: number) => void;
@@ -285,8 +295,9 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
       const nextZoom = { x: nextZoomValue, y: nextZoomValue };
 
       syncingZoomRef.current = true;
+      zoomRef.current = nextZoom;
+      applyCanvasTransform(nextZoomValue);
       viewer.scrollTo?.(nextScrollLeft, nextScrollTop);
-      commitScroll(nextScrollLeft, nextScrollTop);
       resizeLayoutAnchorRef.current = {
         viewportWidth: w,
         viewportHeight: h,
@@ -301,16 +312,12 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
         zoomX: nextZoomValue,
         zoomY: nextZoomValue,
       };
-      zoomRef.current = nextZoom;
       onZoomChange({
         x: Number(nextZoomValue.toFixed(4)),
         y: Number(nextZoomValue.toFixed(4)),
       });
-      requestAnimationFrame(() => {
-        syncingZoomRef.current = false;
-      });
     },
-    [commitScroll, onZoomChange]
+    [applyCanvasTransform, onZoomChange]
   );
 
   const syncViewportElement = useCallback(
@@ -326,11 +333,14 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
   const syncCanvasElement = useCallback(
     (el: HTMLDivElement | null) => {
       canvasElRef.current = el;
+      if (el) {
+        applyCanvasTransform(uniformViewportZoom(zoomRef.current));
+      }
       if (!canvasRef) return;
       if (typeof canvasRef === "function") canvasRef(el);
       else (canvasRef as React.MutableRefObject<HTMLDivElement | null>).current = el;
     },
-    [canvasRef]
+    [applyCanvasTransform, canvasRef]
   );
 
   useEffect(() => {
@@ -465,15 +475,9 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
         const nextLeft = panRef.current.startLeft - dx;
         const nextTop = panRef.current.startTop - dy;
         viewer.scrollTo(nextLeft, nextTop);
-        const left =
-          typeof viewer.getScrollLeft === "function"
-            ? viewer.getScrollLeft()
-            : nextLeft;
-        const top =
-          typeof viewer.getScrollTop === "function"
-            ? viewer.getScrollTop()
-            : nextTop;
-        commitScroll(left, top);
+        lastScrollRef.current = { left: nextLeft, top: nextTop };
+        onScrollChange?.({ left: nextLeft, top: nextTop });
+        notifyViewportSync();
       };
 
       const up = (ev: MouseEvent) => {
@@ -498,7 +502,7 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
       el.removeEventListener("contextmenu", onContextMenu, true);
       el.removeEventListener("mousedown", onMouseDown, true);
     };
-  }, [clearWindowPanListeners, commitScroll]);
+  }, [clearWindowPanListeners, commitScroll, notifyViewportSync, onScrollChange]);
 
   const resolvedContentSize = useMemo(() => {
     if (contentSize) return contentSize;
@@ -511,6 +515,35 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
 
   const canvasScale = useMemo(() => uniformViewportZoom(zoom), [zoom.x, zoom.y]);
 
+  const reconcileCanvasTransform = useCallback(() => {
+    const scale = syncingZoomRef.current
+      ? uniformViewportZoom(zoomRef.current)
+      : uniformViewportZoom(zoom);
+    applyCanvasTransform(scale);
+  }, [applyCanvasTransform, zoom.x, zoom.y]);
+
+  useLayoutEffect(() => {
+    reconcileCanvasTransform();
+  }, [canvasScale, reconcileCanvasTransform]);
+
+  useEffect(() => {
+    if (
+      Math.abs(zoom.x - zoomRef.current.x) < 0.0001 &&
+      Math.abs(zoom.y - zoomRef.current.y) < 0.0001
+    ) {
+      syncingZoomRef.current = false;
+    }
+  }, [zoom.x, zoom.y]);
+
+  const worldStyle = useMemo<React.CSSProperties>(
+    () => ({
+      width: resolvedContentSize.width,
+      height: resolvedContentSize.height,
+      position: "relative",
+    }),
+    [resolvedContentSize.height, resolvedContentSize.width]
+  );
+
   const style = useMemo<React.CSSProperties>(
     () => ({
       width: resolvedContentSize.width,
@@ -518,10 +551,9 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
       minWidth: "100%",
       minHeight: "100%",
       position: "relative",
-      transform: `scale(${canvasScale})`,
       transformOrigin: "0 0",
     }),
-    [canvasScale, resolvedContentSize.height, resolvedContentSize.width]
+    [resolvedContentSize.height, resolvedContentSize.width]
   );
 
   const hasMaterialPayload = useCallback((types: ArrayLike<string> | null | undefined) => {
@@ -613,44 +645,29 @@ export const PanelCanvas = React.forwardRef<HTMLDivElement, PanelCanvasProps>(
         const next = { left: e.scrollLeft ?? 0, top: e.scrollTop ?? 0 };
         lastScrollRef.current = next;
         onScrollChange?.(next);
+        if (!syncingZoomRef.current) {
+          notifyViewportSync();
+        }
       }}
     >
-      <TransformWrapper
-        ref={transformRef}
-        initialScale={1}
-        minScale={1}
-        maxScale={1}
-        centerOnInit={false}
-        limitToBounds={false}
-        panning={{ disabled: true }}
-        doubleClick={{ disabled: true }}
-        pinch={{ disabled: true }}
-        wheel={{ step: 0.008, disabled: true, wheelDisabled: true }}
-        centerZoomedOut={false}
-      >
-        <TransformComponent
-          // 始终占满操作容器，但不在这一层裁切放大后的内容
-          wrapperStyle={{ width: "100%", height: "100%", overflow: "visible" }}
-          contentStyle={{ width: "100%", height: "100%", overflow: "visible" }}
+      <div style={worldStyle}>
+        <div
+          ref={syncCanvasElement}
+          data-panel-canvas
+          style={style}
+          className="h-full w-full"
+          onMouseDownCapture={onCanvasMouseDownCapture}
+          onClickCapture={onCanvasClickCapture}
+          onContextMenuCapture={onCanvasContextMenuCapture}
         >
-          <div
-            ref={syncCanvasElement}
-            data-panel-canvas
-            style={style}
-            className=""
-            onMouseDownCapture={onCanvasMouseDownCapture}
-            onClickCapture={onCanvasClickCapture}
-            onContextMenuCapture={onCanvasContextMenuCapture}
-          >
-            {children}
-            {viewportOverlay ? (
-              <div className="rv-viewport-overlay pointer-events-none absolute inset-0 z-[70] overflow-visible [&_.moveable-control-box]:pointer-events-auto">
-                {viewportOverlay}
-              </div>
-            ) : null}
+          {children}
+        </div>
+        {viewportOverlay ? (
+          <div className="rv-viewport-overlay pointer-events-none absolute inset-0 z-[70] overflow-visible [&_.moveable-control-box]:pointer-events-auto [&_.moveable-group]:pointer-events-auto [&_.moveable-area]:pointer-events-auto">
+            {viewportOverlay}
           </div>
-        </TransformComponent>
-      </TransformWrapper>
+        ) : null}
+      </div>
     </InfiniteViewer>
   );
 }

package/src/panel/components/PanelConfigSidebar.tsx

@@ -19,10 +19,6 @@ import {
   SelectTrigger,
   SelectValue,
   Textarea,
-  Tooltip,
-  TooltipContent,
-  TooltipProvider,
-  TooltipTrigger,
 } from "@arronqzy/ui";
 import type {
   PanelChartConfig,
@@ -30,10 +26,11 @@ import type {
   PanelElementStyle,
   ReferenceCopyMode,
 } from "../types";
-import { buildChartOption, CHART_TYPES, getChartValuesDisplayText } from "../utils/chartOptionBuilder";
+import { buildChartOption, CHART_TYPES, getChartLabelsDisplayText, getChartValuesDisplayText } from "../utils/chartOptionBuilder";
 import type { PanelLayer } from "../types";
 import { PANEL_MESSAGES } from "../constants/messages";
 import { ViewElementScopePanel } from "./ViewElementScopePanel";
+import { ConfigHintIcon } from "./ConfigHintIcon";
 import { hasViewElementScope } from "../scope/view-scope-store";
 import { collectElementScopeWarnings } from "../utils/scope-template-warnings";
 import { ScopeConfigProvider } from "./scope-config/ScopeConfigContext";
@@ -415,7 +412,8 @@ export function PanelConfigSidebar({
     title: string,
     children: React.ReactNode,
     defaultOpen = true,
-    searchTerms: string[] = []
+    searchTerms: string[] = [],
+    hint?: React.ReactNode
   ) => {
     const hit =
       !hasSearch ||
@@ -437,7 +435,10 @@ export function PanelConfigSidebar({
             {isSectionExpanded(key, defaultOpen) ? "▾" : "▸"}
           </button>
         </CollapsibleTrigger>
-        <div className="text-[11px] font-semibold tracking-wide text-muted-foreground">{title}</div>
+        <div className="flex min-w-0 flex-1 items-center gap-1">
+          <div className="text-[11px] font-semibold tracking-wide text-muted-foreground">{title}</div>
+          {hint ? <ConfigHintIcon label={title}>{hint}</ConfigHintIcon> : null}
+        </div>
       </div>
       <CollapsibleContent className="space-y-3 border-t border-border/60 bg-muted/[0.1] px-3 pb-3 pt-2.5">
         {children}
@@ -446,9 +447,16 @@ export function PanelConfigSidebar({
     );
   };
 
-  const renderFieldGroup = (title: string, children: React.ReactNode) => (
+  const renderFieldGroup = (
+    title: string,
+    children: React.ReactNode,
+    hint?: React.ReactNode
+  ) => (
     <div className="space-y-2.5 rounded-lg border border-border/55 bg-background/80 p-2.5">
-      <div className="text-[11px] font-semibold text-muted-foreground">{title}</div>
+      <div className="flex items-center gap-1">
+        <div className="text-[11px] font-semibold text-muted-foreground">{title}</div>
+        {hint ? <ConfigHintIcon label={title}>{hint}</ConfigHintIcon> : null}
+      </div>
       {children}
     </div>
   );
@@ -494,50 +502,24 @@ export function PanelConfigSidebar({
   const renderOptionLabel = (label: string, keyPath: string, desc: string) => (
     <div className="flex min-w-0 items-center gap-1">
       <span className={optionLabelTextClass} title={`${label}（${keyPath}）`}>{label}</span>
-      <TooltipProvider delayDuration={120}>
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <button
-              type="button"
-              className="inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-full border border-border text-[10px] text-muted-foreground"
-              aria-label={`${label}说明`}
-            >
-              ?
-            </button>
-          </TooltipTrigger>
-          <TooltipContent className="max-w-[260px] text-[11px]">
-            <div>Key: {keyPath}</div>
-            <div>{desc}</div>
-          </TooltipContent>
-        </Tooltip>
-      </TooltipProvider>
+      <ConfigHintIcon label={label}>
+        <div>Key: {keyPath}</div>
+        <div>{desc}</div>
+      </ConfigHintIcon>
     </div>
   );
   const renderFormatterLabel = (label = "Tooltip Formatter（可选）") => (
     <div className="flex min-w-0 items-center gap-1">
       <span className={optionLabelTextClass} title={label}>{label}</span>
-      <TooltipProvider delayDuration={120}>
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <button
-              type="button"
-              className="inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-full border border-border text-[10px] text-muted-foreground"
-              aria-label="Tooltip Formatter 说明"
-            >
-              ?
-            </button>
-          </TooltipTrigger>
-          <TooltipContent className="max-w-[360px] text-[11px] leading-5">
-            <div className="font-medium">可用占位符</div>
-            <div>{"{a}=系列名, {b}=类目名, {c}=数值, {d}=百分比(饼图)"}</div>
-            <div className="mt-1 font-medium">常用模板 + 输出示例</div>
-            <div>{"1) {b}: {c}  ->  周一: 120"}</div>
-            <div>{"2) {a}<br/>{b}: {c}  ->  销量<br/>周一: 120"}</div>
-            <div>{"3) {b}: {c} ({d}%)  ->  访问来源: 335 (42%)"}</div>
-            <div>{"4) ￥{c} / {b}  ->  ￥120 / 周一"}</div>
-          </TooltipContent>
-        </Tooltip>
-      </TooltipProvider>
+      <ConfigHintIcon label="Tooltip Formatter" contentClassName="max-w-[360px]">
+        <div className="font-medium">可用占位符</div>
+        <div>{"{a}=系列名, {b}=类目名, {c}=数值, {d}=百分比(饼图)"}</div>
+        <div className="mt-1 font-medium">常用模板 + 输出示例</div>
+        <div>{"1) {b}: {c}  ->  周一: 120"}</div>
+        <div>{"2) {a}<br/>{b}: {c}  ->  销量<br/>周一: 120"}</div>
+        <div>{"3) {b}: {c} ({d}%)  ->  访问来源: 335 (42%)"}</div>
+        <div>{"4) ￥{c} / {b}  ->  ￥120 / 周一"}</div>
+      </ConfigHintIcon>
     </div>
   );
   const mergeOptionPatch = useCallback(
@@ -593,6 +575,7 @@ export function PanelConfigSidebar({
   return (
     <ScopeConfigProvider
       scope={showScopePanel ? viewElementScope : undefined}
+      element={selectedElement}
       warnings={scopeWarnings}
       scrollContainerRef={sidebarScrollRef}
     >
@@ -1102,15 +1085,12 @@ export function PanelConfigSidebar({
                         <div>类目（逗号分隔）</div>
                         <Input
                           className="h-7"
-                          value={(el.chart?.labels ?? []).join(",")}
+                          value={getChartLabelsDisplayText(el.chart)}
                           onChange={(e) =>
                             updateElement(el.id, {
                               chart: {
                                 ...(el.chart ?? {}),
-                                labels: e.target.value
-                                  .split(",")
-                                  .map((s) => s.trim())
-                                  .filter(Boolean),
+                                labelsText: e.target.value,
                               },
                             })
                           }
@@ -2364,13 +2344,10 @@ export function PanelConfigSidebar({
                       <label className="block space-y-1">
                         <div>类目（逗号分隔）</div>
                         <Input
-                          value={(selectedElement.chart?.labels ?? []).join(",")}
+                          value={getChartLabelsDisplayText(selectedElement.chart)}
                           onChange={(e) =>
                             updateSelectedChart({
-                              labels: e.target.value
-                                .split(",")
-                                .map((s) => s.trim())
-                                .filter(Boolean),
+                              labelsText: e.target.value,
                             })
                           }
                           className="h-7"
@@ -2846,10 +2823,10 @@ export function PanelConfigSidebar({
                           onCheckedChange={(checked) => setIsAdvancedOptionMode(checked === true)}
                         />
                         <span>开启高级模式（直接编辑图表 JSON 配置）</span>
+                        <ConfigHintIcon label="图表 JSON 高级模式">
+                          基础配置会先生成图表配置，高级模式会在此基础上覆盖（深度合并）。
+                        </ConfigHintIcon>
                       </label>
-                      <div className="rounded border border-border/60 bg-background px-2 py-1.5 text-[11px] text-muted-foreground">
-                        基础配置会先生成图表配置，高级模式会在此基础上覆盖（深度合并）。
-                      </div>
                       {isAdvancedOptionMode ? (
                         <>
                           <Textarea
@@ -3241,8 +3218,11 @@ export function PanelConfigSidebar({
                         className="h-20 w-full rounded border border-border/60 object-cover"
                       />
                     ) : null}
-                    <div className="text-[11px] text-muted-foreground">
-                      设置占位图或图标后，节点上将隐藏进度条，改为点击图标播放/暂停。
+                    <div className="flex items-center gap-1">
+                      <div className="text-[11px] text-muted-foreground">音频占位图</div>
+                      <ConfigHintIcon label="音频占位图">
+                        设置占位图或图标后，节点上将隐藏进度条，改为点击图标播放/暂停。
+                      </ConfigHintIcon>
                     </div>
                   </>
                 )}
@@ -3358,12 +3338,10 @@ export function PanelConfigSidebar({
                       </label>
                     </div>
                   )}
-                  <div className="rounded border border-border/60 bg-background px-2 py-1.5 text-[11px] text-muted-foreground">
-                    网格子节点可跨越多格，占据更大区域，便于复杂布局。
-                  </div>
                 </>,
                 true,
-                ["网格", "跨列", "跨行", "span", "slot"]
+                ["网格", "跨列", "跨行", "span", "slot"],
+                <>网格子节点可跨越多格，占据更大区域，便于复杂布局。</>
               )
               : null
             : null}
@@ -3409,9 +3387,6 @@ export function PanelConfigSidebar({
                 {renderFieldGroup(
                   "高级（Canvas 脚本）",
                   <>
-                    <div className="rounded border border-border/60 bg-background px-2 py-1.5 text-[11px] text-muted-foreground">
-                      可输入 Canvas 绘制逻辑，变量：ctx、width、height、element。脚本异常会被安全忽略。
-                    </div>
                     <Textarea
                       value={selectedElement.geometryScript ?? ""}
                       onChange={(e) => updateSelectedGeometry({ geometryScript: e.target.value || undefined })}
@@ -3419,6 +3394,9 @@ export function PanelConfigSidebar({
                       className="h-36 font-mono text-[11px]"
                       placeholder="// 例: ctx.fillStyle = 'rgba(255,255,255,0.25)'; ctx.fillRect(8,8,width-16,height-16);"
                     />
+                  </>,
+                  <>
+                    可输入 Canvas 绘制逻辑，变量：ctx、width、height、element。脚本异常会被安全忽略。
                   </>
                 )}
                 {renderFieldGroup(
@@ -3610,12 +3588,12 @@ export function PanelConfigSidebar({
                     </label>
                   </div>
                 )}
-                <div className="rounded border border-border/60 bg-background px-2 py-1.5 text-[11px] text-muted-foreground">
-                  其他节点拖拽靠近该网格槽位中心时会自动吸附，并在节点树显示为该网格子节点。
-                </div>
               </>,
               true,
-              ["网格", "grid", "行", "列", "间距", "内边距", "吸附", "阈值"]
+              ["网格", "grid", "行", "列", "间距", "内边距", "吸附", "阈值"],
+              <>
+                其他节点拖拽靠近该网格槽位中心时会自动吸附，并在节点树显示为该网格子节点。
+              </>
             )
           ) : selectedElement.materialType === "reference" ? (
             renderSection(
@@ -3673,9 +3651,9 @@ export function PanelConfigSidebar({
                         </SelectContent>
                       </Select>
                     </label>
-                    <div className="rounded border border-border/60 bg-background px-2 py-1.5 text-[11px] text-muted-foreground">
-                      浅拷贝会实时同步被引用图层；深拷贝会固定当前快照，不再随源变化。
-                    </div>
+                  </>,
+                  <>
+                    浅拷贝会实时同步被引用图层；深拷贝会固定当前快照，不再随源变化。
                   </>
                 )}
               </>,

package/src/panel/components/SelectLayer.tsx

@@ -74,6 +74,7 @@ export function SelectLayer({
         if (selectedIdSet.size > 0) {
           if (
             target?.closest(".moveable-control-box") ||
+            target?.closest(".moveable-group") ||
             target?.closest(".moveable-line") ||
             target?.closest(".moveable-control") ||
             target?.closest(".moveable-direction")

package/src/panel/components/ViewElementScopePanel.tsx

@@ -1,6 +1,8 @@
 import { useEffect, useRef, useState } from "react";
 
 import { formatViewElementScope } from "../utils/scope-template";
+import { ConfigHintIcon } from "./ConfigHintIcon";
+import { ScopeTemplateUsageHint } from "./scope-config/ScopeTemplateUsageHint";
 
 const SCOPE_COLLAPSE_STORAGE_KEY = "panel:config-scope-collapsed";
 
@@ -43,6 +45,9 @@ export function ViewElementScopePanel({ scope }: ViewElementScopePanelProps) {
       <div className="flex items-center justify-between gap-2">
         <div className="flex min-w-0 items-center gap-1.5">
           <div className="text-[11px] font-medium text-foreground">Scope 数据</div>
+          <ConfigHintIcon label="Scope 模版" contentClassName="max-w-[380px]">
+            <ScopeTemplateUsageHint />
+          </ConfigHintIcon>
           {scopeUpdated ? (
             <span className="shrink-0 rounded bg-sky-500/15 px-1.5 py-0.5 text-[10px] font-medium text-sky-700 dark:text-sky-300">
               已更新
@@ -64,14 +69,6 @@ export function ViewElementScopePanel({ scope }: ViewElementScopePanelProps) {
           >
             {formatViewElementScope(scope)}
           </pre>
-          <p className="mt-1.5 text-[10px] leading-relaxed text-muted-foreground">
-            表单中可使用模版字符串引用 scope，例如{" "}
-            <code className="rounded bg-muted px-1">{`{scope?.a||0}`}</code>
-            、
-            <code className="rounded bg-muted px-1">{`{scope?.name||''}`}</code>
-            。支持 <code className="rounded bg-muted px-1">?.</code> 与{" "}
-            <code className="rounded bg-muted px-1">||</code> 占位。
-          </p>
         </>
       ) : null}
     </div>

package/src/panel/components/scope-config/ScopeConfigContext.tsx

@@ -8,11 +8,13 @@ import {
   type RefObject,
 } from "react";
 
+import type { PanelElement } from "../../types";
 import type { ScopeTemplateWarning } from "../../utils/scope-template-warnings";
 import { scopeFieldDomId } from "../../utils/scope-field-labels";
 import { groupScopeWarningsByField } from "../../utils/scope-template-warnings";
 
 import { ScopeTemplateAutocompleteHost } from "./ScopeTemplateAutocompleteHost";
+import { ScopeTemplatePreviewHost } from "./ScopeTemplatePreviewHost";
 
 type ScopeConfigContextValue = {
   warnings: ScopeTemplateWarning[];
@@ -83,11 +85,13 @@ function attachInlineHints(
 
 export function ScopeConfigProvider({
   scope,
+  element,
   warnings,
   scrollContainerRef,
   children,
 }: {
   scope?: unknown;
+  element?: PanelElement | null;
   warnings: ScopeTemplateWarning[];
   scrollContainerRef?: RefObject<HTMLElement | null>;
   children: ReactNode;
@@ -156,6 +160,11 @@ export function ScopeConfigProvider({
         scope={scope}
         containerRef={scrollContainerRef}
       />
+      <ScopeTemplatePreviewHost
+        scope={scope}
+        element={element ?? null}
+        containerRef={scrollContainerRef}
+      />
     </ScopeConfigContext.Provider>
   );
 }