From 7ce640627df62377d8340f267ecb74fa1ef3ddbc Mon Sep 17 00:00:00 2001
From: roymondchen <roymondchen@tencent.com>
Date: Thu, 7 May 2026 20:31:25 +0800
Subject: [PATCH] =?UTF-8?q?feat(editor):=20=E6=96=B0=E5=A2=9E=20stage-top?=
 =?UTF-8?q?=20=E6=8F=92=E6=A7=BD=E7=94=A8=E4=BA=8E=E5=9C=A8=E7=94=BB?=
 =?UTF-8?q?=E5=B8=83=E4=B8=8A=E6=96=B9=E6=8F=92=E5=85=A5=E8=87=AA=E5=AE=9A?=
 =?UTF-8?q?=E4=B9=89=E5=85=83=E7=B4=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ScrollViewer 增加 before 具名插槽，Stage 据此暴露 stage-top 插槽，
经 Workspace、Editor 逐层透传，并补充对应类型定义与文档说明。

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/api/editor/slots.md                      | 22 +++++++++++++++++++
 packages/editor/src/Editor.vue                |  1 +
 .../editor/src/components/ScrollViewer.vue    |  5 ++++-
 .../src/layouts/workspace/Workspace.vue       |  4 +++-
 .../src/layouts/workspace/viewer/Stage.vue    |  8 ++++++-
 packages/editor/src/type.ts                   | 12 +++++++++-
 6 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/docs/api/editor/slots.md b/docs/api/editor/slots.md
index eaee7654..10d2bd4b 100644
--- a/docs/api/editor/slots.md
+++ b/docs/api/editor/slots.md
@@ -270,6 +270,28 @@
 
 - **默认：** [Stage.vue](https://github.com/Tencent/tmagic-editor/blob/239b5d3efeae916a8cf3e3566d88063ecccc0553/packages/editor/src/layouts/workspace/Stage.vue)
 
+## stage-top
+
+- **详情：** 画布上方位置，与画布共享同一个滚动容器，渲染在画布之前，可用于在画布顶部插入自定义元素，例如顶部工具条、提示信息等
+
+- **默认：** 无
+
+:::warning
+如设置了[stage](#stage)插槽，此插槽将失效
+:::
+
+- **示例：**
+
+```html
+<template>
+  <m-editor>
+    <template #stage-top>
+      <div class="custom-stage-top">画布顶部自定义内容</div>
+    </template>
+  </m-editor>
+</template>
+```
+
 ## workspace-content
 
 - **详情：** 编辑器中间区域内，画布上方位置
diff --git a/packages/editor/src/Editor.vue b/packages/editor/src/Editor.vue
index 394a9add..642914cb 100644
--- a/packages/editor/src/Editor.vue
+++ b/packages/editor/src/Editor.vue
@@ -86,6 +86,7 @@
           :stage-content-menu="stageContentMenu"
           :custom-content-menu="customContentMenu"
         >
+          <template #stage-top><slot name="stage-top"></slot></template>
           <template #stage><slot name="stage"></slot></template>
           <template #workspace-content><slot name="workspace-content" :editorService="editorService"></slot></template>
         </Workspace>
diff --git a/packages/editor/src/components/ScrollViewer.vue b/packages/editor/src/components/ScrollViewer.vue
index 0593fdfc..865e2ba9 100644
--- a/packages/editor/src/components/ScrollViewer.vue
+++ b/packages/editor/src/components/ScrollViewer.vue
@@ -1,6 +1,7 @@
 <template>
   <div class="m-editor-scroll-viewer-container" ref="container">
     <div ref="target" :style="style">
+      <slot name="before"></slot>
       <slot></slot>
     </div>
 
@@ -29,7 +30,7 @@ import { computed, onBeforeUnmount, onMounted, ref, useTemplateRef, watch } from
 
 import { isNumber } from '@tmagic/utils';
 
-import type { ScrollViewerEvent } from '@editor/type';
+import type { ScrollViewerEvent, ScrollViewerSlots } from '@editor/type';
 import { ScrollViewer } from '@editor/utils/scroll-viewer';
 
 import ScrollBar from './ScrollBar.vue';
@@ -38,6 +39,8 @@ defineOptions({
   name: 'MEditorScrollViewer',
 });
 
+defineSlots<ScrollViewerSlots>();
+
 const props = withDefaults(
   defineProps<{
     width?: number | string;
diff --git a/packages/editor/src/layouts/workspace/Workspace.vue b/packages/editor/src/layouts/workspace/Workspace.vue
index 95a71876..7240a190 100644
--- a/packages/editor/src/layouts/workspace/Workspace.vue
+++ b/packages/editor/src/layouts/workspace/Workspace.vue
@@ -9,7 +9,9 @@
         :disabled-stage-overlay="disabledStageOverlay"
         :stage-content-menu="stageContentMenu"
         :custom-content-menu="customContentMenu"
-      ></MagicStage>
+      >
+        <template #stage-top><slot name="stage-top"></slot></template>
+      </MagicStage>
     </slot>
 
     <slot name="workspace-content"></slot>
diff --git a/packages/editor/src/layouts/workspace/viewer/Stage.vue b/packages/editor/src/layouts/workspace/viewer/Stage.vue
index d445cb21..9ed6e58d 100644
--- a/packages/editor/src/layouts/workspace/viewer/Stage.vue
+++ b/packages/editor/src/layouts/workspace/viewer/Stage.vue
@@ -27,6 +27,10 @@
 
     <NodeListMenu></NodeListMenu>
 
+    <template #before>
+      <slot name="stage-top"></slot>
+    </template>
+
     <template #content>
       <StageOverlay v-if="!disabledStageOverlay"></StageOverlay>
 
@@ -52,7 +56,7 @@ import { calcValueByFontsize, getIdFromEl } from '@tmagic/utils';
 import ScrollViewer from '@editor/components/ScrollViewer.vue';
 import { useServices } from '@editor/hooks';
 import { useStage } from '@editor/hooks/use-stage';
-import type { CustomContentMenuFunction, MenuButton, MenuComponent, StageOptions } from '@editor/type';
+import type { CustomContentMenuFunction, MenuButton, MenuComponent, StageOptions, StageSlots } from '@editor/type';
 import { DragType, Layout } from '@editor/type';
 import { getEditorConfig } from '@editor/utils/config';
 import { KeyBindingContainerKey } from '@editor/utils/keybinding-config';
@@ -65,6 +69,8 @@ defineOptions({
   name: 'MEditorStage',
 });
 
+defineSlots<StageSlots>();
+
 const props = withDefaults(
   defineProps<{
     stageOptions: StageOptions;
diff --git a/packages/editor/src/type.ts b/packages/editor/src/type.ts
index 60fa2881..1f73b4cf 100644
--- a/packages/editor/src/type.ts
+++ b/packages/editor/src/type.ts
@@ -73,7 +73,17 @@ export interface FrameworkSlots {
   'page-list-popover'(props: { list: (MPage | MPageFragment)[] }): any;
 }
 
-export interface WorkspaceSlots {
+export interface ScrollViewerSlots {
+  before(props: {}): any;
+  content(props: {}): any;
+  default(props: {}): any;
+}
+
+export interface StageSlots extends ScrollViewerSlots {
+  'stage-top'(props: {}): any;
+}
+
+export interface WorkspaceSlots extends StageSlots {
   stage(props: {}): any;
   'workspace-content'(props: {}): any;
 }