守护规则编辑器

说明: 此软件包开发于 辅助软件。 。 。 . 这个 守护小组/规则编辑器 寄存器是一个公共镜像.

一个基于浏览器的库,用于编辑并标出AdGuard过滤规则. 它提供了一个 代码 6 用文本Mate语法突出显示的文本编辑器 (通过Web Assembly Oniguruma, 由 vscode-textmate + 键 vscode-oniguruma(中文(简体) ) 以及用于自定义规则渲染的WASM后置符号.

目录

• 安装
• 关键概念
• 快速启动
  • 编辑器
    • 他们
    • 突出战略
    • 多曲线编辑
  • 执行规则
  • 检查一行( 镜像调试)
• API 密码
  • initEditor
    • 热键
  • getTokenizer
  • inspectLine
  • 将符号渲染到 HTML( 只播放)
    • renderTokensToHtml
    • getHtmlRenderer
    • mountHighlightStyle
    • RenderOptions
  • 错误分类
• 同伴依赖关系
• 文档

安装

vscode-oniguruma 和 CodeMirror/Lezer 软件包是同行依赖关系 您的工程必须单独安装 . vscode-oniguruma 需要时间 因此, WASM 二进制可以在您的捆绑中可用; CodeMiror 包 因为库返回一个活字 EditorView 举个例子. 密码 @codemirror/state 依赖 instanceof 检查 扩展和侧面——如果您的捆绑器重复 @codemirror/state (库包一个副本,你的应用程序另一个) 这些支票会 失败。 将对等分页外部化可确保一个共享副本.

pnpm add @adguard/rules-editor vscode-oniguruma @codemirror/state \
    @codemirror/view @codemirror/language @codemirror/commands \
    @codemirror/search @lezer/highlight

关键概念

• 编辑器 代码Mirror 6 实例,其格格语法突出 (嵌入式JavaScript区域的范围为 source.js 但使用最小值 占位符语法,以保持捆绑小块,由基于WASM的动力驱动 来自 Oniguruma regex 的 vscode-oniguruma。 。 。 .
• 切换器 使用 WASM 将一条规则分解为突出的段; 最高精确度.
• 脚本 与编码Mirror 6相一致的符号类型 @lezer/highlight 标记分类学( t)keyword, (中文(简体) ), operator, (中文(简体) ), string, (中文(简体) ), comment, (中文(简体) ), regexp(见a/c.5/49/70,附件).
• 检查行 ——返回带有完整文本Mate范围的每个托肯段 用于调试和测试的堆栈.

快速启动

编辑器

import { initEditor } from '@adguard/rules-editor';

// Let your bundler (rspack / Vite) emit the asset and compute the URL.
const wasm = new URL('vscode-oniguruma/release/onig.wasm', import.meta.url);

const textarea = document.getElementById('textarea');
const view = await initEditor(textarea, wasm, {
    hotkeys: { mode: 'mac' },
});
view.dispatch({ changes: { from: 0, insert: '||example.org^' } });

他们

用标准突出显示托肯 @lezer/highlight 标签,所以任何 CodeMirror 6主题工作出盒. 默认应用编辑器 密码 defaultHighlightStyle; 通过自己的主题(或 HighlightStyle)通过 conf.extensions 以覆盖它 :

import { oneDark } from '@codemirror/theme-one-dark';

const view = await initEditor(textarea, wasm, {
    hotkeys: { mode: 'mac' },
    extensions: [oneDark],
});

initEditor 总是添加 CodeMiror 代码 drawSelection() 扩展,所以护身符 选择由 CodeMirror 绘制,而不是由浏览器绘制: 本地 ::selection 和护身符样式不适用,不应添加 drawSelection() 你自己来 多曲线编辑可被关闭 withMultipleSelections: false,该选项将禁用额外选择区域,同时 留下画的原样.

突出战略

默认情况下,编辑器使用由 Oniguruma 支持的全文本Mate 突出显示 温。 不需要语法加亮时,请选择 highlight: 'none' - 它从不装载WASM,所以 wasm 参数可以是 undefined数字 :

// No highlighting at all, no WASM:
const plain = await initEditor(textarea, undefined, {
    hotkeys: { mode: 'mac' },
    highlight: 'none',
});

initEditor 仍然返回 a Promise<EditorView> 每一个策略,所以 现有 await initEditor(...) 电话站点不受影响.

多曲线编辑

编辑器支持同时编辑多行. 别动 Ctrl (温道/灵通 或者说 Cmd (macOS)并单击您想要编辑的每行:每点击一次都添加一个 二次光标,并在所有光标上插入相同的文字。 单人 Ctrl+Z 编号 : Cmd+Z 返回整个多行编辑。 拥有修改器和 单击一个已存在的二级光标去除; 一个平滑点击倒塌 转到一个光标.

设定 withMultipleSelections: false 切换多曲线编辑; 不 它不能将编辑器调回单选模式 conf.extensions,因为 EditorState.allowMultipleSelections 组合其 数值为 some。关闭它也会将键盘命令留在下面 因此,他们的和弦 掉进CodeMirror自己的钥匙图和 浏览器.

键盘上有相同的命令, 绑定前一个 使用了基于王牌的编辑器. 阿斯会把他们绑起来 Ctrl+Alt 在每一个平台上,和在 macOS 这个库也一样 Cmd+Alt 故意不在那里使用, 因为Chrome和Firefox拦截 Cmd+Option+Left/Right 前一个/下一个 选项卡,因此这些快捷键永远不会到达编辑器:

• Ctrl+Alt+Up 编号 : Ctrl+Alt+Down 在上行/下行增加光标;
• Ctrl+Alt+Shift+Up 编号 : Ctrl+Alt+Shift+Down ——上下移动上一光标 而不是添加一个; 仅用一个光标, 第一种媒体会添加一个, 如 甲;
• Ctrl+Alt+Right 编号 : Ctrl+Alt+Left —— 添加下一次/以往发生的 选择;
• Ctrl+Alt+Shift+Right 编号 : Ctrl+Alt+Shift+Left ——将主光标移动到 下一个/ 上一个事件,而不是添加一个;
• Esc ——倒塌回单光标.

横跨多行的选定区域被行命令所移动,而不是 正在复制: 副本将重复原件, 代码Mirror 将合并 两人进入一个更长的选择。 当移动将离开文件 命令下降,选择保留原样——尽管在Windows和 Linux 和弦随即跳入 CodeMiror 的自有添加- cursor 命令 绑入相同的密钥,仍然可以添加光标.

使用空光标, 发生快捷键选择光标下的单词 首先,当光标本身不是时,搜索扩展至相邻的单词 在单词字符上,它选择 example.com 编辑 ^ 联 合 国 ||example.com^。字母、数字和组合标记与 Unicode 匹配 属性逃脱,所以非 ASCII 域也被选中.

Ctrl+/ 编号 : Cmd+/ 注释(或注释),每个光标下行和 切换每行规则状态翻转的启用规则标记. 评论一条规则来切换它的标记 而不评论规则来切换它 因此,规则保持了它的允许状态 超过一个评论和不评论 循环。 因此,一个被禁用的规则在成为评论时会获得标记. Ctrl+S 编号 : Cmd+S 触发 onSave 处理者.

这个 toggleRule callback 还会为只选择一个注释的选项点火,该选项 切换回到规则。 混合选择的注释行会否 标记。 保留注释的行( :! ! note其标记不变, 当行变为空 (!失去任何标记,因为 空行无法持有 。 空行被跳过, 但只有空白 线条不是空的,仍然有标记.

在 Linux 桌面上 Ctrl+Alt+Arrow 通常被窗口管理器抓取 用于工作空间切换, 因此这些密钥永远不会到达那里的浏览器; 鼠标 手势和其余快捷键不受影响.

执行规则

import { getTokenizer } from '@adguard/rules-editor';

// WASM-based (async init, highest precision)
const wasm = new URL('vscode-oniguruma/release/onig.wasm', import.meta.url);
const tokenize = await getTokenizer(wasm);
const tokens = tokenize('||example.org^$important');

检查一行( 镜像调试)

import { inspectLine } from '@adguard/rules-editor';

const wasm = new URL('vscode-oniguruma/release/onig.wasm', import.meta.url);
const segments = await inspectLine(wasm, '||example.org^$important');
// segments: TokenSegment[] — each with text, startIndex, endIndex,
//            scopes (full TextMate scope stack), and token (resolved class)

API 密码

initEditor

async function initEditor(
    element: HTMLTextAreaElement,
    wasm: WasmSource,
    conf: InitEditorConfig,
): Promise<EditorView>

A 类 WasmSource 是 URL/ 字符串( 在运行时比较) , Response, (中文(简体) ), ArrayBuffer,或一个 Promise解决其中任何问题.

回返a CodeMirror.EditorView 举个例子 参见代码Miror 6文件 事件 财务报告和审定财务报表 键盘图。 。 。 .

热键

默认情况下,编辑器一创建就集中(通过) conf.autofocus: false 选择退出,例如当主机页面挂载多个 编辑,所以编辑热键 立即工作. Ctrl 意思是Windows/Linux, 意思是 Windows/Linux, Cmd 指macOS — CodeMirror 从用户平台解决修改器 自动, 所以下面的绑定忽略 conf.hotkeys.mode (选项) 只选择多曲线和弦的修饰符 — 见多曲线 页:1 搜索面板由编辑器底端提供 默认; 通过自己的 search({ top: true }) 结束 conf.extensions 改为 改变这一点。 面板的按钮和标签不能选择为文本 — a 双击或拖动它们不选择任何内容——而输入字段保留 浏览器的文本选择,所以仍然可以选择一个查询并复制. 在编辑器中打开的每个 CodeMirror 对话框都一样 上行对话框和一个消费者打开的对话框 showDialog 包括: 其形式控制input, (中文(简体) ), textarea, (中文(简体) ), select保持可选,他们的 其他内容没有。 规则是一个基础主题,所以它坐落在消费者之下 主题 —— 添加自己的主题来覆盖它 —— 和每一个基础主题一样,它 不限于此编辑器: 也适用于其他 CodeMiror 6 编辑器 在同一页.

• Ctrl+F 编号 : Cmd+F 打开搜索面板
• Ctrl+H 打开以替换字段为焦点的搜索面板 ("find & 取代";仅在Windows/Linux上——在macOS上) Cmd+H 保留 由OS/浏览器,所以 Cmd+Alt+F 是“ 查找并替换” 快捷键
• Ctrl+Alt+F 编号 : Cmd+Alt+F 在 在每个平台替换字段( 查找并替换)
• F3 或者说 Ctrl+G 找到下一个匹配; Shift+F3 或者说 Ctrl+Shift+G 找到上一个(在macOS上: Cmd+G 编号 : Cmd+Shift+G) (中文(简体) ). 打开 Windows/Linux 前一个编辑器的 Ctrl+K 编号 : Ctrl+Shift+K 和弦工作 和;在macOS上 Ctrl+K 保留其“ 删除到行尾”默认值
• Escape 关闭搜索面板
• Ctrl+Alt+G 编号 : Cmd+Alt+G 将光标移动到带有给定数字的行上 ("去行");上个编辑 Ctrl+L 编号 : Cmd+L 还有工作
• Alt+Up 编号 : Alt+Down 上下移动所选行
• Shift+Alt+Up 编号 : Shift+Alt+Down 复制上下所选行 (单位:千美元)Cmd+Option+Up 编号 : Cmd+Option+Down 在macOS上,如上一个编辑器)
• Ctrl+D 编号 : Cmd+D 删除当前行或选择
• Ctrl+S 编号 : Cmd+S 触发 conf.hotkeys.onSave 回调
• Ctrl+/ 编号 : Cmd+/ 切换 !编号 :# 关于选定行和 在规则状态翻转的每行上设置规则标记,所以规则保留 整个注释周期和不注释周期的启用状态

说明: 从上一个(基于王牌)编辑器恢复的和弦是 在 CodeMirror 默认之前已注册,因此在双方绑定 同键: MacOS 复制行和弦 Cmd+Option+Arrow 替换“添加” 以上/以下光标,“, Ctrl+D 编号 : Cmd+D 替换“ 选择下一个 ” 发生“ 有“ 删除行” , 在 Windows/ Linux 上 Ctrl+Shift+K 将"删除行"替换为"查找上行". "选择所有事件" (单位:千美元)Ctrl+Shift+L 编号 : Cmd+Shift+L)作为 CodeMirror 约束它——它的行为 上,未选择文本.

类似搜索绑定Ctrl+F, (中文(简体) ), F3, (中文(简体) ), Ctrl+G, (中文(简体) ), Escape页:1 查找并替换、保存和注释切换快捷键,在焦点时也会工作 正在打开搜索面板.

内置密钥映射在注册之前 conf.extensions捍卫者 绑定( 行操作, 多曲线, 查找并替换, 保存, 和注释) 切换)运行于 Prec.high,在同等优先的情况下,先前的扩展 赢了,所以 Prec.high 绑定通过 conf.extensions 无法阴影 它们——首先查阅内置装订。 股票代码密钥映射 (单位:千美元)defaultKeymap, (中文(简体) ), historyKeymap, (中文(简体) ), searchKeymap在默认情况下运行 优先级,所以 Prec.high 装入 conf.extensions 已经 影子他们.. Mod-f 从 searchKeymap 这是一个例子。 覆盖一个 还要装订 将您的键盘图的重心置于 内置 Prec.highest(...)数字 :

import { Prec } from '@codemirror/state';
import { keymap } from '@codemirror/view';

extensions: [
    // Overrides the AdGuard `Prec.high` bindings (and the stock keymaps).
    Prec.highest(keymap.of([{ key: 'Mod-s', run: mySaveCommand }])),
]

getTokenizer

async function getTokenizer(
    wasm: WasmSource,
): Promise<(rule: string) => RuleTokens>

返回接受规则字符串的函数并返回 RuleTokens (单位:千美元){ str: string, token: Token | null }[]) (中文(简体) ).

inspectLine

async function inspectLine(
    wasm: WasmSource,
    line: string,
    scopeName?: string,
): Promise<TokenSegment[]>

返回一个相接、无间隙的数组 TokenSegment 覆盖对象 输入行。 每个部分都有 text, (中文(简体) ), startIndex, (中文(简体) ), endIndex, (中文(简体) ), scopes (全范围堆放),和 token (已解决的类别或 null) (中文(简体) ).

将符号渲染到 HTML( 只播放)

对于只读视图(如规则行的虚拟列表),您可以制作一个 用于颜色化的 HTML 的符号列表, 其类匹配编辑器—— 不创建 a 每行编码编辑器。 设定 white-space: pre 在容器上到 保持间隔.

renderTokensToHtml

function renderTokensToHtml(
    tokens: RuleTokens,
    options?: RenderOptions,
): string

返回 HTML 字符串安全 innerHTML编号 :dangerouslySetInnerHTML。 。 。 .

getHtmlRenderer

async function getHtmlRenderer(
    wasm: WasmSource,
    options?: RenderOptions,
): Promise<(rule: string, search?: SearchHighlightOptions) => string>

返回一个初始化语法的合成厂,然后返回 a 同步 (rule, search?) => html 全精度函数( WASM) 在多行中突出显示可重复使用.

返回函数接受可选 search 要突出显示的参数 规则中的搜索名词 :

interface SearchHighlightOptions {
    searchTerm?: string;     // plain-text, case-insensitive
    searchClassName?: string; // CSS class on each matched chunk
}

何时 searchTerm 是一个非空字符串, 每个大小写不敏感的事件 - 包含跨多个符号的相配符 <span> 携带 searchClassName. 弃权 search (或通过空名词) 输出与平面渲染完全相同。 匹配文本和 searchClassName 已跳过 HTML.

const render = await getHtmlRenderer(wasm);
// Plain rendering — unchanged from previous versions:
const html = render('||example.org^');
// With search highlighting:
const highlighted = render('||example.org^', {
    searchTerm: 'example',
    searchClassName: 'search-hit',
});

mountHighlightStyle

function mountHighlightStyle(
    highlightStyle?: HighlightStyle,
    root?: Document | ShadowRoot,
): void

挂载 a HighlightStyleCSS 所排放的类没有颜色 编辑。 拨打一通;再拨一通为一通.

RenderOptions

interface RenderOptions {
    highlightStyle?: HighlightStyle | HighlightStyle[];
}

通过自定义 HighlightStyle (例如:. oneDarkHighlightStyle匹配 a 自定义编辑器主题 .

错误分类

同伴依赖关系

文档

• 发展
• 部署
• LLM 代理规则
• 更改日志