跳到主要内容

API 参考

Monaco 组件​

Monaco 是核心的代码编辑器组件，基于 Monaco Editor 和 Shiki 构建，提供丰富的代码编辑功能。

基本用法​

<template>
  <Monaco
    language="javascript"
    theme="vitesse-light"
    :value="code"
    height="400px"
    :show-toolbar="true"
    :auto-resize="true"
    :context-menu="{ enabled: true, items: 'full', variant: 'glass' }"
    :minimap-context-menu="{ enabled: true, items: 'basic', variant: 'glass' }"
    @change="handleChange"
    @ready="handleReady"
  />
</template>

Props​

currentLanguage​

  • 类型: BundledLanguage
  • 默认值: 'javascript'
  • 描述: 设置编辑器的当前语言模式

支持的语言包括：javascript, typescript, python, html, css, json, markdown, vue, react, go, rust, php, java, c, cpp, csharp 等。

<Monaco current-language="typescript" />

currentTheme​

  • 类型: BundledTheme
  • 默认值: 'vitesse-light'
  • 描述: 设置编辑器当前主题

支持的主题包括：vitesse-light, vitesse-dark, github-light, github-dark, one-dark-pro, dracula, nord, material-theme 等。

<Monaco current-theme="vitesse-dark" />

languages​

  • 类型: BundledLanguage[]
  • 默认值: ['javascript', 'typescript', 'python', 'html', 'css', 'json']
  • 描述: 编辑器支持的语言列表
<Monaco :languages="['javascript', 'typescript', 'vue', 'go']" />

themes​

  • 类型: BundledTheme[]
  • 默认值: ['vitesse-light', 'vitesse-dark', 'github-light', 'github-dark']
  • 描述: 编辑器支持的主题列表
<Monaco :themes="['vitesse-light', 'vitesse-dark', 'one-dark-pro']" />

value​

  • 类型: string
  • 默认值: ''
  • 描述: 编辑器的初始内容
<Monaco :value="initialCode" />

height​

  • 类型: string
  • 默认值: '400px'
  • 描述: 编辑器的高度
<Monaco height="600px" />

showToolbar​

  • 类型: boolean
  • 默认值: true
  • 描述: 是否显示顶部工具栏
<Monaco :show-toolbar="false" />

autoResize​

  • 类型: boolean
  • 默认值: true
  • 描述: 是否启用自动尺寸调整
<Monaco :auto-resize="false" />

monacoEditClass​

  • 类型: string
  • 默认值: undefined
  • 描述: 编辑器容器的自定义 CSS 类名
<Monaco monaco-edit-class="my-custom-editor" />

fileName​

  • 类型: string
  • 默认值: undefined
  • 描述: 工具栏显示的文件名
<Monaco file-name="main.ts" />

contextMenu​

  • 类型: ContextMenuConfig
  • 默认值: { enabled: true, items: 'full', variant: 'glass' }
  • 描述: 编辑器区域自定义右键菜单配置

ContextMenuConfig 接口​

interface ContextMenuConfig {
  enabled?: boolean; // 是否启用右键菜单
  items?: string[] | "minimal" | "basic" | "full"; // 菜单项配置
  customItems?: ContextMenuItem[]; // 自定义菜单项
  variant?: "classic" | "glass"; // 菜单样式变体
  teleportTarget?: string | HTMLElement; // 菜单的挂载目标
}

预设菜单配置​

<!-- 最小菜单：复制、粘贴、全选 -->
<Monaco :context-menu="{ enabled: true, items: 'minimal', variant: 'glass' }" />

<!-- 基础菜单：复制、剪切、粘贴、全选、撤销、重做 -->
<Monaco :context-menu="{ enabled: true, items: 'basic', variant: 'glass' }" />

<!-- 完整菜单：所有功能 -->
<Monaco :context-menu="{ enabled: true, items: 'full', variant: 'glass' }" />

<!-- 经典样式菜单 -->
<Monaco :context-menu="{ enabled: true, items: 'full', variant: 'classic' }" />

<!-- 自定义菜单项 -->
<Monaco
  :context-menu="{
    enabled: true,
    items: ['copy', 'paste', 'selectAll'],
    variant: 'glass',
    teleportTarget: '.my-menu-container',
    customItems: [
      {
        type: 'separator',
      },
      {
        type: 'item',
        id: 'custom-action',
        label: '自定义操作',
        shortcut: 'Ctrl+Shift+X',
        action: () => console.log('自定义操作'),
      },
    ],
  }"
/>

<!-- 指定菜单挂载到特定DOM元素 -->
<Monaco
  :context-menu="{
    enabled: true,
    items: 'full',
    variant: 'glass',
    teleportTarget: document.getElementById('menu-container'),
  }"
/>

teleportTarget​

  • 类型: string | HTMLElement
  • 默认值: '.monaco-editor'
  • 描述: 指定右键菜单的挂载目标，用于控制菜单渲染的位置
<!-- 挂载到特定选择器 -->
<Monaco teleport-target=".my-container" />

<!-- 挂载到DOM元素 -->
<Monaco :teleport-target="myElement" />

minimapContextMenu​

  • 类型: MinimapContextMenuConfig
  • 默认值: { enabled: true, items: 'basic', variant: 'glass' }
  • 描述: Minimap区域专用右键菜单配置

MinimapContextMenuConfig 接口​

interface MinimapContextMenuConfig {
  enabled?: boolean; // 是否启用Minimap右键菜单
  items?: string[] | "minimal" | "basic" | "full"; // 菜单项配置
  customItems?: ContextMenuItem[]; // 自定义菜单项
  variant?: "classic" | "glass"; // 菜单样式变体
  teleportTarget?: string | HTMLElement; // 菜单的挂载目标
}

Minimap菜单示例​

<!-- Minimap基础菜单 -->
<Monaco
  :minimap-context-menu="{ enabled: true, items: 'basic', variant: 'glass' }"
/>

<!-- Minimap完整菜单 -->
<Monaco
  :minimap-context-menu="{ enabled: true, items: 'full', variant: 'glass' }"
/>

<!-- 禁用Minimap菜单 -->
<Monaco :minimap-context-menu="{ enabled: false }" />

Events​

change​

  • 参数: (value: string) => void
  • 描述: 当编辑器内容发生变化时触发
<Monaco @change="handleCodeChange" />

ready​

  • 参数: (editor: EditInstance) => void
  • 描述: 当编辑器初始化完成时触发
<Monaco @ready="handleEditorReady" />

Slots​

toolbar​

  • 描述: 自定义工具栏内容
<Monaco>
  <template #toolbar>
    <div class="custom-toolbar">
      <button @click="runCode">运行代码</button>
      <button @click="saveCode">保存</button>
      <button @click="shareCode">分享</button>
    </div>
  </template>
</Monaco>

暴露的方法​

通过 ref 可以访问以下方法：

getEditor()​

  • 返回: EditInstance | null
  • 描述: 获取 Monaco Editor 实例
<script setup>
const monacoRef = ref();

const getEditorInstance = () => {
  const editor = monacoRef.value?.getEditor();
  if (editor) {
    console.log("编辑器实例:", editor);
  }
};
</script>

setValue(value: string)​

  • 参数: value - 要设置的代码内容
  • 描述: 设置编辑器内容
<script setup>
const monacoRef = ref();

const updateCode = () => {
  monacoRef.value?.setValue('console.log("新代码")');
};
</script>

getValue()​

  • 返回: string
  • 描述: 获取编辑器当前内容
<script setup>
const monacoRef = ref();

const getCurrentCode = () => {
  const code = monacoRef.value?.getValue();
  console.log("当前代码:", code);
};
</script>

focus()​

  • 描述: 让编辑器获得焦点
<script setup>
const monacoRef = ref();

const focusEditor = () => {
  monacoRef.value?.focus();
};
</script>

setTheme(theme: BundledTheme)​

  • 参数: theme - 要切换的主题
  • 描述: 动态切换编辑器主题
<script setup>
const monacoRef = ref();

const switchTheme = () => {
  monacoRef.value?.setTheme("vitesse-dark");
};
</script>

setLanguage(language: BundledLanguage)​

  • 参数: language - 要切换的语言
  • 描述: 动态切换编辑器语言
<script setup>
const monacoRef = ref();

const switchLanguage = () => {
  monacoRef.value?.setLanguage("typescript");
};
</script>

layout()​

  • 描述: 手动触发编辑器布局更新
<script setup>
const monacoRef = ref();

const refreshLayout = () => {
  monacoRef.value?.layout();
};
</script>

enableAutoResize()​

  • 描述: 启用自动尺寸调整
<script setup>
const monacoRef = ref();

const enableResize = () => {
  monacoRef.value?.enableAutoResize();
};
</script>

disableAutoResize()​

  • 描述: 禁用自动尺寸调整
<script setup>
const monacoRef = ref();

const disableResize = () => {
  monacoRef.value?.disableAutoResize();
};
</script>

copyCode()​

  • 描述: 复制当前代码到剪贴板（支持多种策略）
<script setup>
const monacoRef = ref();

const copyCurrentCode = () => {
  monacoRef.value?.copyCode();
};
</script>

pasteCode()​

  • 描述: 从剪贴板粘贴内容到编辑器（支持多种策略）
<script setup>
const monacoRef = ref();

const pasteFromClipboard = () => {
  monacoRef.value?.pasteCode();
};
</script>

formatCode()​

  • 描述: 格式化当前代码
<script setup>
const monacoRef = ref();

const formatCurrentCode = () => {
  monacoRef.value?.formatCode();
};
</script>

useMonacoEdit Hook​

useMonacoEdit 是底层的编辑器初始化钩子，用于创建和管理 Monaco Editor 实例。

基本用法​

import { useMonacoEdit } from "vue-shiki-monaco";

const { initMonacoEdit, destroy, setTheme, setLanguage } = useMonacoEdit({
  target: editorElement,
  languages: ["javascript", "typescript"],
  themes: ["vitesse-light", "vitesse-dark"],
  codeValue: 'console.log("Hello World")',
  defaultTheme: "vitesse-light",
  defaultLanguage: "javascript",
  contextMenu: {
    enabled: true,
    items: "full",
  },
});

参数​

MonacoOptions​

interface MonacoOptions
  extends monaco.editor.IStandaloneEditorConstructionOptions {
  target: HTMLElement; // 编辑器挂载的目标元素
  languages: BundledLanguage[]; // 支持的语言列表
  codeValue: string; // 初始代码内容
  themes: BundledTheme[]; // 支持的主题列表
  defaultTheme: BundledTheme; // 默认主题
  defaultLanguage: BundledLanguage; // 默认语言
  contextMenu?: {
    // 右键菜单配置
    enabled?: boolean;
    items?: string[] | "minimal" | "basic" | "full";
    customItems?: ContextMenuItem[];
  };
}

返回值​

UseMonacoEditReturn​

interface UseMonacoEditReturn {
  initMonacoEdit: () => Promise<EditInstance>; // 初始化编辑器
  destroy: () => void; // 销毁编辑器
  registerLanguage: (language: string) => void; // 注册新语言
  setTheme: (theme: BundledTheme) => Promise<void>; // 切换主题
  setLanguage: (language: BundledLanguage) => Promise<void>; // 切换语言
  layout: () => void; // 重新布局
  enableAutoResize: () => void; // 启用自动调整
  disableAutoResize: () => void; // 禁用自动调整
  editInstance: EditInstance | null; // 编辑器实例
  onContextMenu: (callback: (event: MouseEvent) => void) => void; // 编辑器右键菜单回调
  offContextMenu: () => void; // 移除编辑器右键菜单回调
  onMinimapContextMenu: (callback: (event: MouseEvent) => void) => void; // Minimap右键菜单回调
  offMinimapContextMenu: () => void; // 移除Minimap右键菜单回调
}

方法详解​

initMonacoEdit()​

  • 返回: Promise<EditInstance>
  • 描述: 异步初始化 Monaco Editor 实例
  • 用法: 
    const editor = await initMonacoEdit();

destroy()​

  • 描述: 销毁编辑器实例，释放内存和事件监听器
  • 用法: 
    destroy();

setTheme(theme)​

  • 参数: theme: BundledTheme - 要切换的主题
  • 返回: Promise<void>
  • 描述: 动态切换编辑器主题
  • 用法: 
    await setTheme("vitesse-dark");

setLanguage(language)​

  • 参数: language: BundledLanguage - 要切换的语言
  • 返回: Promise<void>
  • 描述: 动态切换编辑器语言
  • 用法: 
    await setLanguage("typescript");

enableAutoResize() / disableAutoResize()​

  • 描述: 启用或禁用编辑器自动尺寸调整
  • 用法: 
    enableAutoResize(); // 启用
    disableAutoResize(); // 禁用

onContextMenu(callback) / offContextMenu()​

  • 描述: 注册或移除编辑器区域右键菜单事件回调

  • 用法:

    onContextMenu((event) => {
      console.log("编辑器右键菜单事件:", event);
    });

    offContextMenu(); // 移除回调

onMinimapContextMenu(callback) / offMinimapContextMenu()​

  • 描述: 注册或移除Minimap区域右键菜单事件回调

  • 用法:

    onMinimapContextMenu((event) => {
      console.log("Minimap右键菜单事件:", event);
    });

    offMinimapContextMenu(); // 移除回调

useContextMenu Hook​

useContextMenu 是用于管理自定义右键菜单的钩子。

基本用法​

import { useContextMenu } from "vue-shiki-monaco";

const contextMenu = useContextMenu({
  items: [
    {
      type: "item",
      id: "copy",
      label: "复制",
      shortcut: "Ctrl+C",
      action: () => console.log("复制"),
    },
    { type: "separator" },
    {
      type: "item",
      id: "paste",
      label: "粘贴",
      shortcut: "Ctrl+V",
      action: () => console.log("粘贴"),
    },
  ],
  target: ".monaco-editor", // 指定菜单的目标容器
});

参数和返回值​

UseContextMenuOptions​

interface UseContextMenuOptions {
  items: ContextMenuItem[]; // 菜单项列表
  target?: string | HTMLDivElement; // 菜单的目标容器
  onShow?: () => void; // 显示时回调
  onHide?: () => void; // 隐藏时回调
}

UseContextMenuReturn​

interface UseContextMenuReturn {
  isVisible: Ref<boolean>; // 菜单可见性
  position: ContextMenuPosition; // 菜单位置
  items: Ref<ContextMenuItem[]>; // 菜单项
  show: (
    event: MouseEvent,
    menuItems: ContextMenuItem[],
    target?: HTMLDivElement,
  ) => void; // 显示菜单，支持动态指定目标元素
  hide: () => void; // 隐藏菜单
  handleItemClick: (item: MenuItem) => void; // 处理菜单项点击
  updateTarget: (target: HTMLDivElement) => void; // 更新目标元素
}

ContextMenuItem 类型​

// 菜单项
interface MenuItem {
  type: "item";
  id: string; // 唯一标识
  label: string; // 显示文本
  icon?: string; // 图标类名
  shortcut?: string; // 快捷键文本
  disabled?: boolean; // 是否禁用
  action: () => void; // 点击回调
}

// 分隔符
interface MenuItemSeparator {
  type: "separator";
}

type ContextMenuItem = MenuItem | MenuItemSeparator;

MonacoDiff 组件​

MonacoDiff 是专门用于显示代码差异对比的组件，基于 Monaco Editor 的 Diff Editor 构建，提供强大的代码对比功能。

基本用法​

<template>
  <MonacoDiff
    :old-model="oldCode"
    :new-model="newCode"
    language="typescript"
    theme="vitesse-light"
    height="500px"
    :show-toolbar="true"
    :auto-resize="true"
    :context-menu="{ enabled: true, items: 'full', variant: 'glass' }"
    :minimap-context-menu="{ enabled: true, items: 'basic', variant: 'glass' }"
    @change="handleChange"
    @ready="handleReady"
  />
</template>

Props​

oldModel​

  • 类型: string
  • 必填: true
  • 描述: 原始代码内容（左侧编辑器显示）
<MonacoDiff old-model="const a = 1;" />

newModel​

  • 类型: string
  • 必填: true
  • 描述: 修改后的代码内容（右侧编辑器显示）
<MonacoDiff new-model="const a = 2;" />

diffViewType​

  • 类型: 'default' | 'inline' | 'unified'
  • 默认值: 'default'
  • 描述: 差异显示模式
<!-- 默认并排模式 -->
<MonacoDiff diff-view-type="default" />

<!-- 内联模式 -->
<MonacoDiff diff-view-type="inline" />

<!-- 统一模式 -->
<MonacoDiff diff-view-type="unified" />

currentLanguage​

  • 类型: BundledLanguage
  • 默认值: 'typescript'
  • 描述: 代码语言模式
<MonacoDiff current-language="javascript" />

currentTheme​

  • 类型: BundledTheme
  • 默认值: 'vitesse-light'
  • 描述: 编辑器主题
<MonacoDiff current-theme="vitesse-dark" />

languages​

  • 类型: BundledLanguage[]
  • 默认值: ['typescript']
  • 描述: 支持的语言列表
<MonacoDiff :languages="['typescript', 'javascript', 'vue']" />

themes​

  • 类型: BundledTheme[]
  • 默认值: ['vitesse-light', 'vitesse-dark']
  • 描述: 支持的主题列表
<MonacoDiff :themes="['vitesse-light', 'vitesse-dark', 'github-light']" />

height​

  • 类型: string
  • 默认值: '400px'
  • 描述: 编辑器高度
<MonacoDiff height="600px" />

showToolbar​

  • 类型: boolean
  • 默认值: true
  • 描述: 是否显示顶部工具栏（包含差异导航）
<MonacoDiff :show-toolbar="false" />

autoResize​

  • 类型: boolean
  • 默认值: true
  • 描述: 是否启用自动尺寸调整
<MonacoDiff :auto-resize="false" />

fileName​

  • 类型: string
  • 默认值: 'Untitled'
  • 描述: 工具栏显示的文件名
<MonacoDiff file-name="app.ts" />

contextMenu​

  • 类型: ContextMenuConfig
  • 默认值: { enabled: true, items: 'full', variant: 'glass' }
  • 描述: 编辑器区域右键菜单配置
<!-- 原始编辑器（左侧）菜单项：复制、查找替换、字体调整 -->
<!-- 修改编辑器（右侧）菜单项：完整功能菜单 -->
<MonacoDiff
  :context-menu="{
    enabled: true,
    items: 'full',
    variant: 'glass',
  }"
/>

minimapContextMenu​

  • 类型: MinimapContextMenuConfig
  • 默认值: { enabled: true, items: 'basic', variant: 'glass' }
  • 描述: Minimap区域右键菜单配置
<MonacoDiff
  :minimap-context-menu="{
    enabled: true,
    items: 'basic',
    variant: 'glass',
  }"
/>

Events​

change​

  • 参数: (value: string) => void
  • 描述: 当修改编辑器（右侧）内容发生变化时触发
<MonacoDiff @change="handleDiffChange" />

ready​

  • 参数: (editor: DiffEditInstance) => void
  • 描述: 当差异编辑器初始化完成时触发
<MonacoDiff @ready="handleDiffEditorReady" />

暴露的方法​

通过 ref 可以访问以下方法：

getEditor()​

  • 返回: DiffEditInstance | null
  • 描述: 获取 Monaco Diff Editor 实例
<script setup>
const diffRef = ref();

const getDiffEditorInstance = () => {
  const editor = diffRef.value?.getEditor();
  if (editor) {
    console.log("差异编辑器实例:", editor);
    // 可以访问 getOriginalEditor() 和 getModifiedEditor()
    const originalEditor = editor.getOriginalEditor();
    const modifiedEditor = editor.getModifiedEditor();
  }
};
</script>

focus()​

  • 描述: 让修改编辑器（右侧）获得焦点
<script setup>
const diffRef = ref();

const focusDiffEditor = () => {
  diffRef.value?.focus();
};
</script>

setTheme(theme: BundledTheme)​

  • 参数: theme - 要切换的主题
  • 描述: 动态切换编辑器主题
<script setup>
const diffRef = ref();

const switchTheme = () => {
  diffRef.value?.setTheme("vitesse-dark");
};
</script>

layout()​

  • 描述: 手动触发编辑器布局更新
<script setup>
const diffRef = ref();

const refreshLayout = () => {
  diffRef.value?.layout();
};
</script>

enableAutoResize() / disableAutoResize()​

  • 描述: 启用或禁用自动尺寸调整
<script setup>
const diffRef = ref();

const toggleAutoResize = () => {
  diffRef.value?.enableAutoResize();
  // 或
  diffRef.value?.disableAutoResize();
};
</script>

工具栏功能​

MonacoDiff 组件的工具栏包含以下差异导航功能：

  • 差异计数器: 显示当前差异位置和总数（如 "2 / 5"）
  • 上一个差异按钮: 跳转到上一个差异位置
  • 下一个差异按钮: 跳转到下一个差异位置
  • 折叠/展开按钮: 折叠或展开未更改的代码区域

特殊功能​

差异导航​

  • 自动检测代码差异数量
  • 支持循环导航（从最后一个差异跳转到第一个）
  • 自动滚动到差异位置并居中显示

右键菜单分级​

  • 原始编辑器（左侧）: 只读模式，提供复制、查找替换、字体调整功能
  • 修改编辑器（右侧）: 完整编辑功能，支持所有菜单项

复制功能​

  • 工具栏复制按钮默认复制修改后的内容（右侧编辑器）
  • 支持现代剪贴板API和降级方案

useMonacoDiffEdit Hook​

useMonacoDiffEdit 是专门用于创建和管理 Monaco Diff Editor 实例的钩子。

基本用法​

import { useMonacoDiffEdit } from "vue-shiki-monaco";

const diffHook = useMonacoDiffEdit({
  target: diffEditorElement,
  languages: ["typescript", "javascript"],
  themes: ["vitesse-light", "vitesse-dark"],
  defaultTheme: "vitesse-light",
  contextMenu: {
    enabled: true,
    items: "full",
  },
});

// 初始化差异编辑器
const diffEditor = await diffHook.initMonacoDiffEdit();

// 创建模型
const originalModel = diffHook.createModel(oldCode, "typescript");
const modifiedModel = diffHook.createModel(newCode, "typescript");

// 设置差异模型
diffHook.setDiffModel({
  original: originalModel,
  modified: modifiedModel,
});

参数​

MonacoDiffOptions​

interface MonacoDiffOptions {
  target: HTMLElement; // 编辑器挂载的目标元素
  languages: BundledLanguage[]; // 支持的语言列表
  themes: BundledTheme[]; // 支持的主题列表
  defaultTheme: BundledTheme; // 默认主题
  diffViewType?: "default" | "inline" | "unified"; // 差异显示模式
  contextMenu?: {
    enabled?: boolean;
    items?: string[] | "minimal" | "basic" | "full";
    customItems?: ContextMenuItem[];
  };
}

返回值​

UseMonacoDiffEditReturn​

interface UseMonacoDiffEditReturn {
  initMonacoDiffEdit: () => Promise<DiffEditInstance>; // 初始化差异编辑器
  createModel: (content: string, language: string) => any; // 创建模型
  setDiffModel: (models: { original: any; modified: any }) => void; // 设置差异模型
  setDiffViewOptions: (viewType: string) => void; // 设置差异视图类型
  setTheme: (theme: BundledTheme) => Promise<void>; // 切换主题
  layout: () => void; // 重新布局
  enableAutoResize: () => void; // 启用自动调整
  disableAutoResize: () => void; // 禁用自动调整
  destroy: (target: HTMLElement) => void; // 销毁编辑器
  onOriginalContextMenu: (callback: (event: MouseEvent) => void) => void; // 原始编辑器右键菜单
  onModifiedContextMenu: (callback: (event: MouseEvent) => void) => void; // 修改编辑器右键菜单
  onMinimapContextMenu: (callback: (event: MouseEvent) => void) => void; // Minimap右键菜单
}

右键菜单重构改进​

在最新版本中，useContextMenu 钩子进行了重要的重构优化：

智能目标查找​

  • 自动查找容器: 在 show 方法中新增了智能查找功能，当未指定目标元素时，会自动向上查找最近的 .monaco-editor 或 .monaco-diff-editor 容器
  • 动态目标指定: show 方法新增 target 参数，允许在显示菜单时动态指定目标元素
  • 更新目标方法: 新增 updateTarget 方法，允许在显示菜单前更新目标元素

使用示例​

import { useContextMenu } from "vue-shiki-monaco";

const contextMenu = useContextMenu({
  items: menuItems,
});

// 方式1：让系统自动查找最近的编辑器容器
contextMenu.show(event, menuItems);

// 方式2：动态指定目标容器
const targetElement = document.querySelector(".my-editor-container");
contextMenu.show(event, menuItems, targetElement);

// 方式3：更新目标后显示
contextMenu.updateTarget(myEditorElement);
contextMenu.show(event, menuItems);

改进效果​

  • 更准确的定位: 菜单能够自动找到正确的编辑器容器，确保菜单显示在合适的位置
  • 更灵活的使用: 支持多编辑器场景下的动态目标切换
  • 更好的兼容性: 同时支持 Monaco Editor 和 Monaco Diff Editor 容器

TypeScript 类型定义​

Monaco 组件类型​

import type { BundledLanguage, BundledTheme } from "shiki";
import type { EditInstance } from "vue-shiki-monaco";

// 组件 Props
interface MonacoProps {
  currentLanguage?: BundledLanguage;
  currentTheme?: BundledTheme;
  languages?: BundledLanguage[];
  themes?: BundledTheme[];
  value?: string;
  height?: string;
  showToolbar?: boolean;
  autoResize?: boolean;
  monacoEditClass?: string;
  fileName?: string;
  teleportTarget?: string | HTMLElement; // 菜单的挂载目标
  contextMenu?: {
    enabled?: boolean;
    items?: string[] | "minimal" | "basic" | "full";
    customItems?: ContextMenuItem[];
    teleportTarget?: string | HTMLElement; // 菜单的挂载目标
  };
  minimapContextMenu?: {
    enabled?: boolean;
    items?: string[] | "minimal" | "basic" | "full";
    customItems?: ContextMenuItem[];
    variant?: "classic" | "glass";
    teleportTarget?: string | HTMLElement; // 菜单的挂载目标
  };
}

// 组件 Emits
interface MonacoEmits {
  change: [value: string];
  ready: [editor: EditInstance];
}

// 编辑器实例类型
type EditInstance = monaco.editor.IStandaloneCodeEditor;

MonacoDiff 组件类型​

import type { BundledLanguage, BundledTheme } from "shiki";
import type { DiffEditInstance } from "vue-shiki-monaco";

// MonacoDiff 组件 Props
interface MonacoDiffProps {
  oldModel: string; // 原始代码内容
  newModel: string; // 修改后的代码内容
  diffViewType?: "default" | "inline" | "unified"; // 差异显示模式
  currentLanguage?: BundledLanguage;
  currentTheme?: BundledTheme;
  languages?: BundledLanguage[];
  themes?: BundledTheme[];
  height?: string;
  showToolbar?: boolean;
  autoResize?: boolean;
  monacoEditClass?: string;
  fileName?: string;
  teleportTarget?: string | HTMLElement;
  contextMenu?: {
    enabled?: boolean;
    items?: string[] | "minimal" | "basic" | "full";
    customItems?: ContextMenuItem[];
    variant?: "classic" | "glass";
  };
  minimapContextMenu?: {
    enabled?: boolean;
    items?: string[] | "minimal" | "basic" | "full";
    customItems?: ContextMenuItem[];
    variant?: "classic" | "glass";
  };
}

// MonacoDiff 组件 Emits
interface MonacoDiffEmits {
  change: [value: string]; // 修改编辑器内容变化
  ready: [editor: DiffEditInstance]; // 差异编辑器就绪
}

// 差异编辑器实例类型
type DiffEditInstance = monaco.editor.IStandaloneDiffEditor;

Hook 类型​

import type * as monaco from "monaco-editor-core";
import type { BundledLanguage, BundledTheme } from "shiki";

// Hook 选项
interface MonacoOptions
  extends monaco.editor.IStandaloneEditorConstructionOptions {
  target: HTMLElement;
  languages: BundledLanguage[];
  codeValue: string;
  themes: BundledTheme[];
  defaultTheme: BundledTheme;
  defaultLanguage: BundledLanguage;
  contextMenu?: {
    enabled?: boolean;
    items?: string[] | "minimal" | "basic" | "full";
    customItems?: ContextMenuItem[];
  };
}

// Hook 返回值
interface UseMonacoEditReturn {
  initMonacoEdit: () => Promise<EditInstance>;
  destroy: () => void;
  registerLanguage: (language: string) => void;
  setTheme: (theme: BundledTheme) => Promise<void>;
  setLanguage: (language: BundledLanguage) => Promise<void>;
  layout: () => void;
  enableAutoResize: () => void;
  disableAutoResize: () => void;
  editInstance: EditInstance | null;
  onContextMenu: (callback: (event: MouseEvent) => void) => void;
  offContextMenu: () => void;
}

// 编辑器实例
type EditInstance = monaco.editor.IStandaloneCodeEditor;

右键菜单类型​

// 菜单位置
interface ContextMenuPosition {
  x: number;
  y: number;
  direction?: "down" | "up"; // 菜单显示方向
}

// 菜单项
interface MenuItem {
  type: "item";
  id: string;
  label: string;
  icon?: string;
  shortcut?: string;
  disabled?: boolean;
  action: () => void;
}

// 分隔符
interface MenuItemSeparator {
  type: "separator";
}

// 联合类型
type ContextMenuItem = MenuItem | MenuItemSeparator;

// 菜单预设
type MenuPreset = "minimal" | "basic" | "full";