使用 Parcel 构建自定义 CodeMirror 6 GraphQL 编辑器：基于 cm6-graphql 的完整实战指南

使用 Parcel 构建自定义 CodeMirror 6 GraphQL 编辑器基于 cm6-graphql 的完整实战指南【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql导读本文围绕examples/cm6-graphql-parcel示例展开介绍如何用 Parcel 打包器转译transpile一套自定义的 ES6 CodeMirror 6 GraphQL 编辑器实现——即直接以cm6-graphql语言包为内核、自行组装补全、校验、跳转与主题等扩展的轻量编辑器。读完本文你将掌握示例的启动与构建命令、编辑器入口的完整装配方式、cm6-graphql可配置选项及其底层实现原理并能在此基础上快速搭建属于自己的 GraphQL 代码编辑页面。示例定位为什么需要自定义 CM6 实现examples/cm6-graphql-parcel是 GraphiQL 仓库中与examples/cm6-graphql-legacy-parcel并列的 Parcel 版示例。它的核心目的正如其 README 所述演示如何用 Parcel 打包器转译自定义的 ES6 CodeMirror 6 GraphQL 实现README。与直接使用现成 GraphiQL 组件不同这个示例把编辑器拆开给你看它不再依赖完整的 GraphiQL React 界面而是通过cm6-graphql包提供的graphql()扩展把 CodeMirror 6 的语法高亮、自动补全、lint 校验、符号跳转等能力组装成一个可独立运行的编辑器实例。从 examples/cm6-graphql-parcel/src/index.ts 可以看到整个入口只有创建 EditorState 挂载 EditorView两步非常契合希望深度定制编辑器行为的场景如内嵌到自定义表单、IDE 插件或私有工具链。环境准备与快速开始安装依赖示例采用 Yarn 作为包管理器在examples/cm6-graphql-parcel目录下执行yarn关键依赖见 package.json运行时依赖codemirror/autocomplete、codemirror/commands、codemirror/language、codemirror/state、codemirror/theme-one-dark、codemirror/view、cm6-graphql^0.0、graphql^16。开发依赖parcel^2、worker-loader^2、typescript^4。cm6-graphql对 CodeMirror 6 各模块及graphql的版本要求由其 peerDependencies 声明packages/cm6-graphql/package.json支持graphql^15.5.0 || ^16.0.0 || ^17.0.0并需要codemirror/autocomplete、codemirror/language、codemirror/lint、codemirror/state、codemirror/view、lezer/highlight的 6.x/1.x 版本族。启动开发模式yarn start该命令实际执行parcel src/index.html -p 8080package.json即以src/index.html为入口启动 Parcel 开发服务器并监听 8080 端口。由于开发模式的browserslist配置为last 1 chrome version、last 1 firefox version、last 1 safari versionParcel 不会做重型转译热更新HMR反馈更迅速。构建生产文件yarn build对应脚本为parcel build src/index.html --public-url /生成可直接部署的静态产物。生产模式下的browserslist为0.2%、not dead、not op_mini allParcel 会按目标浏览器做代码转译与压缩。构建并发布 Demo 到 GraphiQL 包目录yarn build-demo该命令在yarn build之后把产物拷贝到../../packages/graphiql/cm6/用于把该自定义 CM6 编辑器作为 GraphiQL 的 demo 页面嵌入主包目录。它是示例团队内部工作流的一部分普通用户可忽略。编辑器入口源码拆解HTML 骨架与挂载点src/index.html 定义了#editor挂载节点并以typemodule的方式引入./index.tsParcel 负责把 TypeScript 编译为浏览器可执行代码。页面样式将body与#root铺满 100vh为编辑器预留全屏空间。核心入口组装 EditorState 与 EditorViewsrc/index.ts 完整展示了装配过程import { EditorState } from codemirror/state; import { EditorView, lineNumbers } from codemirror/view; import { history } from codemirror/commands; import { autocompletion, closeBrackets } from codemirror/autocomplete; import { bracketMatching, syntaxHighlighting } from codemirror/language; import { oneDarkHighlightStyle, oneDark } from codemirror/theme-one-dark; import { graphql } from cm6-graphql; import query from ./sample-query; import { TestSchema } from ./testSchema; const state EditorState.create({ doc: query, extensions: [ bracketMatching(), closeBrackets(), history(), autocompletion(), lineNumbers(), oneDark, syntaxHighlighting(oneDarkHighlightStyle), graphql(TestSchema, { onShowInDocs(field, type, parentType) { alert( Showing in docs.: Field: ${field}, Type: ${type}, ParentType: ${parentType}, ); }, onFillAllFields(view, schema, _query, cursor, token) { alert(Filling all fields. Token: ${token}); }, }), ], }); new EditorView({ state, parent: document.querySelector(#editor)!, });逐层解读通用编辑能力bracketMatching()括号匹配、closeBrackets()自动闭合括号、history()撤销/重做、autocompletion()开启补全 UI、lineNumbers()行号。主题oneDark与oneDarkHighlightStyle来自codemirror/theme-one-dark为编辑器套用 One Dark 暗色主题。GraphQL 核心graphql(TestSchema, opts)是cm6-graphql的对外入口传入一个GraphQLSchema与可选的扩展选项。它返回一个Extension[]数组packages/cm6-graphql/src/graphql.ts内部依次装配graphqlLanguageSupport()基于 Lezer 的 GraphQL 语法解析与语法高亮completionschema 驱动的自动补全lint基于 schema 的诊断校验jump符号跳转stateExtensions(schema, opts)把 schema 与选项注入编辑器状态。HMR 适配文件末尾的if (module.hot) { module.hot.accept(); }让编辑器在 Parcel 开发模式下支持热替换修改源码无需整页刷新。由内到外的依赖原理schema 如何流动cm6-graphql通过 CodeMirror 6 的StateFieldStateEffect机制管理 schema 与选项packages/cm6-graphql/src/state.tsschemaStateField与optionsStateField分别保存 schema 与GqlExtensionsOptions对外提供updateSchema(view, schema)与updateOpts(view, opts)两个工具函数允许在编辑器运行期通过view.dispatch动态替换 schema 或选项——这意味着你完全可以在启动时不传 schema之后异步加载远端 introspection 结果再注入stateExtensions在初始化时执行{ ...defaultOpts, ...opts }合并默认开启showErrorOnInvalidSchema: true。补全模块packages/cm6-graphql/src/completions.ts在每次输入时从状态中读取 schema 与选项把光标位置换算为行列坐标后调用graphql-language-service的getAutocompleteSuggestions获取候选词再映射为 CodeMirror 的Completion对象若配置了onCompletionInfoRender还会用该回调自定义补全项的 info 弹层否则展示documentation/deprecationReason文本。cm6-graphql 可配置选项详解graphql(schema, opts)的第二个参数类型为GqlExtensionsOptionspackages/cm6-graphql/src/interfaces.ts完整字段如下选项类型默认值说明showErrorOnInvalidSchemabooleantrue当传入的 schema 无效时是否显示错误提示onShowInDocs(field?, type?, parentType?) void无用户触发在文档中查看时回调携带字段名、类型名与父类型名onFillAllFields(view, schema, query, cursor, token) void无用户触发填充所有字段时回调携带编辑器视图、schema、当前查询、光标位置与上下文 tokenonCompletionInfoRender(gqlCompletionItem, ctx, item) Node \| PromiseNode \| null \| null无自定义补全项的详情渲染返回 DOM 节点autocompleteOptionsAutocompleteSuggestionOptions无透传给graphql-language-service的补全建议参数来自该服务的类型定义示例中把onShowInDocs与onFillAllFields实现为alert弹窗方便直观观察触发时机实际项目中通常替换为跳转文档面板或自动生成查询片段等业务逻辑。示例数据资产sample-query 与 TestSchema覆盖多种语法的示例查询src/sample-query.ts 导出一个默认查询字符串刻意覆盖了 GraphQL 语言的多类特性便于验证补全与高亮带默认值$site: TestEnum RED与自定义类型$foo: TestInput的变量定义字段别名testAlias:、指令include/skip、内联片段与命名片段...frag标量、枚举、列表、对象与浮点数含科学计数法等多种参数形态同一文件中包含 query、mutation、subscription 三种操作。用 graphql-js 手工构建的测试 Schemasrc/testSchema.ts 不依赖 SDL 文本而是直接用graphql包的构造器定义 schema涵盖标量全集GraphQLString、GraphQLInt、GraphQLFloat、GraphQLBoolean、GraphQLID复合类型GraphQLEnumTypeTestEnumRED/GREEN/BLUE、GraphQLInputObjectTypeTestInput含自引用object: { type: TestInputObject }与各类 List 字段、GraphQLInterfaceType、GraphQLUnionType对象类型Testquery 根类型包含递归字段test、带deprecationReason的deprecatedTest、union 字段union以及带 14 个参数的hasArgs另有MutationType与SubscriptionType作为 mutation/subscription 根自定义指令onArg仅限ARGUMENT_DEFINITION与onAllDefs覆盖 schema 上全部指令位置与内置的include、skip、deprecated一并注册到TestSchema。这套 schema 是为语言服务特性量身定做的测试数据与codemirror-graphql包中的testSchema.tspackages/codemirror-graphql/src/tests/testSchema.ts同源可用来验证递归类型、列表、枚举默认值等补全边界。验证与扩展思路运行yarn start后访问http://localhost:8080即可在暗色主题的编辑器中体验输入时触发 schema 驱动的自动补全光标悬停或按快捷键触发跳转输入无效字段时出现 lint 波浪线。想验证动态 schema 能力可在updateSchema(view, newSchema)处接入远端 introspection 结果想深度自定义则替换onCompletionInfoRender渲染富文本补全详情。示例完整代码位于 examples/cm6-graphql-parcel/srccm6-graphql包的其余扩展如 commands.ts、jump.ts、lint.ts均从 packages/cm6-graphql/src/index.ts 导出可继续深入研读。【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考