★ FEATURED ARTICLE 1. 为什么 Position 是 Monaco Editor 的“坐标原点”——从光标跳转卡顿说起我第一次在某跨平台代码编辑器项目里遇到光标定位不准的问题是在实现一个自定义语法高亮插件时。用户点击错误提示行编辑器本该把光标精准跳转到出错的 token 起始位置结果却总偏移 1~2 个字符。排查了三天最后发现不是正则匹配逻辑错了而是我把editor.setPosition({ lineNumber: 5, column: 10 })里的column当成了“字节偏移”而 Monaco 的 Position 类型中column实际上是“可视字符列号”且从 1 开始计数——这个细节在官方文档里藏在 API 参考页的第三级折叠菜单下连 TypeScript 类型定义都只写了column: number没注释单位。这就是 Position 类型的真实处境它看起来最简单却是整个编辑器坐标系统的基石所有光标移动、选区计算、Marker 定位、文本插入替换都绕不开它。你用editor.executeEdits()插入一段代码底层必须把字符串长度换算成 Position 偏移你调用editor.deltaDecorations()添加一个红色波浪线传进去的 range 必须由两个 Position 构成甚至你按 CtrlClick 跳转到定义编辑器内部也是先解析出目标符号的 Position再驱动视图滚动和光标定位。它不是“一个类型”而是一套隐式约定的坐标协议。标题里把 Position 放在最前面不是凑字数。因为如果你连lineNumber和column的语义都没吃透后面所有 Marker 设置、位置插入操作都会像蒙眼走钢丝——表面能跑通一到复杂场景比如含 emoji、全角字符、制表符混合的文件就崩。我见过太多人直接抄示例代码new monaco.Position(1, 1)结果在处理中文注释时发现 Marker 总是画歪最后才发现column在含中文的行里需要按 Unicode 字符宽度重新计算而不是简单用str.length。所以这一篇我们不讲 API 列表就死磕 Position它怎么定义、为什么这样定义、哪些坑必须填平以及——它如何成为你控制编辑器行为的真正支点。2. Position 类型深度解剖不只是 {lineNumber, column} 的简单组合2.1 官方定义与不可忽视的“1-based”契约Monaco 的 Position 类型在 TypeScript 中定义为export interface IPosition { readonly lineNumber: number; readonly column: number; }表面看就是两个只读数字。但关键在文档里那句轻描淡写的说明“lineNumber and column are both 1-based.” 这句话的分量远超你的想象。lineNumber 1 表示第一行不是第 0 行。这和大多数编程语言的数组索引习惯相反。当你用editor.getModel().getLineContent(1)获取第一行内容时传入的是 1但如果你用lines[0]访问模型内部行数组索引却是 0。Position 永远站在“用户视角”而非“内存视角”。column 1 表示行首第一个可视字符前的位置即光标在行首左侧的插入点。这里“可视字符”是核心一个 emoji如 在 Monaco 中占 2 列宽因 UTF-16 编码占两个 code unit但column计数时仍算作 1 个字符位置一个制表符\t默认展开为 4 个空格column值会跳变 4从 col 5 到 col 9而非 1。提示column的值永远等于光标左侧的“显示列数”不是字节偏移不是 UTF-16 code unit 数更不是 JavaScript 字符串的str.length。它是编辑器渲染层对“位置”的最终解释。2.2 为什么不能直接用字符串索引——从 “ab” 的陷阱说起假设你有一行文本ab想在 emoji 后插入一个逗号。直觉做法可能是// ❌ 错误示范用 JS 字符串索引 const line ab; const pos new monaco.Position(1, line.indexOf() 2); // 期望得到 emoji 后的位置 editor.setPosition(pos);这段代码在大多数情况下会失败。原因在于JavaScript 字符串ab的length是 4a,的 high surrogate,的 low surrogate,b但 Monaco 的column计数中是一个整体占 1 列。line.indexOf()返回的是 1surrogate pair 的起始索引2后得到 3对应的是b的位置但 Monaco 会认为这是第 3 列而实际b在视觉上位于第 4 列a1,2,b3不对。实测验证在 Monaco 编辑器中输入ab将光标放在b前调用editor.getPosition()返回的是{lineNumber: 1, column: 3}。因为a→ column 1→ column 2单个字符1 列宽b→ column 3所以正确做法是永远通过编辑器模型获取位置而非手动计算字符串。// ✅ 正确做法用模型 API 精确获取 const model editor.getModel(); const lineContent model.getLineContent(1); // ab // 找到 emoji 在行中的字符索引按 Unicode 字符非 UTF-16 const charIndex [...lineContent].findIndex(char char ); // 1 // 转换为 Monaco columncharIndex 1因 column 从 1 开始 const columnAfterEmoji charIndex 2; // emoji 本身占 1 列后一位是 2 const pos new monaco.Position(1, columnAfterEmoji); // {1, 3}2.3 Position 与 Range 的共生关系没有 Range 的 Position 是残缺的Position 从不单独存在。它总是作为 Range 的一部分出现。Range 定义为export interface IRange { readonly startLineNumber: number; readonly startColumn: number; readonly endLineNumber: number; readonly endColumn: number; }注意startColumn和endColumn都是column遵循完全相同的 1-based 规则。而 Range 的语义是包含 start 位置不包含 end 位置。这和 Python 的切片str[start:end]一致。举个硬核例子你想删除第 2 行第 5 列到第 2 行第 10 列之间的文本含第 5 列不含第 10 列共 5 个字符。你写const range { startLineNumber: 2, startColumn: 5, endLineNumber: 2, endColumn: 10 }; editor.executeEdits([{ range, text: }]);但如果第 2 行是Hello WorldstartColumn:5对应oH1, e2, l3, l4, o5endColumn:10对应rW6, o7, r8, l9, d10 → 所以 end 是 d 后的位置即 column 11。等等这里就暴露了常见误区Hello World共 11 个字符column从 1 到 12行尾是 12。所以endColumn:10实际指向lW6, o7, r8, l9, d10 → d 是第 10 列endColumn10 就是 d 的位置不包含 d。注意endColumn是“结束位置”不是“结束字符的列号”。range {start:1, end:5}删除的是 column 1,2,3,4 的字符共 4 个。因此Position 的真正力量在于它和 Range 的绑定。设置 Marker、插入文本、高亮选区本质都是在构造一个或多个 Range而 Range 的四个端点全部由 Position 构成。理解 Position就是掌握编辑器空间坐标的密钥。3. Marker 设置实战从“画一条红线”到“动态诊断提示”3.1 Marker 是什么不是装饰是语义化诊断信标很多新手把 Marker 理解为“给代码加红波浪线”这太浅了。Monaco 的 Marker 是一个语义化诊断对象它携带的不只是样式信息更是编辑器对代码健康度的判断结论。当你调用model.updateMarkers()你不是在“画线”而是在向编辑器的诊断系统提交一份“病情报告”。一个 Marker 对象长这样interface IMarkerData { readonly severity: MarkerSeverity; // 1error, 2warning, 3info, 4hint readonly message: string; // 错误描述会显示在悬停和问题面板 readonly source?: string; // 来源如 eslint, tslint readonly startLineNumber: number; readonly startColumn: number; readonly endLineNumber: number; readonly endColumn: number; readonly code?: string | { value: string; target: Uri }; // 错误码或链接 readonly relatedInformation?: IRelatedInformation[]; // 相关位置如“此处定义于...” }看到没severity决定图标和颜色message决定悬停内容source决定它归类到哪个诊断提供者下。这才是 Marker 的全貌。你设置一个severity: 1的 Marker编辑器不仅画红线还会在左侧行号旁显示红色 × 图标在状态栏显示 “1 problem”在“问题”面板中列出该条目如果用户按 CtrlShiftM焦点会自动跳转到这里。3.2 三步法设置 Marker创建、校验、提交第一步构造合法的 MarkerData核心是确保startLineNumber/endLineNumber和startColumn/endColumn组成的 Range 是有效的。无效 Range 会导致 Marker 被静默丢弃。// ✅ 安全构造函数自动校验并修正边界 function createSafeMarker( model: monaco.editor.ITextModel, lineNumber: number, startColumn: number, endColumn: number, message: string, severity: monaco.MarkerSeverity monaco.MarkerSeverity.Error ): monaco.editor.IMarkerData { // 1. 校验行号不能超过总行数不能小于 1 const maxLine model.getLineCount(); const safeLine Math.min(Math.max(lineNumber, 1), maxLine); // 2. 校验列号不能超过该行长度1行尾是 length1不能小于 1 const lineContent model.getLineContent(safeLine); const maxColumn lineContent.length 1; const safeStartCol Math.min(Math.max(startColumn, 1), maxColumn); const safeEndCol Math.min(Math.max(endColumn, safeStartCol), maxColumn); return { severity, message, startLineNumber: safeLine, startColumn: safeStartCol, endLineNumber: safeLine, endColumn: safeEndCol, source: my-linter }; }第二步使用 updateMarkers 提交不是 setMarkers这是另一个高频坑。model.setMarkers()是旧 API已被废弃。正确方法是model.deltaDecorations()用于视觉装饰model.updateMarkers()用于语义 Marker。// ✅ 正确提交方式 const model editor.getModel(); const markerId my-custom-marker; // 用于后续更新/删除 const markers [ createSafeMarker(model, 3, 5, 12, 变量未声明, monaco.MarkerSeverity.Error) ]; // updateMarkers 的第一个参数是 owner建议用唯一字符串标识你的插件 model.updateMarkers(my-linter-owner, [markers[0]]);updateMarkers是“增量更新”你传入的数组会完全替换该owner下的所有 Marker。所以如果你想添加多个必须把它们全塞进一个数组里一起提交。第三步动态更新与清理Marker 不是一次性的。当用户修改代码旧 Marker 可能失效你需要重新计算并更新。// 监听编辑事件实时更新 editor.onDidChangeModelContent(() { const model editor.getModel(); // 重新运行你的 lint 逻辑生成新 markers const newMarkers runMyLinter(model); model.updateMarkers(my-linter-owner, newMarkers); });实操心得不要在每次按键后都调用updateMarkers。Monaco 有防抖机制但频繁调用仍影响性能。我的做法是用setTimeout延迟 300ms如果期间有新编辑则清除旧定时器只执行最后一次。这样既保证响应及时又避免过载。3.3 高级技巧让 Marker 支持“快速修复”真正的专业级 Marker应该支持 Ctrl. 弹出修复建议。这需要你在 Marker 中加入code和relatedInformation并注册一个 CodeActionProvider。// 在 Marker 中添加 code const marker: monaco.editor.IMarkerData { // ...其他字段 code: undefined-var, relatedInformation: [{ resource: model.uri, message: 该变量在此处被使用但未声明, startLineNumber: 3, startColumn: 5, endLineNumber: 3, endColumn: 12 }] }; // 注册 CodeActionProvider需在插件激活时 monaco.languages.registerCodeActionProvider(javascript, { provideCodeActions: (model, range, context, token) { if (context.markers.some(m m.code undefined-var)) { return { actions: [{ title: 声明变量, kind: quickfix, diagnostics: context.markers, edit: { edits: [{ resource: model.uri, edit: { range: new monaco.Range(3, 1, 3, 1), // 在行首插入 text: let } }] } }] }; } } });这已经超出 Position 范畴但它证明了一点一个扎实的 Position 基础是你构建高级编辑器功能的起点。4. 在指定位置插入或替换文本executeEdits 的精确制导艺术4.1 executeEdits 是编辑器的“外科手术刀”editor.executeEdits()是 Monaco 中最常用也最容易误用的 API。它的签名是executeEdits(source: string, edits: IIdentifiedSingleEditOperation[]): void;source是操作来源描述如user,my-extension仅用于调试日志。核心是edits数组每个元素是interface IIdentifiedSingleEditOperation { readonly range: IRange; readonly text: string; readonly forceMoveMarkers?: boolean; }关键在range它决定了“在哪里动刀”text决定了“动什么”。forceMoveMarkers是个隐藏开关——设为true时编辑器会强制将所有 Marker 的位置按此次编辑进行偏移比如你在第 1 行插入 5 个字符所有第 1 行 column 1 的 Marker 都会 5。默认falseMarker 位置不变可能导致 Marker 指向错误位置。4.2 插入文本两种模式的精确选择模式一在光标位置插入最常用用户按快捷键插入一段模板代码光标在哪代码就插在哪。// 获取当前光标位置 const selection editor.getSelection(); // 返回 ISelection包含 position const pos selection.getStartPosition(); // IPosition // 构造插入范围从 pos 开始到 pos 结束即一个零长度范围 const range new monaco.Range( pos.lineNumber, pos.column, pos.lineNumber, pos.column ); // 插入文本 editor.executeEdits(my-snippet, [{ range, text: console.log(); }]);这里range的start和end完全相同表示“在该点插入”不删除任何内容。模式二在指定行列插入绝对定位比如你解析出一个 JSON Schema想在第 10 行第 1 列插入一个// Generated by schema注释。const range new monaco.Range(10, 1, 10, 1); editor.executeEdits(schema-gen, [{ range, text: // Generated by schema\n }]);注意text中的\n会被正确识别为换行编辑器会自动增加新行。无需手动处理行号变更。4.3 替换文本从“覆盖”到“智能包裹”替换比插入复杂因为你需要精确计算range的起止点。场景一替换选中文本这是最直观的。用户选中一段文字按 CtrlShiftP 输入命令替换成新内容。const selection editor.getSelection(); if (!selection.isEmpty()) { // selection 是 ISelection可直接用作 range editor.executeEdits(replace-selection, [{ range: selection, text: new content }]); }场景二替换某个单词需 Position 精确定位你想把光标所在单词替换成大写。首先得找到单词的 Range。function getWordAtPosition(model: monaco.editor.ITextModel, position: monaco.Position): monaco.IRange | null { const word model.getWordAtPosition(position); if (!word) return null; return new monaco.Range( word.startLineNumber, word.startColumn, word.endLineNumber, word.endColumn ); } const model editor.getModel(); const pos editor.getPosition(); const wordRange getWordAtPosition(model, pos); if (wordRange) { const wordText model.getValueInRange(wordRange); editor.executeEdits(uppercase-word, [{ range: wordRange, text: wordText.toUpperCase() }]); }场景三智能包裹如给字符串加引号用户选中hello按 Ctrl想变成hello。这需要“包裹”而非简单替换。const selection editor.getSelection(); if (!selection.isEmpty()) { const model editor.getModel(); const selectedText model.getValueInRange(selection); const newText ${selectedText}; // 新 range覆盖原 selection并扩展两端 const newRange new monaco.Range( selection.startLineNumber, selection.startColumn - 1, // 左括号位置 selection.endLineNumber, selection.endColumn 1 // 右括号位置 ); editor.executeEdits(wrap-string, [{ range: newRange, text: newText }]); }这里startColumn - 1和endColumn 1的计算依赖你对 Position 的绝对信任。如果startColumn算错了括号就会插歪。4.4 高级技巧批量编辑与事务原子性executeEdits支持一次提交多个编辑操作它们会被视为一个原子事务。这意味着要么全部成功要么全部失败撤销CtrlZ会一次性撤销所有操作forceMoveMarkers对整个数组生效。// 一次添加 import 修改函数名 const edits [ // 在文件开头插入 import { range: new monaco.Range(1, 1, 1, 1), text: import { helper } from ./utils;\n }, // 修改第 5 行的函数调用 { range: new monaco.Range(5, 10, 5, 15), // 假设 doWork 占 5 列 text: doHelper } ]; editor.executeEdits(refactor, edits);实操心得批量编辑时务必按“从上到下、从左到右”的顺序排列 edits。因为编辑是顺序执行的前面的插入会影响后面 range 的行列号。上面的例子中如果我把修改函数名的 edit 放在前面它会基于原始文件计算 range放后面它就基于已插入 import 的新文件计算。所以顺序就是执行顺序必须精心设计。5. 常见问题与避坑指南那些让我熬夜改 Bug 的瞬间5.1 问题速查表高频故障与根因分析现象可能原因排查步骤解决方案Marker 不显示或显示在错误行lineNumber超出模型行数或column为 0console.log(model.getLineCount(), marker.startLineNumber)使用Math.min/max校验边界见 3.2 节安全构造函数光标跳转后位置偏移 1 列把column当作 0-based 索引使用editor.getPosition()对比预期值牢记column是 1-basedstr.length不等于columnexecuteEdits后 Marker 消失或错位未设置forceMoveMarkers: true且编辑影响了 Marker 位置检查编辑前后 Marker 的startColumn值对可能影响 Marker 的编辑显式设forceMoveMarkers: true插入文本后光标跑到行尾text中包含\n且range.endColumn计算错误console.log(range)和实际光标位置对比确保range的endLineNumber/endColumn与text的换行数匹配处理含 emoji/全角字符时列号错乱直接用str.length计算columnconsole.log([...str])查看 Unicode 字符数组用[...str]展开字符串再用indexOf5.2 我踩过的三个深坑与血泪教训坑一异步时机导致 Position 失效我曾写了一个“点击错误行跳转”的功能// ❌ 危险代码 editor.onMouseDown(e { if (e.target.position) { setTimeout(() { editor.setPosition(e.target.position); // 300ms 后跳转 }, 300); } });问题在于e.target.position是鼠标按下瞬间的 Position300ms 后用户可能已滚动、编辑、切换标签页editor.setPosition()会失败或跳到错误位置。Position 是瞬态快照不是持久引用。✅ 正确做法在setTimeout回调中重新获取当前位置上下文或使用editor.createPosition()创建一个稳定引用但仍有风险。最佳实践是所有 Position 操作尽可能在同步、确定的上下文中完成。坑二Range 跨行时的 column 计算灾难想替换第 3 行第 5 列到第 5 行第 3 列的文本。我写了// ❌ 错误跨行 Range 的 endColumn 不能随意设 const range new monaco.Range(3, 5, 5, 3);这在 Monaco 中是合法的 Range但语义是“从第 3 行第 5 列开始到第 5 行第 3 列结束”。如果第 4 行很短只有 2 列endColumn:3就超出了该行长度编辑器会静默修正为endColumn:3即第 5 行第 3 列但中间的第 4 行会被整行删除。这不是我想要的。✅ 正确做法跨行编辑必须明确每一行的起止column。用model.getValueInRange(range)先预览再决定是否拆分为多个单行 edit。坑三Marker 的 message 中文乱码在message字段里写变量未定义结果在问题面板显示为????。查了半天发现是打包工具Webpack的terser-webpack-plugin默认启用了keep_fnames: false把中文字符串压缩掉了。✅ 解决方案在 Webpack 配置中为 Monaco 相关代码禁用该选项或直接在message中使用英文前端用 i18n 映射。5.3 性能优化别让 Position 拖垮你的插件Position 操作本身极快但不当使用会引发连锁性能问题避免在onDidChangeModelContent中高频调用getLineContent()每行内容访问都是 O(n) 字符串拷贝。缓存model.getValue()全文用indexOf查找更高效。批量 Marker 更新不要为每个错误单独updateMarkers收集所有错误一次提交。懒计算 Position如果只是需要“大概位置”用editor.getPosition()获取当前光标比解析 AST 计算精确 Position 快 10 倍。最后分享一个小技巧Monaco 内置了monaco.Range.fromPositions(startPos, endPos)工厂方法。当你有两个 Position想快速生成 Range别手写new monaco.Range(...)用这个方法它会自动处理lineNumber/column的合法性校验省去一堆 if 判断。6. 实战案例构建一个“JSON Key 自动补全”功能现在我们把 Position、Marker、executeEdits 串起来做一个真实可用的功能当用户在 JSON 文件中输入{后自动补全为{key: value}并将光标定位到key处。6.1 需求拆解与 Position 关键点触发时机用户输入{且光标在行末或空格后。插入位置{的右侧即lineNumber,column 1。插入内容{key: value}其中key应高亮选中方便用户直接输入。Marker 用途如果用户输入的 JSON 格式错误如多了一个逗号在错误位置添加 warning Marker。6.2 完整代码实现带详细注释// 1. 注册语言配置监听输入 monaco.languages.registerCompletionItemProvider(json, { provideCompletionItems: (model, position, context, token) { // 只在行末或空格后触发 const lineContent model.getLineContent(position.lineNumber); const beforeCursor lineContent.substring(0, position.column - 1); // column 是 1-based所以 -1 if (!beforeCursor.trim().endsWith({)) return null; // 2. 构造插入范围在 { 后插入 const insertRange new monaco.Range( position.lineNumber, position.column, // { 的 column 是 x则插入位置是 x position.lineNumber, position.column ); // 3. 构造插入文本和选区 const snippetText {key: value}; // 选中 key从 { 后第 2 列开始{ 是 1 是 2k 是 3e 是 4y 是 5 是 6 // 所以 key 的 startColumn position.column 3, endColumn position.column 6 const keyStartColumn position.column 3; const keyEndColumn position.column 6; return { suggestions: [{ label: JSON Object, kind: monaco.languages.CompletionItemKind.Snippet, documentation: Insert a JSON object template, insertText: snippetText, range: insertRange, // 设置插入后的选区 selection: new monaco.Range( position.lineNumber, keyStartColumn, position.lineNumber, keyEndColumn ) }] }; } }); // 4. 同时添加 JSON 格式校验 Marker monaco.languages.setLanguageConfiguration(json, { onEnterRules: [{ // 当输入 } 后检查是否匹配 beforeText: /^\s*},?\s*$/, action: { indentAction: monaco.languages.IndentAction.None } }] }); // 5. 主动校验函数简化版 function validateJSON(model: monaco.editor.ITextModel) { try { JSON.parse(model.getValue()); // 无错误清空 Marker model.updateMarkers(json-validator, []); } catch (e) { // 解析错误提取行号列号 const message e.message; // 简化假设错误信息含 line X column Y const match message.match(/line (\d) column (\d)/); if (match) { const line parseInt(match[1], 10); const col parseInt(match[2], 10); const marker: monaco.editor.IMarkerData { severity: monaco.MarkerSeverity.Error, message: JSON parse error: ${message}, startLineNumber: line, startColumn: col, endLineNumber: line, endColumn: col 1, source: json-validator }; model.updateMarkers(json-validator, [marker]); } } } // 6. 在编辑器加载后启动校验 editor.onDidCreateModel((model) { if (model.getModeId() json) { validateJSON(model); } }); editor.onDidChangeModelContent((e) { const model editor.getModel(); if (model model.getModeId() json) { validateJSON(model); } });这个案例里position.column是核心支点它决定了插入位置、选区起始、甚至错误定位。没有对 Position 的深刻理解这个功能的每一行代码都可能出错。7. 总结Position 是编辑器世界的经纬度而你是测绘师写完这篇我翻出自己三年前的第一个 Monaco 插件代码里面还充斥着editor.setPosition({lineNumber: line, column: str.length})这样的写法。当时觉得“能跑就行”直到用户反馈在含 emoji 的文件里补全失效才意识到str.length和column之间隔着一个 Unicode 的鸿沟。Position 看似简单实则是 Monaco 编辑器世界观的基石。它把抽象的文本流映射到用户可感知的二维坐标系它让 Marker 能精准“钉”在错误上让executeEdits能像手术刀一样切除病灶。你每一次光标跳转、每一处波浪线、每一个代码补全背后都是 Position 在默默工作。所以别把它当成一个待 memorize 的 API。把它当作编辑器与你对话的语言。当你再看到{lineNumber: 5, column: 10}想到的不该是两个数字而是这是第 5 行从上往下数的第五道横线这是该行第 10 个“显示位置”无论那里是空格、emoji 还是汉字它是 Range 的起点是 Marker 的锚点是executeEdits的靶心。我在某高校实验室带学生做代码编辑器开发时总会让他们先花两天时间只做一件事写一个函数输入任意字符串和任意 Unicode 字符输出它在 Monaco 中的column值。很多人第一天交上来的是str.indexOf(char) 1第二天才改成[...str].indexOf(char) 1。这个过程就是在重建对编辑器坐标的直觉。最后再强调一次所有高级功能都始于对 Position 的敬畏。你不需要记住所有 API但必须刻进本能lineNumber从 1 开始column是可视列数Range的end不包含executeEdits的range必须有效。做到这点你就能稳稳握住 Monaco 的缰绳让它按你的意志驰骋。
阅读完成 · 觉得有帮助？
