# 扩展 扩展可以给编辑器加上装饰、行号旁的标记、面板、小部件和检查。用 `defineCodeExtension` 定义扩展,通过 `extensions` 传给编辑器。 ## 定义扩展 下面的示例包含三个扩展:标出 `TODO`、找出 `var` 并提供修复、点击行号左侧设置断点。 ```ts import { defineCodeExtension, type CodeDecoration } from '@dou-ui/code' const todo = defineCodeExtension({ name: 'todo', decorations(editor) { const out: CodeDecoration[] = [] for (let n = editor.visible.from; n <= editor.visible.to; n++) { const line = editor.doc.line(n) const at = line.text.indexOf('TODO') if (at >= 0) out.push({ type: 'mark', from: line.from + at, to: line.from + at + 4, class: 'todo' }) } return out }, }) ``` 扩展中的函数都会收到编辑器的上下文。上下文包含编辑器实例的全部属性和方法,另外还有 `visible`、`announce` 等,见下方 [API](#codeextensioncontext)。在面板或行号栏中渲染的组件可以用 `useCodeEditor()` 获取同一个上下文。 ## 装饰 `decorations` 返回要装饰的文字,在绘制时调用,只需要给出可见的行: - `{ type: 'mark', from, to, class, style?, title? }` 给一段文字加 class。`style` 适合放每个人不同的颜色这类值,如 `{ '--my-color': '#3b6ea8' }`。 - `{ type: 'line', line, class }` 给整行加 class,`line` 从 1 开始。 - `{ type: 'inline', pos, render, width?, id? }` 在 `pos` 处的字符之前放一个小部件,见[行内小部件](#行内小部件)。 `mark` 和 `line` 只能改变颜色、底色、下划线、边框等,不能改变字号和字重,否则光标位置会不准。 `decorations` 中读到的响应式数据变化时,装饰会自动更新。 ## 行号栏 `gutters` 在行号左侧加一列,例如断点、修改标记: ```ts defineCodeExtension({ name: 'breakpoint', gutters: [ { name: 'breakpoint', markers: () => [...breakpoints.value].map((line) => ({ line, title: '移除断点' })), onPress: (line) => toggle(line), }, ], }) ``` 有 `onPress` 的列里,每个标记都是一个按钮,`title` 是它的名称,必须填写(缺少时开发环境会给出警告)。光标所在行的标记可以用键盘操作:按 `Esc` 离开编辑区,再按 `Shift` + `Tab` 聚焦到它,按 `Enter` 或 `Space` 触发 `onPress`,第二个参数是这次的 `KeyboardEvent`。从页面上按 `Tab` 进入编辑器时,也会先停在这个标记上,再进入编辑区。按下后标记消失时(例如移除断点),焦点回到编辑区。其他行的标记不进入 Tab 顺序,免得一屏几十个标记挡在编辑区前面。没有标记的格子只能用鼠标或手指点。 开了 `wrap` 时,一行折成几行,这一行的格子也跟着整行一样高:点折出来的那几行旁边的格子,同样算点这一行;图标和文字留在第一行居中,焦点环也只画在第一行。标记的 `class` 设了底色的话,底色会铺满整行的高度;只想在第一行画一个色块,就用 `::before` 画,上面示例里的断点圆点就是这样画的。`::after` 留给可按格子的焦点环,标记的 `class` 不要用它,否则获得焦点时会被焦点环顶掉。 需要在每一行提供一个操作时(比如“在这一行加断点”“在这一行写批注”),可以给列设置 `hoverMarker`:没有自己标记的行都会显示它,平时隐藏,在鼠标指着这一行(行号栏或文字都可以)、编辑器有焦点时光标所在的行、以及它自己获得焦点时显示;编辑器禁用时不显示。上面的示例里,指着某一行就会出现空心的断点。只想在部分行上提供时,给那些行返回 `visible: 'hover'` 的标记,效果相同。 触屏和触控笔上,点按在手指抬起、且没有移动时才触发 `onPress`,从行号栏开始拖动只会滚动。手指没法悬停,所以点一个还看不见的悬停标记时,第一下只把光标移到这一行,标记随之出现,再点一下才触发。 ## 小部件 小部件是画在文字中的组件,分为画在一行之内的行内小部件和插在两行之间的行间小部件。 ### 行内小部件 行内小部件画在一行文字中间,例如颜色值前的色块、参数名提示。它不是文字:光标会跳过它,复制时也不包含它。 给出 `width`(px)时按这个宽度排版;不给时绘制后测量宽度,并按 `id` 记住。位置会变化的小部件最好给出 `id`。 ### 行间小部件 `widgets` 返回插在两行之间的组件,例如审阅评论。小部件横跨整个编辑区,下方的行会让出位置。 - 用 `pos`(文本位置)或 `line`(行号)指定位置,默认画在这一行下方,`position: 'above'` 时画在上方。 - `widgets` 要返回全部文本中的小部件,因为它们的高度会影响后面每一行的位置,所以数量不宜过多。 - 小部件中可以放输入框和按钮。只用键盘时,按 `Esc` 再按 `Tab` 可以进入小部件。 - `label` 是小部件的名称,光标移到所在行时读屏会读出。 小部件的位置由扩展自己保存。上面的示例把评论的位置存为文本位置,在 `transaction` 事件中用 `changes.mapPos` 跟随修改移动。 ## 面板 `panels` 返回显示在编辑区上方或下方的栏,位于编辑器边框之内: ```ts defineCodeExtension({ name: 'status', panels: (editor) => [ { name: 'status', position: 'bottom', render: () => h('div', `共 ${editor.doc.lines} 行`) }, ], }) ``` ## 隐藏行 `hide` 返回不显示的行,例如对比时收起的行。上下移动光标时会跳过它们,原处不留标记;需要提示时,自己在那里放一个行间小部件。 ## 响应修改 扩展可以在每次修改前后执行自己的逻辑: - `transaction` 在每次修改应用之前调用,可以在同一次修改中追加改动。撤销、重做、外部传入的新值和其他人的修改不经过这里。 - `update` 在每次修改应用之后调用,包括撤销、重做、外部传入的新值和其他人的修改,用 `meta.action` 区分。 ## API ### CodeExtension | 名称 | 说明 | 类型 | | -------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------ | | `name` | 扩展的名称,用于区分各个扩展找到的问题 | `string` | | `priority` | 优先级,大的先执行,它的快捷键也先尝试;默认 `100` | `number` | | `keymap` | 快捷键,优先于内置快捷键,在 `keymap` 属性之后 | `(context) => CodeKeymap` | | `decorations` | 装饰 | `(context) => CodeDecoration[]` | | `gutters` | 行号左侧的列 | `CodeGutter[]` | | `widgets` | 行间小部件 | `(context) => CodeWidget[]` | | `hide` | 不显示的行,两端都包含 | `(context) => { from, to }[]` | | `panels` | 上方或下方的栏 | `(context) => CodePanel[]` | | `lint` | 检查文本,见[诊断](./assist#诊断) | `(context) => CodeDiagnostic[] \| Promise` | | `completion`、`completionTriggers`、`hover`、`signature` | 补全和提示,见[补全与提示](./assist#补全) | — | | `transaction` | 修改应用之前调用 | `(tr, context) => void` | | `update` | 修改应用之后调用 | `(result, context) => void` | | `history` | 替换内置的撤销记录,例如协同编辑;有多个时使用第一个 | `(context) => CodeHistoryHandler` | | `menu` | 触屏选区工具条中追加的按钮 | `(context) => { label, run }[]` | | `setup` | 挂载后调用一次,返回的函数在卸载时调用 | `(context) => void \| (() => void)` | ### CodeExtensionContext 编辑器实例的全部属性和方法,以及: | 名称 | 说明 | | ---------------- | --------------------------------------------------------- | | `visible` | 可见的行 `{ from, to }`,是行号而不是文本位置,两端都包含 | | `diagnostics` | 当前的所有问题 | | `focused` | 编辑器是否有焦点 | | `messages` | 编辑器使用的文字 | | `announce(text)` | 让读屏读出一句话 | | `relint(name?)` | 立即重新运行某个扩展的 `lint`,不传时运行全部 | ### CodeGutter | 名称 | 说明 | 类型 | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `name` | 列的名称 | `string` | | `width` | 宽度(px),默认 `16` | `number` | | `markers` | 可见行上的标记 `{ line, icon?, text?, class?, title?, visible? }`;有 `onPress` 时 `title` 必填;`visible: 'hover'` 时只在指着这一行、光标在这一行或它有焦点时显示 | `(context) => CodeGutterMarker[]` | | `pressOn` | `onPress` 在哪里响应:默认 `any`,这一列的任何格子都能点(比如在空行上加断点);`markers` 时只有标记能点,空格子不显示手形光标 | `'any' \| 'markers'` | | `hoverMarker` | 没有自己标记的每一行都显示的标记 `{ icon?, text?, class?, title? }`,悬停时出现;有 `onPress` 时 `title` 必填。`title` 可以是 `(line) => string`,给每一行一个名称,比如“在第 3 行加断点”;它会对可见的每一行频繁调用,不要做耗时操作 | `CodeGutterHoverMarker` | | `onPress` | 点击某一行的这一列,或在标记上按 `Enter`、`Space` | `(line, event: PointerEvent \| KeyboardEvent, context) => void` | ### CodeWidget | 名称 | 说明 | 类型 | | ---------- | -------------------------------------- | -------------------- | | `id` | 在同一个扩展中唯一 | `string` | | `pos` | 所在的文本位置,和 `line` 二选一 | `number` | | `line` | 所在的行号,从 1 开始 | `number` | | `position` | 画在这一行的上方或下方,默认 `'below'` | `'above' \| 'below'` | | `render` | 渲染函数 | `() => VNodeChild` | | `height` | 绘制前估计的高度(px),默认一行 | `number` | | `label` | 读屏读出的名称 | `string` | ### CodePanel | 名称 | 说明 | 类型 | | ---------- | --------------------- | ------------------- | | `name` | 在同一个扩展中唯一 | `string` | | `position` | 位置,默认 `'bottom'` | `'top' \| 'bottom'` | | `render` | 渲染函数 | `() => VNodeChild` |