ParseOptions 选项

处理器辅助函数 | Token 结构

调用 parseRichText、createParser、parseStructural 时传的那个配置对象。 选项虽然多，但大部分有默认值，日常只需要 handlers 一个就能跑。

---

选项全景图

                        ParseOptions
                            │
         ┌──────────────────┼──────────────────┐
         ▼                  ▼                  ▼
   ParserBaseOptions    ParseOptions 独有    StructuralParseOptions 独有
   （共享基类）         （parseRichText 用）  （parseStructural 用）
         │                  │                  │
    ┌────┼────┐        ┌────┼────┐          只有一个:
    │    │    │        │    │    │          trackPositions
    ▼    ▼    ▼        ▼    ▼    ▼
handlers  syntax  ...  createId  blockTags  ...
depthLimit tagName     onError   mode(弃用)
allowForms             trackPositions
implicitInlineShorthand
baseOffset
tracker

日常够用的选项

选项	一句话	默认值
handlers	标签名 → handler 映射，必须有	{}
onError	解析出错时的回调，不传就静默忽略	不报错
trackPositions	要不要给每个 token 打上源码坐标	false

安全/限制相关

选项	一句话	默认值
allowForms	全局限制哪些标签形式（inline/raw/block）可用	全部启用
implicitInlineShorthand	控制 inline 参数中的 name(...) 简写。1.3 起	false
depthLimit	嵌套深度上限，防栈溢出	50

自定义语法

选项	一句话	默认值
syntax	换掉 $$、(、)$$ 等语法符号	默认 $$tag(...)$$ 系列
tagName	控制标签名允许哪些字符	字母+下划线+连字符

子串解析

选项	一句话	默认值
baseOffset	切片在原文中的起始偏移	0
tracker	从原文建好的行表，配合 baseOffset 用	无

仅 parseRichText

选项	一句话	默认值
createId	自定义 token ID 生成方式	顺序计数器 rt-0, rt-1, ...
blockTags	声明哪些标签做换行规范化（一般自动推导）	从 handlers 推导

---

详细说明

handlers

handlers ? : Record<string, TagHandler>

标签名到 handler 的映射。不在 handlers 里的标签不会报错——直接把语法当成普通文本输出（优雅降级）。

用 处理器辅助函数 批量注册可以省很多样板代码。

allowForms

allowForms ? : readonly("inline" | "raw" | "block")[]

全局限制解析器接受哪些标签形式。不在列表里的形式会被降级成字面文本。

// UGC 场景：只允许 inline，block/raw 太危险
parseRichText(input, {handlers, allowForms: ["inline"]});

implicitInlineShorthand

1.3 起

implicitInlineShorthand ? : boolean | readonly
string[]

控制 inline 参数区内的隐式简写（name(...)）。启用后，解析器在已有 inline 参数区内识别 tagName( 作为 inline 标签开头——无需 $$ 前缀。

• false（默认）：关闭——仅识别完整 $$tag(...)$$ 语法。
• true：对所有已注册且支持 inline form 的标签启用。
• string[]：仅对白名单中的标签启用。

// 对所有支持 inline 的标签启用
parseRichText("$$bold(Hello italic(world))$$", {
    handlers, implicitInlineShorthand: true,
});

// 仅对特定标签启用
parseRichText("$$bold(Hello italic(world))$$", {
    handlers, implicitInlineShorthand: ["italic"],
});

解析优先级： 完整 DSL 结构（$$tag(...)$$、raw、block）始终优先匹配。仅当无完整结构匹配时才尝试简写。 简写参数中的字面括号需要用 \) / \( 转义。

depthLimit

depthLimit ? : number  // 默认 50

递归嵌套上限。超过时报 DEPTH_LIMIT 错误，标签降级为字面文本。防止恶意输入把栈打爆。

syntax

syntax ? : Partial<SyntaxInput>

覆盖 DSL 语法符号。只传你要改的，其余保持默认。详见 自定义语法。

interface SyntaxInput {
    tagPrefix: string;    // 默认: "$$"
    tagOpen: string;      // 默认: "("
    tagClose: string;     // 默认: ")$$"
    tagDivider: string;   // 默认: "|"
    endTag: string;       // 默认: "end$$"
    rawOpen: string;      // 默认: ")%"
    blockOpen: string;    // 默认: ")*"
    blockClose: string;   // 默认: "*end$$"
    rawClose: string;     // 默认: "%end$$"
    escapeChar: string;   // 默认: "\\"
}

tagName

tagName ? : Partial<TagNameConfig>

控制标签名字符。详见 自定义标签名字符。

interface TagNameConfig {
    isTagStartChar: (char: string) => boolean;  // 标签名开头能是啥
    isTagChar: (char: string) => boolean;        // 标签名里能出现啥
}

baseOffset / tracker

解析子字符串时使用。baseOffset 移动 offset，配合 tracker 一起传才能得到完全正确的 line/column。详见 源码位置追踪。

createId

createId ? : (token: TokenDraft) => string

自定义 token ID 生成。默认是顺序计数器 rt-0, rt-1, ...。 想要基于内容的稳定 ID（编辑周围文本不会变），用 createEasyStableId()。详见 稳定 Token ID。

blockTags

blockTags ? : readonly
BlockTagInput[]

声明哪些标签做首尾换行规范化，防止渲染时出现多余空行。

• raw / block：剥掉多行标签内容开头和结尾各一个边界换行
• inline：剥掉 inline close $$ 后紧跟的 \n——适用于用 inline 语法但渲染为块级元素的标签

一般省略——解析器从 handlers 自动推导 raw/block 规范化。传 blockTags 时，覆盖是按标签的 ：你列出的标签完全替换该标签的自动推导，没列出的标签保留自动推导。inline 规范化不会自动推导 ，必须显式声明。传字符串表示三种形式全部规范化（raw + block + inline），传 { tag, forms } 可精细控制。

详见 处理器辅助函数 中 declareMultilineTags 的完整说明。

onError

onError ? : (error: ParseError) => void

解析出错时调用。不传就静默丢弃——解析器照样尽力输出。

interface ParseError {
    code: ErrorCode;
    message: string;
    line: number;
    column: number;
    snippet: string;
}

详见 错误处理。

trackPositions

trackPositions ? : boolean  // 默认 false

开了之后每个 token 会多一个 position 属性。性能开销几乎为零。详见 源码位置追踪。

mode（已弃用）

mode ? : "render"

唯一值 "render"，向后兼容用。新代码不要传。

---

StructuralParseOptions

parseStructural 用的选项，继承 ParserBaseOptions，额外只有 trackPositions。

不包含 createId、blockTags、onError、mode——结构化解析器不分配 ID、不做换行规范化、不需要注册 handler。