Monaco YAML

Monaco 编辑器的 YAML 语言插件。在编辑 YAML 文件时提供以下功能：

代码补全，基于 JSON schemas 或通过查看同文件中的类似对象
悬停提示，基于 JSON schemas
验证：语法错误和 schema 验证
使用 Prettier 进行格式化
文档符号
自动加载远程 schema 文件（通过启用 DiagnosticsOptions.enableSchemaRequest）
JSON 引用的链接
YAML 锚点的链接和悬停效果
代码折叠

也可以通过配置提供 schemas。查看这里了解插件提供的配置 YAML 语言支持的 API。

安装

npm install monaco-yaml

使用

在实现 monaco-yaml 甚至 Monaco 编辑器之前，建议了解 Monaco 编辑器的基本概念。

要配置 monaco-yaml，调用 configureMonacoYaml。

import * as monaco from 'monaco-editor'
import { configureMonacoYaml } from 'monaco-yaml'

configureMonacoYaml(monaco, {
  enableSchemaRequest: true,
  schemas: [
    {
      // 如果打开的 YAML 文件匹配此 glob
      fileMatch: ['**/.prettierrc.*'],
      // 则会从互联网下载并使用此 schema
      uri: 'https://json.schemastore.org/prettierrc.json'
    },
    {
      // 如果打开的 YAML 文件匹配此 glob
      fileMatch: ['**/person.yaml'],
      // 将应用以下 schema
      schema: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
            description: '人的显示名称'
          },
          age: {
            type: 'integer',
            description: '这个人多少岁？'
          },
          occupation: {
            enum: ['送货员', '软件工程师', '宇航员']
          }
        }
      },
      // 并将 URI 链接为源
      uri: 'https://github.com/remcohaszing/monaco-yaml#usage'
    }
  ]
})

const prettierc = monaco.editor.createModel(
  'singleQuote: true\nproseWrap: always\nsemi: yes\n',
  undefined,
  monaco.Uri.parse('file:///.prettierrc.yaml')
)

monaco.editor.createModel(
  'name: John Doe\nage: 42\noccupation: 海盗\n',
  undefined,
  monaco.Uri.parse('file:///person.yaml')
)

monaco.editor.create(document.getElementById('editor'), {
  automaticLayout: true,
  model: prettierc
})

还要确保注册 web worker。使用 Webpack 5 时，看起来像下面的代码。其他打包工具可能使用不同的语法，但思路是一样的。可以省略未使用的语言。

window.MonacoEnvironment = {
  getWorker(moduleId, label) {
    switch (label) {
      case 'editorWorkerService':
        return new Worker(new URL('monaco-editor/esm/vs/editor/editor.worker', import.meta.url))
      case 'css':
      case 'less':
      case 'scss':
        return new Worker(new URL('monaco-editor/esm/vs/language/css/css.worker', import.meta.url))
      case 'handlebars':
      case 'html':
      case 'razor':
        return new Worker(
          new URL('monaco-editor/esm/vs/language/html/html.worker', import.meta.url)
        )
      case 'json':
        return new Worker(
          new URL('monaco-editor/esm/vs/language/json/json.worker', import.meta.url)
        )
      case 'javascript':
      case 'typescript':
        return new Worker(
          new URL('monaco-editor/esm/vs/language/typescript/ts.worker', import.meta.url)
        )
      case 'yaml':
        return new Worker(new URL('monaco-yaml/yaml.worker', import.meta.url))
      default:
        throw new Error(`未知标签 ${label}`)
    }
  }
}

示例

演示可在 monaco-yaml.js.org 上获得。

一些使用示例可以在 examples 目录中找到。

API

monaco-yaml 有以下导出：

`configureMonacoYaml(monaco, options?)`

配置 monaco-yaml。

注意：同一时间只能有一个配置好的 monaco-yaml 实例。

参数

monaco (object): Monaco 编辑器模块。通常通过导入 monaco-editor 获得。第三方集成通常将其公开为全局 monaco 变量。
options (object): 用于配置 monaco-yaml 的选项。

选项

completion（boolean）：如果设置，启用基于模式的自动完成。（默认：true）
customTags（string[]）：自定义标签列表。（默认：[]）
enableSchemaRequest（boolean）：如果设置，模式服务将按需加载模式内容。（默认：false）
format（boolean）：来自捆绑包的Prettier。（默认：true）
hover（boolean）：如果设置，启用基于JSON模式的悬停类型。（默认：true）
isKubernetes（boolean）：如果为true，使用不同的diff算法生成错误消息。（默认：false）
schemas（object[]）：已知模式和/或模式与文件名关联的列表。（默认：[]）
validate（boolean）：基于验证。（默认：true）
yamlVersion（'1.1' | '1.2'）：用于解析的YAML版本。（默认：1.2）

返回值

可用于处置或更新monaco-yaml的对象。

常见问题

这是否适用于Monaco UMD捆绑包？

是的，从版本5.0.0开始支持。

这是否适用于来自CDN的Monaco编辑器？

是的，从版本5.0.0开始支持。

这是否适用于`@monaco-editor/loader`或`@monaco-editor/react`？

是的，从版本5.0.0开始支持。

Web Worker是否必需？

是的。Web Worker提供了monaco-yaml的核心功能。

它是否可以在没有打包工具的情况下工作？

不可以。monaco-yaml使用来自node_modules的依赖项，以便可以去重并减少您的捆绑包大小。这带来的代价是无法在没有打包工具的情况下使用它。

我如何将`monaco-yaml`与框架集成？（Angular、React、Vue等）

monaco-yaml仅使用Monaco编辑器。它不与任何框架绑定，只需要一个DOM节点来附加Monaco编辑器即可。请参阅Monaco编辑器示例以了解如何在项目中集成Monaco编辑器，然后按上述说明配置monaco-yaml。

`monaco-yaml`是否适用于`create-react-app`？

是的，但您需要执行eject操作。详情请参见#92（评论）。

为什么它不适用于Vite？

一些用户在使用Vite时遇到了以下错误：

Uncaught (in promise) Error: Unexpected usage
  at EditorSimpleWorker.loadForeignModule (editorSimpleWorker.js)
  at webWorker.js

作为解决方法，在您自己的项目中创建一个名为yaml.worker.js的文件，内容如下：

import 'monaco-yaml/yaml.worker.js'

然后在您的Monaco环境getWorker函数中，引用此文件而不是直接引用monaco-yaml/yaml.worker.js：

import YamlWorker from './yaml.worker.js?worker'

window.MonacoEnvironment = {
  getWorker(moduleId, label) {
    switch (label) {
      // 处理其他情况
      case 'yaml':
        return new YamlWorker()
      default:
        throw new Error(`Unknown label ${label}`)
    }
  }
}

为什么`monaco-yaml`不起作用？官方Monaco语言扩展可以正常工作。

这很可能是因为monaco-yaml使用的是与您不同的monaco-editor包实例。无论是否使用monaco-editor，您都应该避免这种情况，因为这意味着您的捆绑包比需要的大得多。这可能是由以下问题之一引起的：

代码拆分配置错误

要解决这个问题，请尝试使用例如webpack-bundle-analyzer检查您的捆绑包。如果monaco-editor出现两次，这就是问题所在。解决方法取决于您的具体项目。
您正在使用一个为您导入monaco-editor的包，但它使用的是不同版本。

您可以使用npm ls monaco-editor或yarn why monaco-editor找出为什么安装了monaco-editor。它应该只存在一次，但如果它被去重了也是可以的。

您可以尝试删除node_modules文件夹和package-lock.json或yarn.lock，然后分别运行npm install或yarn install来解决这个问题。

使用Monaco webpack加载器插件

如果您正在使用monaco webpack插件，那么您可以扩展插件的配置，而不是使用上述代码。在您的webpack.config.js文件中添加以下内容：

import { MonacoWebpackPlugin } from 'monaco-editor-webpack-plugin'

export default {
  // ...webpack配置的其余部分...
  plugins: [
    new MonacoWebpackPlugin({
      languages: ['yaml'],
      customLanguages: [
        {
          label: 'yaml',
          entry: 'monaco-yaml',
          worker: {
            id: 'monaco-yaml/yamlWorker',
            entry: 'monaco-yaml/yaml.worker'
          }
        }
      ]
    })
  ]
}

您也可以参考示例中的完整项目。

为什么即使我提供了一个对象形式的模式，它仍然试图下载我的模式？

您可能提供了一个如下配置的模式：

{
  uri: "http://example.com",
  fileMatch: ["file_name.yml"],
  schema: {
    $schema: "http://json-schema.org/draft-07/schema#",
    $id: "http://example.com",
    title: "placeholder title",
    description: "placeholder description",
    type: "object",
    properties: {
      name: {
        description: "name property description",
        type: "string",
      },
    },
    required: ["name"],
  },
}

然后您可能会惊讶地看到以下错误：

Unable to load schema from '<http://example.com>': Failed to fetch.

这是因为插件不仅使用模式URI作为下载模式的URL，还用它来确定模式名称。要修复这个问题，请将uri参数更改为http://example.com/schema-name.json。

贡献

请查看我们的贡献指南

致谢

最初，@kpdecker从@microsoft的monaco-json分叉了这个仓库，并重写它以使用yaml-language-server。后来，仓库的维护由@pengx17接管。最终，仓库被转移到@remcohaszing的账户下，他目前正在维护这个仓库，并得到了@fleon和@yazaabed的帮助。

主要的处理工作是在yaml-language-server中完成的，它最著名的是作为vscode-yaml的核心。这个仓库提供了一个薄层，将yaml-language-server提供的功能添加到monaco-editor中。