# @braccato/highlight 中文文档

规范地址：https://npmcn.com/package/%40braccato/highlight/

版本：0\.3\.2
npm 元数据更新时间：2026-10-17T16:32:24.059Z
中文译文更新时间：2026-11-09T22:10:36.874Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40braccato/highlight
原文对照：https://npmcn.com/package/%40braccato/highlight/?lang=original
项目主页：https://braccato.boidu.dev/
源码仓库：https://github.com/better-lyrics/braccato

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：33.4 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-09-30T23:05:38.888Z
- 最新版本发布：2026-10-17T16:32:23.691Z
- 近 30 天下载量：1709（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

TTML, LRC, QRC 和 SRT 歌词的轻量级语法加亮

## 安装

```sh
npm install @braccato/highlight
```

也可以使用：`pnpm add @braccato/highlight`、`yarn add @braccato/highlight`、`bun add @braccato/highlight`

## README

# @braccato/高光

TTML 、 LRC 、 QRC 和 SRT 歌词的语法加亮, 超出零运行时依赖性 `@braccato/parsers/format`。它装有纯正的装饰器、只读相片的DOM渲染器和编辑器的文本区域。 印相与印相退取相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相出相相出相.

## 安装

```bash
npm i @braccato/highlight
```

## 使用量

### 仅读面板

```typescript
import { highlightInto } from "@braccato/highlight";
import "@braccato/highlight/highlight.css";

highlightInto(pre, source, { pretty: true });
```

`highlightInto` 添加 `bh` 类到元素,将符号颜色放入其下,并返回所使用的格式. `pretty: true` 将已修改的 TTML 切换成行 `head`, (中文(简体) ), `body`, (中文(简体) ), `div` 财务报告和审定财务报表 `p`。它只插入白空格,但所渲染的文本已不匹配源,因此仅用于显示,而从未在编辑器中显示。 线条格式忽略它 .

### 编辑器

```typescript
import { attachEditor } from "@braccato/highlight";
import "@braccato/highlight/highlight.css";

const editor = attachEditor(textarea);
```

`attachEditor` 将文本区域包成一个 `div.bh-edit` 并突出显示 `pre.bh-layer` 硂 文本区变得透明,并保持了被关注,选择和所有输入. 该图层复制了文本区域的字体、贴纸、边框宽度和框大小,并按其滚动位置排列.

层接一 `span.bh-line` 每个源行的块,每个块都有一个单一的文本节点。 颜色来自 [CSS 自定义突出显示 API](https://developer.mozilla.org/docs/Web/API/CSS_Custom_Highlight_API): 每个符号类型一个亮点,注册于 `CSS.highlights` 作为 `bh-<type>` 由页面上的每个编辑分享。 将一行分割成一行会使浏览器将每个片段的宽度相隔相隔一圈,一行只适合文本区,然后在地层早期将一字包住并逐行推倒. 一个单一的文本节点的设置恰好与文本区规定的其价值一致. 在缺少 API 的地方,该图层会显示相同位置的纯文本 .

每一个输入都重新将整个文档收录,因此背景相声等TTML状态在后行保持正确,但只有所改变的行被重写并重写.

只有一个编辑器高度上下方的文字才有颜色。 其余部分没有亮度范围。 卷轴留在边框内,一旦卷起就重新样式,再经过一卷则在下张画前重新样式.

在一款Apple M4 Pro上的Chrome 152中键中键成本,用于900中键被600像素编辑器所打入的中键文档. 脚本和布局为中位脚本外加强制样式和布局时间;颜料为相框的绘画相:

| 文档 | 脚本和布局 | 绘画 |
| --- | --- | --- |
| 21.4k-字符单行 TTML | 2.8个毫秒 | 17分钟 |
| 98k-字符单行 TTML | 7.1毫秒(每秒) | 26分钟 |
| 320线 TTML | 3.2个毫秒 | 1.6 毫秒(多径) |
| 2 000行 LRC | 3.6 毫秒(多发数) | 1.3 分钟 |

一个键盘重漆了整个文本节点, 它降落在其中, 上面每个亮点, 所以一个长行是缓慢的情况: 可见文本重漆成每块一个符号.

卷卷起后每向编辑高度滚动一次. 在98k-特征线上重排成本约一分半键,多行文档小于一;在成本相间滚动步骤为0.2ms.

货包为10.9 KB 精密型和 4.7 KB gziped (`esbuild --minify`),加 (中文(简体) ) `@braccato/parsers/format`。 。 。 .

它回来了 `{ wrap, layer, refresh, setFormat, destroy }`数字 :

-   设置 `textarea.value` 从代码不起火 `input`,所以打电话 `editor.refresh()` 在每次程序写完之后.
-   `editor.destroy()` 将文本区域放回原位置,取出包装并删除 `bh-input` 课。 两次就安全了.
-   过 `{ format }` 来标出格式。 没有它,格式在每个渲染上都会被检测出,所以粘贴不同的格式会再有颜色.
-   编辑器在附加并拥有其格式时会复制这些选项. 以后更改选项对象无所作为 .
-   `editor.setFormat(format)` 立即更改活编辑器的格式并重报。 文本区没有被重新附着,所以它的原生倒数历史得以存续. `editor.setFormat(undefined)` 返回到检测每个渲染处的格式。 通过当前固定格式(或) `undefined` 在探测时)无所作为. 在检测模式中,传递被检测到的格式会把它钉上. `setFormat` 不替换 `refresh()` 在程序写入之后 `textarea.value`: 调用 `refresh()` 对于新值,无论格式是否改变.
-   附加已拥有活编辑器的文本区域返回编辑器的手柄并忽略新选项. 使用 `setFormat` 上键以更改格式.

覆盖需要文本区和图层来共享一个框,所以 `.bh-input` 部队 `margin: 0`, (中文(简体) ), `box-sizing: border-box`, (中文(简体) ), `width: 100%` 财务报告和审定财务报表 `resize: none` 文本区域。 层复制盒大小,所以一个文本区的粘贴和边框留在包件内,两个包线的宽度相同. 将主机想要的任何边距或宽度放入包装上(`.bh-edit`,或 `editor.wrap`相反.

亮点只能改变颜色,所以背景相声和评论在编辑器中不是斜体相通,以及 `--bh-bgText-style` 仅适用于只读的面板。 背景相声在编辑器中被淡化,通过 `--bh-bgText-editor`。任何字体都有作用:图层从未改变文本任何部分的字体.

### 仅指针

```typescript
import { tokenize } from "@braccato/highlight";

const tokens = tokenize(source); // [{ type: "punct", text: "[" }, { type: "timestamp", text: "00:14.21" }, ...]
```

令牌的相接文字总是等同输入,相接的相接符号没有两个共享一个类型. 他们到底是什么 `highlightInto` 绘图,因此您自己的一个渲染器( 例如在服务器上制作的 React 组件) 通过将每个符号绘制如下来复制, 没有合并步骤 :

```tsx
tokens.map(({ type, text }, i) => (type === "text" ? text : <span key={i} className={`bh-${type}`}>{text}</span>));
```

将结果与 `bh` 分类,所以符号颜色适用. `highlightInto` 与 `pretty: true` 符号 `prettyTtml(source)` 而不是来源.

## 键

在只读的相片中,每个相片成一个 `<span class="bh-<type>">`时,除 `text`,它作为一个纯文本节点。 在编辑器中,每个符号在 `bh-<type>` 突出显示. `tokenize` 已将相邻的同类型文本合并为一个符号.

| 脚本 | 含义 |
| --- | --- |
| `text` | 成语文. 它也用于白空和新线. |
| `bgText` | TTML 内有成文文字 `ttm:role="x-bg"` 间距. |
| `timestamp` | 线条时间 : `[00:14.21]`,一个 TTML `begin`, (中文(简体) ), `end` 或者说 `dur` 数值, `[14210,4350]`,或者SRT提示时间. |
| `wordTime` | 单词时间: `<00:18.90>` 或者说 `(14210,300)`。 。 。 . |
| `agent` | 一个声音 : `v1:` 在 LRC 中,或 TTML 中 `ttm:agent`, (中文(简体) ), `ttm:role` 或者说 `xml:id` 数值. |
| `meta` | 元数据: LRC 或 QRC `[ti:...]` 键, TTML 中的文本 `<head>`,或SRT提示号. |
| `tag` | 一个 TTML 元素名称 . |
| `attr` | TTML 属性名称 . |
| `value` | 其他属性值,或 LRC 元值. |
| `punct` | 括号,引文, `<` `>` `/` `=`,和特别审判庭 `-->`。 。 。 . |
| `comment` | `<!-- ... -->` 财务报告和审定财务报表 `<?xml ... ?>`。 。 。 . |

## 他们

每个颜色都是CSS自定义属性并有内置倒置. 样式表没有定义全局自定义属性, 因此将其中任何属性设置在窗格的祖先上 :

```css
.my-pane { --bh-timestamp: #86efac; }
```

| 财产 | 默认 |
| --- | --- |
| `--bh-text` | `rgba(255, 255, 255, 0.95)` |
| `--bh-bgText` | `rgba(255, 255, 255, 0.82)` |
| `--bh-bgText-style` | `italic` |
| `--bh-bgText-editor` | `rgba(255, 255, 255, 0.65)` |
| `--bh-timestamp` | `rgba(165, 180, 252, 0.7)` |
| `--bh-wordTime` | `rgba(165, 180, 252, 0.52)` |
| `--bh-agent` | `rgba(252, 211, 77, 0.45)` |
| `--bh-meta` | `rgba(249, 168, 212, 0.38)` |
| `--bh-tag` | `rgba(255, 255, 255, 0.26)` |
| `--bh-attr` | `rgba(255, 255, 255, 0.22)` |
| `--bh-value` | `rgba(134, 239, 172, 0.3)` |
| `--bh-punct` | `rgba(255, 255, 255, 0.16)` |
| `--bh-comment` | `rgba(255, 255, 255, 0.2)` |
| `--bh-caret` | `#fff` |
| `--bh-selection` | `rgba(165, 180, 252, 0.28)` |
| `--bh-placeholder` | `rgba(255, 255, 255, 0.35)` |

## 检测

未给出格式时, 用 `detectFormat` 从 `@braccato/parsers/format`这些是相同的规则 `detectParser` 使用,在同一优先级中:TTML、LRC、SRT、QRC,然后是平原。 子路径是无依赖的, 因此强调绝不在 XML 解析器中拉出 .

## 常见问题

### @braccato/highlight 是什么？

TTML, LRC, QRC 和 SRT 歌词的轻量级语法加亮

### 如何安装 @braccato/highlight？

在项目目录运行 npm install @braccato/highlight，或使用 pnpm add / yarn add / bun add。

### @braccato/highlight 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @braccato/highlight 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @braccato/highlight 可以商用吗？

@braccato/highlight 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @braccato/highlight 的下载量有多少？

根据 npm 官方下载统计，@braccato/highlight 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,709 次，日均约 57 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @braccato/highlight 还在维护吗？

最新版本 0\.3\.2 发布于 2026/10/18（23 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/10/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。