Cherry Markdown 编辑器 TOC 和锚点问题的解决方案

在基于 Cherry Markdown 编辑器开发文章发布系统时，开发者经常会遇到两个典型问题：目录(TOC)定位异常和锚点失效。本文将深入分析问题成因并提供专业解决方案。

问题现象分析

TOC 定位异常

当编辑器容器不是直接挂载在 body 元素下时，预览模式下 TOC 会出现以下异常：

1. TOC 无法固定在右侧中间位置
2. 页面滚动时 TOC 会被顶出可视区域
3. 在 Vue 等框架的组件化开发中尤为常见

锚点失效问题

在 Vue 的 hash 路由模式下，URL 已包含 # 符号时：

1. 锚点链接会生成错误的 URL 结构
2. 点击锚点后页面可能变为空白
3. 无法正确滚动到目标位置

技术原理剖析

滚动容器机制

Cherry Markdown 默认的滚动行为依赖于：

1. 编辑器容器需要有明确的高度设置
2. 滚动事件监听绑定在编辑器内部
3. TOC 位置计算基于容器相对位置

路由冲突原理

Vue hash 路由模式下：

1. 基础 URL 已包含 # 符号
2. 锚点生成的 # 会与路由 # 冲突
3. 浏览器无法正确解析复合 hash

专业解决方案

容器高度配置方案

推荐以下两种配置方式：

1. 固定高度模式

const cherryInstance = new CherryMarkdown({
  element: '#editor',
  value: content,
  editor: {
    height: '800px' // 明确设置固定高度
  }
});

特点：

• 内部滚动条独立
• TOC 定位准确
• 适合嵌入复杂布局

2. 百分比高度模式

const cherryInstance = new CherryMarkdown({
  element: '#editor',
  value: content,
  editor: {
    height: '100%' // 使用百分比高度
  }
});

特点：

• 适合全屏布局
• 需要配合外层容器高度设置

路由适配方案

1. 关闭 hash 更新

const cherryInstance = new CherryMarkdown({
  toolbars: {
    toc: {
      updateLocationHash: false // 禁用hash更新
    }
  }
});

2. 自定义滚动逻辑

document.querySelector('.container').addEventListener('scroll', () => {
  // 自定义实现滚动位置同步
});

最新增强方案

Cherry Markdown 最新版本增加了针对预览模式的专用配置：

const cherryInstance = new CherryMarkdown({
  toolbars: {
    toc: {
      float: {
        enable: true, // 启用浮动定位
        position: 'right' // 右侧定位
      },
      scrollContainer: document.body // 指定滚动容器
    }
  }
});

关键改进点：

1. 支持外部容器滚动监听
2. 智能位置计算算法
3. 与框架路由解耦

最佳实践建议

1. 对于文章发布系统：

• 使用预览专用模式
• 配置外部容器滚动
• 保持100%高度布局

2. 对于复杂SPA应用：

• 明确设置编辑器高度
• 自定义TOC容器
• 处理路由冲突

3. 性能优化建议：

• 防抖处理滚动事件
• 虚拟化长文档TOC
• 延迟加载锚点目标

总结

Cherry Markdown 编辑器通过灵活的配置选项和持续的迭代更新，已经能够很好地解决各种复杂场景下的 TOC 和锚点问题。开发者可以根据实际项目需求选择合适的解决方案，必要时结合自定义逻辑实现最佳用户体验。