待弃用 API

Vue 3 渲染 | 首页

核心解析 API 是稳定的。下面列的是一些正在过渡的工具函数和环境状态 API。 其中大部分仍然从包主入口导出；withCreateId 则只作为兼容辅助存在于深路径模块里，并不从 root 入口导出。

---

一句话总结

旧代码用模块级隐式状态（withSyntax、withCreateId 等），新代码用 DslContext + ParseOptions 显式传参。另外有几个冗余的 handler 工厂也被更通用的替代了。

旧方式（隐式状态）                   新方式（显式传参）
┌──────────────────────┐          ┌──────────────────────┐
│ withSyntax(syntax,   │    →     │ createParser({        │
│   () => parse(...))  │          │   syntax, handlers    │
│                      │          │ })                    │
│ resetTokenIdSeed()   │    →     │ createId:             │
│                      │          │   createEasyStableId()│
└──────────────────────┘          └──────────────────────┘

---

时间线

2026 年 9 月之前不会移除。 NODE_ENV=production 时警告被抑制。

---

已弃用列表

已弃用	root 入口导出？	用这个替代	会发警告？	为什么弃用
withSyntax	是	DslContext / createParser({ syntax })	是	模块级隐式状态
getSyntax	是	DslContext	是	同上
withTagNameConfig	是	ParseOptions.tagName	是	同上
withCreateId	否	DslContext	是	同上；仅深路径兼容
resetTokenIdSeed	是	DslContext.createId	是	模块级 ID 计数器
createPipeBlockHandlers	是	createPipeHandlers + block	否	冗余
createPipeRawHandlers	是	createPipeHandlers + raw	否	冗余
createPassthroughTags	是	标准空对象 handlers 写法 / 在应用侧维护本地 helper	否	不再推荐把隐式 fallback 包装成库级 helper
ParseOptions.mode	不适用	直接删掉	否	只有一个值

说明： 这里的“已弃用”说的是兼容层语义，不代表它们都还能从 import {...} from "yume-dsl-rich-text" 取到。 当前主入口仍导出的兼容 API 是：withSyntax、getSyntax、withTagNameConfig、resetTokenIdSeed、 createPipeBlockHandlers、createPipeRawHandlers、createPassthroughTags。 withCreateId 仍存在于实现里并会发弃用警告，但它不是 root 入口公开导出。

---

迁移示例

withSyntax → createParser

// 之前
withSyntax(customSyntax, () => {
    const tokens = parseRichText("...", {handlers});
});

// 之后
const dsl = createParser({syntax: createSyntax(customOverrides), handlers});
const tokens = dsl.parse("...");

resetTokenIdSeed → createEasyStableId

// 之前
resetTokenIdSeed();
const tokens = parseRichText("...", {handlers});

// 之后
const dsl = createParser({handlers, createId: createEasyStableId()});
const tokens = dsl.parse("...");

createPipeBlockHandlers → createPipeHandlers

// 之前
const handlers = createPipeBlockHandlers(["info", "warning"]);

// 之后
const handlers = createPipeHandlers({
    info: {
        block: (args, content, ctx, rawArg) => ({
            type: "info",
            arg: rawArg,
            args: args.parts.map((_, i) => args.text(i)),
            value: content,
        }),
    },
    warning: {
        block: (args, content, ctx, rawArg) => ({
            type: "warning",
            arg: rawArg,
            args: args.parts.map((_, i) => args.text(i)),
            value: content,
        }),
    },
});

createPassthroughTags → 标准空对象 handlers 写法 / 本地 helper

// 之前
const handlers = createPassthroughTags(["bold", "italic"]);

// 之后
const handlers = {
    bold: {},
    italic: {},
};

createPassthroughTags 的真实语义不是“创建一组 simple inline handler”，而是批量注册空 handler，把最终产物交给解析器内部的默认 materialization / fallback 逻辑处理。

所以它和 createSimpleInlineHandlers 并不等价：

• createSimpleInlineHandlers 会显式提供 inline handler，固定产出 {type, value}
• createPassthroughTags 依赖的是隐式 fallback

如果你的旧代码就是想继续保留这种隐式 fallback，推荐做法不是换成另一个库内 helper，而是直接手写这些空 handler：

const handlers = {
    bold: {},
    italic: {},
};

这不是“临时替代写法”，而是推荐的标准隐式写法：一种几乎零成本的声明语法，只表达“这个标签名存在，后续交给默认 materialization / fallback 处理”。

它的实际行为是：

• bold: {} 这类空对象 handler 会让 inline form 走默认输出：{ type: tagName, value: materializedChildren }
• 它不会自动声明 raw / block form；没有 raw / block 方法时，这两种 form 仍然会降级回源码文本
• 如果同名标签要同时支持 inline 和 raw/block，请显式写出对应方法，不要指望空对象 fallback 自动补齐多形态

换句话说，待弃用的是 createPassthroughTags 这个 helper，不是空对象 handler 这种写法本身。

如果你更喜欢数组转对象的组织方式，也可以在业务侧维护一个很小的本地 helper；但库文档现在默认把上面的空对象写法视为标准用法。