@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/highlight.md

@@ -0,0 +1,363 @@
+# 语法高亮引擎 / Syntax Highlighting
+
+Aithe UI 内置自研语法高亮引擎 `SyntaxRegistry`，无需第三方依赖。引擎基于正则表达式规则匹配，支持多语言注册、自定义规则扩展，并与 `<aithe-code-editor>` 组件深度集成。
+
+> 源码位置：`src/core/highlight/`
+
+---
+
+## 架构概览
+
+```bash
+src/core/highlight/
+├── index.ts           # 导出入口，自动注册所有内置语言
+├── registry.ts        # 核心引擎：SyntaxRegistry 类
+├── lang-javascript.ts # 内置语言定义（自动注册）
+├── lang-typescript.ts
+├── lang-c.ts
+├── lang-cpp.ts
+├── lang-java.ts
+├── lang-html.ts
+├── lang-xml.ts
+├── lang-json.ts
+├── lang-jsonline.ts
+├── lang-yaml.ts
+├── lang-markdown.ts
+├── lang-python.ts
+├── lang-ruby.ts
+├── lang-bash.ts
+├── lang-css.ts
+├── lang-sql.ts
+├── lang-rust.ts
+├── lang-go.ts
+├── lang-kotlin.ts
+├── lang-swift.ts
+├── lang-jsx.ts
+├── lang-tsx.ts
+├── lang-vue.ts
+├── lang-svelte.ts
+├── lang-wasm.ts
+├── lang-dockerfile.ts
+├── lang-makefile.ts
+├── lang-cmake.ts
+├── lang-latex.ts
+├── lang-fsharp.ts
+├── lang-powershell.ts
+├── lang-perl.ts
+├── lang-lua.ts
+├── lang-scala.ts
+├── lang-dart.ts
+├── lang-r.ts
+└── lang-objectivec.ts
+```
+
+**工作流程**：
+
+1. 语言文件导入时自动调用 `SyntaxRegistry.register()` 注册
+2. 调用 `SyntaxRegistry.highlightByLanguage(code, langId)` 执行高亮
+3. 引擎按规则匹配代码，收集所有匹配范围（`MatchRange`）
+4. 合并重叠范围，生成带 `<span class="hl-*">` 的 HTML 输出
+
+---
+
+## 核心 API
+
+### `SyntaxRegistry`
+
+全局单例注册表，所有方法均为静态。
+
+#### 注册与查询
+
+| 方法                                        | 说明               |
+| ------------------------------------------- | ------------------ |
+| `register(def: LanguageDefinition)`         | 注册一种语言定义   |
+| `get(langId: string)`                       | 获取语言定义       |
+| `getAll(): Map<string, LanguageDefinition>` | 获取所有已注册语言 |
+| `has(langId: string): boolean`              | 检查语言是否已注册 |
+| `unregister(langId: string): boolean`       | 注销一种语言       |
+| `clear()`                                   | 清空所有语言注册   |
+
+#### 高亮渲染
+
+| 方法                                                        | 说明                       |
+| ----------------------------------------------------------- | -------------------------- |
+| `highlightCode(code: string, rules: SyntaxRule[]): string`  | 使用指定规则列表高亮代码   |
+| `highlightByLanguage(code: string, langId: string): string` | 根据已注册语言 ID 高亮代码 |
+| `escapeHtml(str: string): string`                           | HTML 转义工具方法          |
+
+### 类型定义
+
+```typescript
+interface SyntaxRule {
+  pattern: RegExp; // 匹配模式（需使用全局标志 /g）
+  className: string; // 匹配到的内容应用的 CSS 类名（如 'hl-keyword'）
+  order: number; // 优先级，数值越小优先级越高
+}
+
+interface LanguageDefinition {
+  langId: string; // 语言唯一标识（如 'javascript'）
+  name?: string; // 语言显示名称（如 'JavaScript'）
+  rules: SyntaxRule[]; // 语法规则列表
+}
+```
+
+---
+
+## 内置语言
+
+| langId     | name        | 文件                 |
+| ---------- | ----------- | -------------------- |
+| javascript | JavaScript  | `lang-javascript.ts` |
+| typescript | TypeScript  | `lang-typescript.ts` |
+| c          | C           | `lang-c.ts`          |
+| cpp        | C++         | `lang-cpp.ts`        |
+| java       | Java        | `lang-java.ts`       |
+| html       | HTML        | `lang-html.ts`       |
+| xml        | XML         | `lang-xml.ts`        |
+| json       | JSON        | `lang-json.ts`       |
+| jsonline   | JSON (Line) | `lang-jsonline.ts`   |
+| yaml       | YAML        | `lang-yaml.ts`       |
+| markdown   | Markdown    | `lang-markdown.ts`   |
+| python     | Python      | `lang-python.ts`     |
+| ruby       | Ruby        | `lang-ruby.ts`       |
+| bash       | Bash        | `lang-bash.ts`       |
+| css        | CSS         | `lang-css.ts`        |
+| sql        | SQL         | `lang-sql.ts`        |
+| rust       | Rust        | `lang-rust.ts`       |
+| go         | Go          | `lang-go.ts`         |
+| kotlin     | Kotlin      | `lang-kotlin.ts`     |
+| swift      | Swift       | `lang-swift.ts`      |
+| jsx        | JSX         | `lang-jsx.ts`        |
+| tsx        | TSX         | `lang-tsx.ts`        |
+| vue        | Vue         | `lang-vue.ts`        |
+| svelte     | Svelte      | `lang-svelte.ts`     |
+| wasm       | WebAssembly | `lang-wasm.ts`       |
+| dockerfile | Dockerfile  | `lang-dockerfile.ts` |
+| makefile   | Makefile    | `lang-makefile.ts`   |
+| cmake      | CMake       | `lang-cmake.ts`      |
+| latex      | LaTeX       | `lang-latex.ts`      |
+| fsharp     | F#          | `lang-fsharp.ts`     |
+| powershell | PowerShell  | `lang-powershell.ts` |
+| perl       | Perl        | `lang-perl.ts`       |
+| lua        | Lua         | `lang-lua.ts`        |
+| scala      | Scala       | `lang-scala.ts`      |
+| dart       | Dart        | `lang-dart.ts`       |
+| r          | R           | `lang-r.ts`          |
+| objectivec | Objective-C | `lang-objectivec.ts` |
+
+所有内置语言在 `src/core/highlight/index.ts` 中通过 import 自动注册，无需手动调用。
+
+---
+
+## 高亮样式类
+
+引擎输出的 HTML 使用以下 CSS 类名，每个类名对应一种语义化颜色变量：
+
+| CSS 类             | CSS 变量                    | 默认颜色  | 用途            |
+| ------------------ | --------------------------- | --------- | --------------- |
+| `.hl-keyword`      | `--aithe-code-keyword`      | `#a626a4` | 编程语言关键字  |
+| `.hl-boolean`      | `--aithe-code-boolean`      | `#986801` | 布尔值          |
+| `.hl-builtin`      | `--aithe-code-builtin`      | `#4078f2` | 内置对象/全局量 |
+| `.hl-number`       | `--aithe-code-number`       | `#986801` | 数值            |
+| `.hl-string`       | `--aithe-code-string`       | `#50a14f` | 字符串字面量    |
+| `.hl-function`     | `--aithe-code-function`     | `#4078f2` | 函数名          |
+| `.hl-type`         | `--aithe-code-type`         | `#c18401` | 类型名          |
+| `.hl-preprocessor` | `--aithe-code-preprocessor` | `#a626a4` | 预处理指令      |
+| `.hl-key`          | `--aithe-code-key`          | `#e45649` | JSON/YAML 键    |
+| `.hl-tag`          | `--aithe-code-tag`          | `#e45649` | XML/HTML 标签   |
+| `.hl-attr`         | `--aithe-code-attr`         | `#986801` | XML/HTML 属性   |
+| `.hl-comment`      | `--aithe-code-comment`      | `#94a3b8` | 注释            |
+| `.hl-doctype`      | `--aithe-code-doctype`      | `#94a3b8` | DOCTYPE 声明    |
+| `.hl-entity`       | `--aithe-code-entity`       | `#986801` | HTML 实体       |
+| `.hl-punctuation`  | `--aithe-code-punctuation`  | `#383a42` | 标点符号        |
+| `.hl-placeholder`  | `--aithe-code-placeholder`  | `#94a3b8` | 占位符文本      |
+
+这些 CSS 变量由每个 Aithe 主题自动设置，也可通过 CSS 变量覆盖自定义颜色：
+
+```css
+:root {
+  --aithe-code-keyword: #c678dd;
+  --aithe-code-string: #98c379;
+  --aithe-code-comment: #5c6370;
+}
+```
+
+---
+
+## 自定义语言注册
+
+### 注册新语言
+
+```typescript
+import { SyntaxRegistry } from '@aithe/aithe-ui';
+
+SyntaxRegistry.register({
+  langId: 'python',
+  name: 'Python',
+  rules: [
+    // 注释（优先级最高）
+    { pattern: /(#.*$)/gm, className: 'hl-comment', order: 1 },
+
+    // 关键字
+    {
+      pattern:
+        /\b(def|class|return|if|elif|else|for|while|import|from|as|try|except|finally|with|yield|lambda|pass|break|continue|raise|and|or|not|in|is|None|True|False)\b/g,
+      className: 'hl-keyword',
+      order: 2,
+    },
+
+    // 内置函数
+    {
+      pattern: /\b(print|len|range|type|int|str|list|dict|set|tuple|open|super|self|cls)\b/g,
+      className: 'hl-builtin',
+      order: 3,
+    },
+
+    // 数字
+    { pattern: /\b(\d+\.?\d*)\b/g, className: 'hl-number', order: 4 },
+
+    // 字符串
+    { pattern: /("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')/g, className: 'hl-string', order: 5 },
+
+    // 函数调用
+    { pattern: /\b([a-zA-Z_][a-zA-Z0-9_]*)\s*(?=\()/g, className: 'hl-function', order: 6 },
+
+    // 标点符号
+    { pattern: /([{}[\](),:])/g, className: 'hl-punctuation', order: 7 },
+  ],
+});
+```
+
+### 规则编写指南
+
+1. **使用全局标志**：所有 `pattern` 应使用 `/g` 全局标志（或 `/gm` 多行全局），否则只匹配第一个结果
+2. **优先级控制**：通过 `order` 控制匹配优先级。数值越小优先级越高。注释（`order: 1`）应在关键字（`order: 2`）之前匹配
+3. **范围合并**：引擎自动合并重叠范围，高优先级的匹配会覆盖低优先级的
+4. **捕获组**：规则应使用捕获组 `()` 包裹需要高亮的文本部分
+
+### 注销语言
+
+```typescript
+// 注销内置语言
+SyntaxRegistry.unregister('yaml');
+
+// 检查是否已注册
+if (SyntaxRegistry.has('python')) {
+  console.log('Python is registered');
+}
+
+// 获取所有已注册语言
+const allLangs = SyntaxRegistry.getAll();
+allLangs.forEach((def) => {
+  console.log(`${def.langId}: ${def.name}`);
+});
+```
+
+### 创建独立语言文件
+
+推荐将自定义语言定义放在单独的文件中，遵循内置语言的模式：
+
+```typescript
+// lang-python.ts
+import { SyntaxRegistry, type LanguageDefinition } from '@aithe/aithe-ui';
+
+const rules = [
+  // ... 规则定义
+];
+
+const definition: LanguageDefinition = { langId: 'python', name: 'Python', rules };
+SyntaxRegistry.register(definition);
+```
+
+然后在应用入口导入：
+
+```typescript
+import './lang-python';
+// 或批量导入
+import './lang-rust';
+import './lang-go';
+```
+
+---
+
+## 独立使用高亮引擎
+
+`SyntaxRegistry` 可以不依赖 `<aithe-code-editor>` 独立使用，适用于自定义代码展示场景：
+
+```typescript
+import { SyntaxRegistry } from '@aithe/aithe-ui';
+
+const code = `function greet(name) {\n  return "Hello, " + name;\n}`;
+
+// 按语言高亮
+const html = SyntaxRegistry.highlightByLanguage(code, 'javascript');
+// 输出: <span class="hl-keyword">function</span> ...
+
+// 使用自定义规则高亮
+const customRules = [{ pattern: /(TODO|FIXME)/g, className: 'hl-comment', order: 1 }];
+const customHtml = SyntaxRegistry.highlightCode(code, customRules);
+
+// HTML 转义
+const escaped = SyntaxRegistry.escapeHtml('<script>alert("xss")</script>');
+// 输出: &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;
+```
+
+---
+
+## 与 code-editor 组件集成
+
+`<aithe-code-editor>` 组件内部使用 `SyntaxRegistry` 实现语法高亮，通过"分层编辑"技术实现：
+
+1. **高亮层**（`.highlight-layer`）：渲染 `SyntaxRegistry` 输出的带 `<span>` 的 HTML
+2. **输入层**（`<textarea>`）：透明覆盖在高亮层之上，处理用户输入
+
+两者通过 CSS Grid 叠加，实现"所见即所得"的语法高亮编辑体验。
+
+```html
+<!-- 基础用法 -->
+<aithe-code-editor language="javascript" value="console.log('hello');"></aithe-code-editor>
+
+<!-- 带工具栏 -->
+<aithe-code-editor language="typescript" show-toolbar></aithe-code-editor>
+
+<!-- 只读展示 -->
+<aithe-code-editor language="json" readonly show-toolbar></aithe-code-editor>
+```
+
+> 完整的 `<aithe-code-editor>` 组件文档见 [code-editor.md](api/display/code-editor.md)。
+
+---
+
+## 颜色主题定制
+
+每个 Aithe 主题自动设置 `--aithe-code-*` 系列 CSS 变量。如需自定义代码高亮颜色，覆盖这些变量即可：
+
+```css
+/* 全局覆盖 */
+:root {
+  --aithe-code-keyword: #c678dd;
+  --aithe-code-string: #98c379;
+  --aithe-code-number: #d19a66;
+  --aithe-code-function: #61afef;
+  --aithe-code-comment: #5c6370;
+  --aithe-code-builtin: #e5c07b;
+  --aithe-code-type: #e5c07b;
+  --aithe-code-tag: #e06c75;
+  --aithe-code-attr: #d19a66;
+  --aithe-code-punctuation: #abb2bf;
+}
+
+/* 单个编辑器覆盖 */
+aithe-code-editor {
+  --aithe-code-keyword: #ff79c6;
+  --aithe-code-string: #f1fa8c;
+}
+```
+
+---
+
+## 性能说明
+
+- 引擎使用正则表达式逐规则匹配，对于大文件（>1000 行）建议使用 `readonly` 模式
+- 规则数量影响匹配性能，建议每个语言控制在 10-15 条规则以内
+- 引擎在每次 `value` 变化时重新渲染高亮层，高频输入场景下自动节流