Slidev Monaco 编辑器完整配置指南：setup 文件、自动类型、Shiki 主题与代码运行选项

Slidev Monaco 编辑器完整配置指南setup 文件、自动类型、Shiki 主题与代码运行选项【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev本篇围绕 Slidev 的 Monaco 编辑器定制能力展开如何编写setup/monaco.ts接入defineMonacoSetup、如何让编辑器自动获取依赖类型、如何复用 Shiki 主题保持一致的视觉风格以及如何通过 frontmatter 控制启用范围与严格模式。读完后可在 Slidev 幻灯片中直接落地一个类型提示完整、主题统一、行为可控的 Monaco 代码编辑环境。编写 Monaco 配置文件setup/monaco.tsSlidev 允许在客户端通过一个独立的 setup 文件对 Monaco 进行全局定制。在项目根目录创建./setup/monaco.ts从slidev/types导入defineMonacoSetup并导出一个接收monaco实例的函数import { defineMonacoSetup } from slidev/types export default defineMonacoSetup(async (monaco) { // use monaco to configure })defineMonacoSetup本质上是一个类型包装函数定义在 setups.ts// client side export type MonacoSetup (m: typeof monaco) AwaitableMonacoSetupReturn | void function defineSetupFn(fn: Fn) { return fn } export const defineMonacoSetup defineSetupMonacoSetup其返回值类型MonacoSetupReturn目前仅包含可选的editorOptions字段setups.tsexport interface MonacoSetupReturn { editorOptions?: monaco.editor.IEditorOptions }仓库内的实际示例位于 demo/composable-vue/setup/monaco.ts演示了如何用typescriptDefaults.addExtraLib注入一段虚拟类型声明让编辑器识别自定义的InjectionKeyimport { defineMonacoSetup } from slidev/types export default defineMonacoSetup((monaco) { monaco.typescript.typescriptDefaults.addExtraLib( import { InjectionKey } from vue export interface UserInfo { id: number; name: string } export const injectKeyUser: InjectionKeyUserInfo Symbol() , file:///root/context.ts, ) })从源码结构看该 setup 文件的执行时机在 packages/client/setup/monaco.ts 中被统一管理。整个 Monaco 初始化被封装为单例 Promisemonaco.ts流程大致为先注册MonacoEnvironmentworker 路由json使用JsonWorker、css/scss/less使用CssWorker、html/handlebars/razor使用HtmlWorker、typescript/javascript使用TsWorker其余语言回退到EditorWorkerL26-L38设置 TypeScript 编译器默认选项strict: true、moduleResolution: NodeJs、module: ESNextL59-L65依次执行所有用户setups/monaco.ts并把各自返回的editorOptions合并进全局配置L98-L102注册 Shiki 高亮后文详述。此外还有一处细节编辑器获得焦点时会调用lockShortcuts()锁定 Slidev 的全局快捷键失焦时释放避免在 Monaco 中输入时误触翻页等快捷键L104-L114。TypeScript 类型自动加载依赖类型在幻灯片中使用{monaco}标记的代码块时Slidev 会自动为代码中引用的依赖安装类型。例如ts {monaco} import { ref } from vue import { useMouse } from vueuse/core const counter ref(0) 前提是确保vue和vueuse/core已作为依赖 / devDependencies 安装在本地Slidev 会自动完成编辑器类型的工作。当项目以 SPA 形式部署时这些类型也会被打入产物用于静态托管。自动扫描的实现原理这一能力由解析层与虚拟模块协作完成解析阶段packages/parser/src/core.ts 用正则/\{monaco.*\}/检测页面是否包含 Monaco 代码块并在命中时调用scanMonacoReferencedMods(code)扫描其中 import 的模块名L163构建阶段虚拟模块/slidev/monaco-types由 monaco-types.ts 生成。它会扫描用户项目snippets/目录下所有*.ts、*.mts、*.cts文件通过addFile()注入为额外 lib把扫描到的依赖与 frontmatter 中monacoTypesAdditionalPackages合并、去重通过mapModuleNameToModule做归一化node:前缀与 Node 内置模块统一映射为nodelodash/identity这类子路径取主包名scope/pkg保留两段过滤掉monacoTypesIgnorePackages中列出的包最后为每个包生成对/slidev-monaco-types/resolve?pkg...的动态 import由服务端在请求时解析本地node_modules中的类型并下发。也就是说类型来源默认是“本地 node_modules 扫描”无需任何额外配置。补充额外类型monacoTypesAdditionalPackagesSlidev 会扫描幻灯片中所有 Monaco 代码块并自动导入被引用库的类型。若它遗漏了某些包例如类型是通过间接方式引用可以显式声明额外需要导入类型的包--- monacoTypesAdditionalPackages: - lodash-es - foo ---与类型加载相关的前置项还包括monacoTypesIgnorePackages忽略某些包避免误注入与monacoRunAdditionalDeps为可运行代码补充本地依赖模块二者在 frontmatter.ts 中均有类型定义VS Code 扩展的 JSON Schema headmatter.json 也对其提供了完整的补全与说明。自动类型获取monacoTypesSource可以切换到从 CDN 加载类型的模式对应配置--- monacoTypesSource: cdn ---该配置取值为local | cdn | none默认local见 config.ts 中的默认值与 headmatter.json 的枚举定义。cdn模式由typescript/ata驱动且完全运行在客户端在 packages/client/setup/monaco.ts 中仅当configs.monacoTypesSource cdn时才调用setupTypeAcquisition其receivedFile回调把拉取到的声明文件通过defaults.addExtraLib注入 Monaco 的 TypeScript 默认实例并用monaco.editor.createModel建立对应模型progress回调还会以[Typescript ATA] downloaded / total的形式在控制台输出下载进度。本地模式下则直接由monaco-types.ts虚拟模块按包解析注入前述流程。主题配置复用 Shiki 主题自 v0.48.0 起Monaco 会复用你在 Shiki 配置文件 中配置的 Shiki 主题由shikijs/monaco驱动无需单独为编辑器指定主题从而保证 Monaco 编辑区与其余代码块高亮风格一致。源码印证见 packages/client/setup/monaco.ts初始化时会先通过getEagerHighlighter()获取 Shiki 高亮器并调用shikiToMonaco(highlighter, monaco)完成主题映射随后根据themeOption的类型决定行为——若主题是一个固定字符串直接monaco.editor.setTheme(themeOption)若是 light/dark 双主题对象则用watchEffect监听isDark状态变化在深浅色间自动切换缺省回退到vitesse-dark/vitesse-light。因此你只需要维护 docs/custom/config-highlighter.md 中的 Shiki 主题配置Monaco 编辑器的配色会自动跟随。配置编辑器行为editorOptions自 v0.43.0 可用如需自定义 Monaco 编辑器行为可以传入一个符合 MonacoIEditorOptions定义的editorOptions对象作用范围有两种1. 单个代码块级别直接在 Markdown 代码块的内联选项中声明ts {monaco} { editorOptions: { wordWrap:on} } console.log(HelloWorld) 2. 全局级别希望所有 Monaco 实例都应用这些选项时在defineMonacoSetup函数中返回它们import { defineMonacoSetup } from slidev/types export default defineMonacoSetup(() { return { editorOptions: { wordWrap: on } } })从源码看全局editorOptions的合并在客户端初始化时进行setup 循环中执行Object.assign(editorOptions, result?.editorOptions)monaco.ts最终随单例 setup 的返回值一同导出供Monaco.vue等内置组件在创建编辑器实例时使用。启用与禁用自 v0.48.0 起Monaco 编辑器默认启用且仅在幻灯片中实际使用时才会被打包按需引入未使用{monaco}代码块时不会增加产物体积。若想禁用它可在幻灯片 frontmatter 中把monaco设为false--- monaco: false # can also be dev or build to conditionally enable it ---monaco的完整类型是boolean | dev | buildfrontmatter.ts默认为trueconfig.tstrue开发与服务端渲染/构建均启用false完全禁用dev仅在开发模式启用build仅在构建产物中启用。严格模式monacoRunUseStrict自 v0.52.0 可用默认情况下Monaco 可运行代码以严格模式use strict执行。如果你的代码依赖非严格模式行为例如隐式this或全局变量绑定差异可以关闭--- monacoRunUseStrict: false ---该选项的默认值为trueconfig.ts 的解析默认值以及 headmatter.json 中的 Schema 默认值一致。配合前文提到的编辑器端编译器选项strict: true整个“编辑提示 实际运行”链路在默认配置下都保持严格的 TypeScript 语义。配置代码运行器 Code Runners关于 Monaco Runner 如何执行代码、以及如何为自定义语言添加运行支持见 配置 Code Runners。可运行的本地代码块还可配合monacoRunAdditionalDeps选项注入额外的本地模块依赖frontmatter.ts。Frontmatter 配置项速查汇总当前仓库中 Monaco 相关的全部 frontmatter 配置项依据 frontmatter.ts 的类型定义与 config.ts 的默认值配置项类型默认值说明monacoboolean \| dev \| buildtrue是否启用 Monaco可按 dev/build 条件启用未使用时代码不会被打包monacoTypesSourcelocal \| cdn \| nonelocal类型来源本地 node_modules 或经typescript/ata从 CDN 获取monacoTypesAdditionalPackagesstring[][]自动扫描遗漏时显式补充需要导入类型的包monacoTypesIgnorePackagesstring[][]类型加载时需要忽略的包monacoRunAdditionalDepsstring[][]为可运行代码块补充的本地依赖模块monacoRunUseStrictbooleantrue可运行代码是否以严格模式执行小结与延伸阅读全局定制入口setup/monaco.tsdefineMonacoSetuppackages/types/src/setups.ts 定义了各 setup 的类型签名客户端初始化与类型注入逻辑packages/client/setup/monaco.ts类型解析虚拟模块packages/slidev/node/virtual/monaco-types.ts解析默认值packages/parser/src/config.ts实际使用示例demo/composable-vue/setup/monaco.ts主题复用docs/custom/config-highlighter.md代码运行器docs/custom/config-code-runners.md。掌握以上内容后你可以按需组合用setup/monaco.ts做全局行为定制与额外类型声明用{monaco}内联editorOptions做单块微调用monacoTypesSource/monacoTypesAdditionalPackages精确控制类型来源用monaco与monacoRunUseStrict管理启用范围与运行语义从而得到一套与幻灯片其余代码块视觉统一、提示完整的 Monaco 编辑环境。【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考