Cherry-Markdown API 使用指南：从基础操作到高级功能

项目概述

Cherry-Markdown 是一款功能强大的 Markdown 编辑器，提供了丰富的 API 接口，让开发者能够灵活地控制和扩展编辑器的功能。本文将详细介绍 Cherry-Markdown 的核心 API 及其使用方法，帮助开发者快速上手并充分利用其功能。

基础 API 详解

内容操作 API

1. setMarkdown(val: string)

   • 功能：设置编辑器内容
   • 示例：editor.setMarkdown('# 标题\n\n这是内容')
   • 应用场景：初始化编辑器内容或重置编辑器状态

2. getMarkdown()

   • 功能：获取当前 Markdown 内容
   • 返回值：字符串形式的 Markdown 文本
   • 应用场景：保存用户输入或进行内容分析

3. getHtml()

   • 功能：获取渲染后的 HTML 内容
   • 返回值：字符串形式的 HTML
   • 应用场景：预览或导出为 HTML 格式

编辑器控制 API

1. switchModel(model: string)

   • 功能：切换编辑器模式
   • 可选值：
     • 'edit&preview'：编辑和预览模式（默认）
     • 'editOnly'：仅编辑模式
     • 'previewOnly'：仅预览模式
   • 应用场景：根据用户需求调整编辑界面

2. getToc()

   • 功能：获取由标题组成的目录结构
   • 返回值：标题层级结构数据
   • 应用场景：生成文档导航或目录

高级功能 API

内容插入 API

insert(content: string, isSelect?: boolean, anchor?: [number, number], focus?: boolean)

• 功能：在指定位置插入内容
• 参数详解：
  • content：要插入的文本内容
  • isSelect：是否选中刚插入的内容（默认 false）
  • anchor：插入位置的坐标 [行号, 字符偏移量]
  • focus：是否保持编辑器焦点状态（默认 true）
• 示例：editor.insert('**加粗文本**', true)

实例获取 API

1. getCodeMirror()

   • 功能：获取底层 CodeMirror 编辑器实例
   • 应用场景：需要直接操作底层编辑器时

2. getPreviewer()

   • 功能：获取预览区对象实例
   • 应用场景：自定义预览区域行为

引擎 API (Cherry.engine)

1. engine.makeHtml(markdown: string)

   • 功能：将 Markdown 转换为 HTML
   • 应用场景：服务器端渲染或独立转换场景

2. engine.makeMarkdown(html: string)

   • 功能：将 HTML 转换为 Markdown
   • 应用场景：内容导入或格式转换

工具栏处理 API (Cherry.toolbar.toolbarHandlers)

基础格式操作

1. bold()：插入加粗语法 **文本**
2. italic()：插入斜体语法 *文本*
3. header(level: number)：插入标题语法（1-6级）
4. strikethrough()：插入删除线语法 ~~文本~~

列表操作

list(type: string)

• 功能：插入列表
• 参数：
  • '1'：有序列表
  • '2'：无序列表
  • '3'：检查清单

复杂元素插入

insert(type: string)

• 功能：插入特定类型元素
• 支持类型：
  • 'hr'：水平线
  • 'code'：代码块
  • 'formula'：数学公式
  • 'toc'：目录
  • 各类媒体：图片、视频、音频等
  • 表格：支持自定义行列

图表绘制

graph(type: string)

• 功能：插入各类图表语法
• 支持图表类型：
  • '1'：流程图
  • '2'：时序图
  • '3'：状态图
  • '4'：类图
  • '5'：饼图
  • '6'：甘特图

最佳实践建议

1. 内容初始化：使用 setMarkdown() 初始化内容比直接操作 DOM 更可靠
2. 模式切换：在移动设备上考虑使用 switchModel('editOnly') 以获得更好的编辑体验
3. 自定义工具栏：通过调用 toolbarHandlers 的方法可以实现完全自定义的工具栏
4. 内容转换：利用 engine API 可以实现前后端统一的内容渲染

总结

Cherry-Markdown 提供了从基础内容操作到高级功能插入的完整 API 体系。通过合理使用这些 API，开发者可以构建功能丰富、用户体验优秀的 Markdown 编辑环境。无论是简单的文本编辑还是复杂的图表插入，Cherry-Markdown 都能提供强大的支持。