Milkdown项目中的HTML导出功能变更解析

背景介绍

Milkdown是一个基于ProseMirror构建的现代化WYSIWYG Markdown编辑器框架。在最近的7.9.0版本更新中，项目团队对组件系统进行了重大技术升级，将底层依赖从Atomico框架迁移到了Vue框架。这一变更虽然带来了性能和维护性上的提升，但也导致了一些API的破坏性变更，特别是@milkdown/kit/component模块中HTML导出功能的移除。

变更详情

在7.9.0版本之前，开发者可以通过import { html } from "@milkdown/kit/component"来获取一个用于创建HTML模板的函数。这个函数在自定义组件渲染时非常有用，例如在代码块语言选择器的自定义渲染场景中：

renderLanguage: (language, selected) => {
  return html`
    <li class="language-list-item" data-language="${language}">
      ${displayName} ${selected ? "✅" : ""}
    </li>
  `;
}

然而，在7.9.0版本中，这个API被移除了，导致依赖它的代码无法正常工作。项目维护者解释称，这次变更源于将Atomico框架替换为Vue框架的技术决策，因为Atomico项目已经长达一年没有更新，维护团队认为其可能已被放弃。

版本控制策略的考量

值得注意的是，这次API变更是在一个"minor"版本更新中引入的，这与传统的语义化版本控制(SemVer)规范相违背。按照SemVer规范，破坏性变更应该在主版本号(major version)更新中引入。

项目维护者对此的解释是，他们采用了类似"epoch semantic versioning"的版本控制策略。这种策略认为，在项目经历重大架构变革时（如Milkdown从v6到v7的headless编辑器框架迁移），才应该增加主版本号。而像框架替换这样的技术升级，虽然包含破坏性变更，但仍在当前主版本周期内进行。

替代方案与最佳实践

对于受此变更影响的开发者，目前有以下几种解决方案：

1. 简化渲染逻辑：如果自定义需求不复杂，可以直接返回字符串而非HTML模板：

renderLanguage: (language, selected) => {
  return `${displayName} ${selected ? "✅" : ""}`;
}

2. 使用原生DOM API：对于需要复杂HTML结构的场景，可以使用document.createElement等原生API构建DOM节点。

3. 等待功能增强：项目可能会在未来版本中为LanguageDescription添加displayName属性，从而减少自定义渲染的需求。

对开发者的建议

1. 关注变更日志：即使是非主版本更新，也应仔细阅读变更日志，了解可能的破坏性变更。

2. 考虑锁定版本：对于生产环境，考虑锁定特定版本以避免意外更新带来的兼容性问题。

3. 参与社区讨论：通过GitHub issues等渠道反馈使用体验，帮助项目改进API设计。

总结

Milkdown 7.9.0的技术升级虽然带来了短期的适配成本，但从长远看有利于项目的可持续发展。作为使用者，理解项目的版本控制哲学和技术路线，能够更好地规划升级策略。同时，这也提醒我们，在现代前端生态中，即使是minor版本更新，也可能包含需要特别注意的变更。