petersolopov/yace

GitHub: petersolopov/yace

Yace 是一个体积不到 2KB、零依赖、可扩展的浏览器端代码编辑器组件，适用于不需要完整 IDE 但需要语法高亮和编辑增强的场景。

Stars: 97 | Forks: 6

# Yace [![npm](https://badgen.net/npm/v/yace/?cache=300)](https://www.npmjs.com/package/yace) [![Coverage Status](https://coveralls.io/repos/github/petersolopov/yace/badge.svg)](https://coveralls.io/github/petersolopov/yace) [![bundlephobia](https://badgen.net/bundlephobia/minzip/yace?label=size)](https://bundlephobia.com/result?p=yace) Yace 是一个微型、可扩展的代码编辑器组件，适用于普通的 `

` 无法满足需求，而使用 Monaco 或 CodeMirror 又过于繁重的场景。

gzip 压缩后体积小于 2KB。零依赖。与框架无关。

- 输入保持在真实的 `<textarea>` 中，保留了原生的光标行为、IME、移动端输入、选区和可访问性
- 插件仅添加你所需的编辑行为：历史记录、缩进、括号配对、快捷键，或你自定义的转换
- 高亮器控制你输入时显示的内容：代码、Markdown、token、动画，或你自己的渲染器
- 编辑器挂载到 DOM 节点中，可与 React、Vue、原生 JS 或任何其他技术一起使用

[查看在线示例](#examples)

## 适用场景

将 Yace 用于嵌入式代码示例、文档演练场、Markdown 输入、prompt 编辑器、token 可视化工具以及自定义文本体验。它为你提供语法高亮和编辑钩子，而无需将一个完整的 IDE 引入页面。

如果你需要处理大型文档的虚拟化、多光标编辑、富文本或完整的语言工具平台，请使用 Monaco 或 CodeMirror。Yace 刻意保持较小的体积，并为你提供组件，让你能够构建真正需要的编辑器。

## 快速开始

从 npm 安装 Yace：

```
npm install yace
```

添加一个挂载点：

```
<div id="editor"></div>
```

创建一个带有语法高亮和熟悉编辑行为的编辑器：

```
import { Yace } from "yace";

import { code } from "yace/highlighters/code";

import { history, preserveIndent, tab } from "yace/plugins";

const editor = new Yace("#editor", {

value: "const answer = 42;",

lineNumbers: true,

highlighters: [code()],

plugins: [history(), tab(), preserveIndent()],

});

editor.onUpdate((value) => console.log(value));
```

Yace 仅支持 ESM。你也可以在没有构建步骤的情况下直接从 CDN 加载核心库：

```
import { Yace } from "https://unpkg.com/yace?module";
```

## 工作原理

一个透明的 `<textarea>` 位于带有高亮效果的 `<pre>` 之上。textarea 负责输入、光标、选区、IME 和可访问性。`<pre>` 则在其下方绘制相同的文本。

这种覆盖层模式已经相当成熟。Yace 保持了精简的实现，并将这两个扩展点转化为明确的流水线：

- 插件接收 textarea 状态和输入事件，然后返回下一个文本和选区
- 高亮器接收当前值并返回由 `<pre>` 渲染的 HTML；将它们串联起来可以先进行 token 化，然后再对结果进行装饰

核心库没有内置必需的高亮器或编辑行为。从原生 textarea 开始，仅添加编辑器所需的功能即可。

## 示例

从编辑器本身开始：

- [内置代码高亮器入门](https://codepen.io/petersolopov/pen/JoELdOr)
- [使用 highlight.js 作为高亮器](https://codepen.io/petersolopov/pen/dPNddwg)
- [使用 PrismJS 作为高亮器](https://codepen.io/petersolopov/pen/RNKQMaX)
- [添加撤销、Tab、缩进和剪切行插件](https://codepen.io/petersolopov/pen/GgrQxjg)
- [在 React 中使用 Yace](https://codepen.io/petersolopov/pen/XJpZEKq)
- [构建一个 Markdown 编辑器](https://codepen.io/petersolopov/pen/NPdyYrR)

进一步利用这些流水线：

- [编写一个插件](https://codepen.io/petersolopov/pen/OPWvyOM)
- [用大约 15 行代码编写一个高亮器](https://codepen.io/petersolopov/pen/dPNmYWr)
- [高亮 Markdown 和围栏代码块](https://codepen.io/petersolopov/pen/pvRaLbw)
- [在可编辑的 OpenAI 风格视图中可视化 LLM token](https://codepen.io/petersolopov/pen/emgMpMr)
- [在选定的单词上叠加微光和故障效果](https://codepen.io/petersolopov/pen/Qwdmjxg)

## 构造函数选项

`new Yace(target, options)` 接受一个 CSS 选择器或 DOM `Node`。所有选项都是可选的：

```
new Yace(target, {

value: "",           // sets the initial text

highlighters: [],    // defines the rendering pipeline

plugins: [],         // defines the editing pipeline, reduced from left to right

lineNumbers: false,  // adds a line-number gutter

styles: {},          // applies inline styles to the editor root, such as `{ fontSize: "20px" }`

});
```

## 实例 API

Yace 构建的 DOM 及驱动它的方法：

- `editor.value` 保存当前文本
- `editor.textarea` 暴露真实的 `<textarea>`，用于焦点、`readOnly`、`spellcheck` 和其他原生功能
- `editor.root` 暴露挂载元素
- `editor.pre` 暴露高亮的 `<pre>` 层
- `editor.onUpdate((value: string) => void)` 注册编辑时的回调函数
- `editor.update({ value?, selectionStart?, selectionEnd? })` 更新文本或选区；仅更新值时会保留当前选区
- `editor.updateOptions({ value?, lineNumbers?, highlighters?, plugins?, styles? })` 在实时编辑器上更改构造函数选项
- `editor.destroy()` 移除监听器和节点并恢复容器；后续的 `update()` 调用将是静默的无操作

## 插件

插件接收 textarea 状态和 DOM 事件，然后返回下一个状态或不返回任何内容：

```
type Plugin = (

props: TextareaProps,

event: Event,

) => Partial<TextareaProps> | void;

interface TextareaProps {

value: string;

selectionStart: number;

selectionEnd: number;

}
```

Yace 会在 `keydown`、`input` 和 `compositionend` 时从左到右运行插件。每个插件都会看到前一个插件的结果。

```
import { Yace } from "yace";

const upperCase = ({ value }) => ({ value: value.toUpperCase() });

new Yace("#editor", { plugins: [upperCase] });
```

第一方插件可从 `yace/plugins` 或单独的子路径（例如 `yace/plugins/tab`）获取：

- `history({ limit = 300, coalesceMs = 300 })` 添加撤销和重做功能，通过 `limit` 限制存储状态的数量，并使用 `coalesceMs` 合并相近的编辑；它必须是流水线中的第一个
- `tab(tabCharacter = "  ")` 通过 Tab 和 Shift+Tab 对选区进行缩进或减少缩进
- `preserveIndent()` 将当前行的缩进延续到下一行
- `cutLine(predicate?)` 在 Ctrl/Cmd+X 时剪切选区或当前行；`predicate` 可覆盖触发条件
- `autoClose(pairs?)` 插入匹配的括号，包裹选区，跳过已存在的闭合字符，并一并删除空的配对
- `toggleComment(prefix = "// ", predicate?)` 在当前行或选区切换行注释；空行会被跳过
- `isKey(shortcut, event)` 匹配快捷键，支持 Ctrl/Cmd 标准化，并为非拉丁键盘布局提供物理按键代码回退

## 高亮

高亮器将文本转换为 HTML。Yace 会将结果赋值给 `innerHTML`，因此第一个高亮器必须对用户文本进行转义。直接返回原始输入会造成 XSS 漏洞。

```
type Highlighter = (value: string, context?: { html: boolean }) => string;
```

高亮器作为流水线运行。第一个阶段接收带有 `context.html === false` 的原始文本。后续阶段接收带有 `context.html === true` 的前一阶段的 HTML，因此它们必须保留标签，而不是再次对整个输入进行转义。空的流水线会回退到 Yace 的转义高亮器。

```
import { Yace } from "yace";

import { code } from "yace/highlighters/code";

import { shimmer } from "yace/highlighters/shimmer";

new Yace("#editor", {

highlighters: [code(), shimmer({ words: ["TODO"] })],

});
```

高亮器必须保持字符的字宽不变，否则绘制出的文本会偏离原生的光标位置。只有当字体堆栈中的每种字体都是严格的等宽字体时，粗体和斜体才是安全的。

第一方高亮器可从 `yace/highlighters` 或单独的子路径（例如 `yace/highlighters/code`）获取：

- `code(extraRules?)` 是一个可扩展的 tokenizer，可发出 `yace-tok` 类而不强制指定颜色；自定义规则会在内置规则之前运行
- `markdown()` 使用内置的 [mdhl](https://github.com/petersolopov/mdhl) 高亮 Markdown 并发出 `mdhl-*` 类；请将其放在第一位或单独使用
- `sliceGlitch(options?)` 将行分割为错位的 RGB 切片，并暴露 `--yace-slice-a` 和 `--yace-slice-b` 用于主题定制
- `shimmer(options?)` 在文本上扫过一条光带，并暴露 `--yace-shimmer-base` 和 `--yace-shimmer-band` 用于主题定制

`sliceGlitch` 和 `shimmer` 还接受一个 `words` 数组，用于仅装饰匹配的单词。它们会在运行时注入其动画 CSS；而 `code` 和 `markdown` 仅发出类，因此需要由使用者提供 token 颜色。

## 浏览器支持

Yace 支持常青浏览器版本的 Chromium、Firefox、WebKit 以及当前的移动端浏览器。它仅限客户端使用并且需要 DOM。不支持 IE 和 SSR。

## 非目标

按照设计，处理大型文档、多光标编辑、富文本、装饰以及 SSR 均不在范围之内。它们需要的是文档模型，而不是 textarea 覆盖层。

## 注意事项

- 在使用打包工具时，`yace/plugins` 和 `yace/highlighters` 可以正常进行 tree-shaking；而在使用原生浏览器模块时，建议使用确切的路径（例如 `yace/plugins/tab`）以避免请求每一个同级文件
- 在 Node 22+ 上执行 `require("yace")` 会返回 ESM 模块的命名空间，因此请使用 `const { Yace } = require("yace")`；这同样适用于每一个子路径
- 编译为 CommonJS 的 TypeScript 使用者需要 `"module": "nodenext"` 以及 TypeScript 5.8 或更高版本；`node16` 会拒绝 `require` 一个 ESM 包
- Jest 默认的 CommonJS 运行时无法加载 ESM；请使用 Vitest 或 Jest 的 ESM 模式
- 只有当完整的字体堆栈严格为等宽字体时，token 样式才能使用粗体或斜体；比例缩放的回退字体会导致绘制的图层偏离光标位置

## 开发

安装依赖并在 `http://localhost:5714` 启动落地页：

```
npm install

npm run dev
```

在提交更改之前验证库：

```
npm test

npm run typecheck

npm run prettier:check

npm run test:e2e

npm run attw
```

## 许可证

[MIT](/LICENSE)</div><div><strong>标签：</strong>Web组件, 代码编辑器, 数据可视化, 自定义脚本, 语法高亮, 零依赖</div></article></div>
    
    <script>
      (function () {
        var base = (document.querySelector('base') && document.querySelector('base').getAttribute('href')) || '';
        var path = base.replace(/\/?$/, '') + '/cap-wasm/cap_wasm.min.js';
        window.CAP_CUSTOM_WASM_URL = new URL(path, window.location.href).href;
      })();
    </script>
  </body>
</html>