fix: types of external api, Engine and toolbarHandlers APIs, (#580

)

* fix:  types of external `api`, `Engine` and `toolbarHandlers` APIs,

fix: remove `insert` and `setValue` return value

* chore: correction description

src/Cherry.js

@@ -191,10 +191,8 @@ export default class Cherry extends CherryStatic {
 
   /**
    * 切换编辑模式
-   * @param {'edit&preview'|'editOnly'|'previewOnly'} model 模式类型
+   * @param {'edit&preview'|'editOnly'|'previewOnly'} [model=edit&preview] 模式类型
    * 一般纯预览模式和纯编辑模式适合在屏幕较小的终端使用，比如手机移动端
-   *
-   * @returns
    */
   switchModel(model = 'edit&preview') {
     switch (model) {
@@ -249,36 +247,44 @@ export default class Cherry extends CherryStatic {
 
   /**
    * 获取编辑区内的markdown源码内容
-   * @returns markdown源码内容
+   * @returns {string} markdown源码内容
    */
   getMarkdown() {
     return this.getValue();
   }
 
   /**
-   * 获取CodeMirror实例
-   * @returns CodeMirror实例
+   * 获取CodeMirror 实例
+   * @returns { CodeMirror.Editor } CodeMirror实例
    */
   getCodeMirror() {
     return this.editor.editor;
   }
 
   /**
    * 获取预览区内的html内容
-   * @param {boolean} wrapTheme 是否在外层包裹主题class
-   * @returns html内容
+   * @param {boolean} [wrapTheme=true] 是否在外层包裹主题class
+   * @returns {string} html内容
    */
   getHtml(wrapTheme = true) {
     return this.previewer.getValue(wrapTheme);
   }
-
+  /**
+   * 获取Previewer 预览实例
+   * @returns {Previewer} Previewer 预览实例
+   */
   getPreviewer() {
     return this.previewer;
   }
 
   /**
+   * @typedef {{
+   *  level: number;
+   * id: string;
+   * text: string;
+   * }[]} HeaderList
    * 获取目录，目录由head1~6组成
-   * @returns 标题head数组
+   * @returns {HeaderList} 标题head数组
    */
   getToc() {
     const str = this.getHtml();
@@ -296,7 +302,6 @@ export default class Cherry extends CherryStatic {
    * 覆盖编辑区的内容
    * @param {string} content markdown内容
    * @param {boolean} keepCursor 是否保持光标位置
-   * @returns
    */
   setValue(content, keepCursor = false) {
     if (keepCursor === false) {
@@ -306,10 +311,9 @@ export default class Cherry extends CherryStatic {
     const old = this.getValue();
     const pos = codemirror.getDoc().indexFromPos(codemirror.getCursor());
     const newPos = getPosBydiffs(pos, old, content);
-    const ret = codemirror.setValue(content);
+    codemirror.setValue(content);
     const cursor = codemirror.getDoc().posFromIndex(newPos);
     codemirror.setCursor(cursor);
-    return ret;
   }
 
   /**
@@ -318,15 +322,13 @@ export default class Cherry extends CherryStatic {
    * @param {boolean} [isSelect=false] 是否选中刚插入的内容
    * @param {[number, number]|false} [anchor=false] [x,y] 代表x+1行，y+1字符偏移量，默认false 会从光标处插入
    * @param {boolean} [focus=true] 保持编辑器处于focus状态
-   * @returns
    */
   insert(content, isSelect = false, anchor = false, focus = true) {
     if (anchor) {
       this.editor.editor.setSelection({ line: anchor[0], ch: anchor[1] }, { line: anchor[0], ch: anchor[1] });
     }
-    const ret = this.editor.editor.replaceSelection(content, isSelect ? 'around' : 'end');
+    this.editor.editor.replaceSelection(content, isSelect ? 'around' : 'end');
     focus && this.editor.editor.focus();
-    return ret;
   }
 
   /**
@@ -357,8 +359,7 @@ export default class Cherry extends CherryStatic {
   /**
    * 覆盖编辑区的内容
    * @param {string} content markdown内容
-   * @param {boolean} keepCursor 是否保持光标位置
-   * @returns
+   * @param {boolean} [keepCursor=false] 是否保持光标位置
    */
   setMarkdown(content, keepCursor = false) {
     return this.setValue(content, keepCursor);
@@ -628,7 +629,7 @@ export default class Cherry extends CherryStatic {
    * @public
    * @param {'pdf' | 'img' | 'markdown' | 'html'} [type='pdf']
    * 'pdf'：导出成pdf文件; 'img'：导出成png图片; 'markdown'：导出成markdown文件; 'html'：导出成html文件;
-   * @param {string} [fileName] 导出文件名
+   * @param {string} [fileName] 导出文件名(默认为当前第一行内容|'cherry-export')
    */
   export(type = 'pdf', fileName = '') {
     this.previewer.export(type, fileName);

src/Engine.js

@@ -192,6 +192,10 @@ export default class Engine {
     return this.$fireHookAction(md, 'paragraph', 'makeHtml', this.$dealSentenceByCache.bind(this));
   }
 
+  /**
+   * @param {string} md md字符串
+   * @returns {string} 获取html
+   */
   makeHtml(md) {
     let $md = this.$beforeMakeHtml(md);
     $md = this.$dealParagraph($md);
@@ -205,6 +209,10 @@ export default class Engine {
     // UrlCache.clear();
   }
 
+  /**
+   * @param {string} html html字符串
+   * @returns {string} 获取markdown
+   */
   makeMarkdown(html) {
     return htmlParser.run(html);
   }

src/toolbars/Toolbar.js

@@ -19,9 +19,51 @@ import Event from '@/Event';
 import { createElement } from '@/utils/dom';
 import Logger from '@/Logger';
 
+/**
+ * @typedef {()=>void} Bold 向cherry编辑器中插入粗体语法
+ * @typedef {()=>void} Italic 向cherry编辑器中插入斜体语法
+ * @typedef {(level:1|2|3|4|5|'1'|'2'|'3'|'4'|'5')=>void} Header  向cherry编辑器中插入标题语法
+ * - level 标题等级 1~5
+ * @typedef {()=>void} Strikethrough 向cherry编辑器中插入删除线语法
+ * @typedef {(type:'ol'|'ul'|'checklist'|1|2|3|'1'|'2'|'3')=>void} List 向cherry编辑器中插入有序、无序列表或者checklist语法
+ * - ol(1)有序
+ * - ul(2)无序列表
+ * - checklist(3)checklist
+ * @typedef {(insert:'hr'|'br'|'code'|'formula'|'checklist'|'toc'|'link'|'image'|'video'|'audio'|'normal-table'|'normal-table-row*col')=>void} Insert 向cherry编辑器中插入特定语法
+ * - hr 水平分割线
+ * - br 换行
+ * - code 代码块
+ * - formula 公式
+ * - checklist 检查项
+ * - toc 目录
+ * - link 链接
+ * - image 图片
+ * - video 视频
+ * - audio 音频
+ * - normal-table 插入3行5列的表格
+ * - normal-table-row*col 如normal-table-2*4插入2行(包含表头是3行)4列的表格
+ * @typedef {(type:'1'|'2'|'3'|'4'|'5'|'6'|1|2|3|4|5|6|'flow'|'sequence'|'state'|'class'|'pie'|'gantt')=>void} Graph 向cherry编辑器中插入画图语法
+ * - flow(1) 流程图
+ * - sequence(2) 时序图
+ * - state(3)状态图
+ * - class(4)类图
+ * - pie(5)饼图
+ * - gantt(6)甘特图
+ */
+
 export default class Toolbar {
   /**
-   * @type {Record<string, any>} 外部获取 toolbarHandler
+   * @typedef {{
+   * bold?:Bold;
+   * italic?:Italic;
+   * header?:Header;
+   * strikethrough?:Strikethrough;
+   * list?:List;
+   * insert?:Insert;
+   * graph?:Graph;
+   * [key:string]:any;
+   * }} ToolbarHandlers
+   * @type ToolbarHandlers 外部获取 toolbarHandlers 的部分功能
    */
   toolbarHandlers = {};
 

src/toolbars/hooks/Graph.js

@@ -143,12 +143,12 @@ export default class Graph extends MenuBase {
   /**
    * 响应点击事件
    * @param {string} selection 被用户选中的文本内容，本函数不处理选中的内容，会直接清空用户选中的内容
-   * @param {string} shortKey 快捷键参数
+   * @param {'1'|'2'|'3'|'4'|'5'|'6'|1|2|3|4|5|6|'flow'|'sequence'|'state'|'class'|'pie'|'gantt'|''} shortKey 快捷键参数
    * @returns {string} 回填到编辑器光标位置/选中文本区域的内容
    */
   onClick(selection, shortKey = '') {
     const shortcut = `${shortKey}`;
-    const shortcutKeyMap = [, 'flow', 'sequence', 'state', 'class', 'pie', 'gantt'];
+    const shortcutKeyMap = [null, 'flow', 'sequence', 'state', 'class', 'pie', 'gantt'];
     const selectedExample = shortcutKeyMap[+shortcut];
     if (!shortcutKeyMap[+shortcut]) {
       return;

src/toolbars/hooks/List.js

@@ -37,10 +37,13 @@ export default class List extends MenuBase {
   /**
    * 响应点击事件
    * @param {string} selection 编辑区选中的文本内容
-   * @param {string} shortKey 快捷键：ol 有序列表，ul 无序列表，checklist 检查项
+   * @param {'ol'|'ul'|'checklist'|1|2|3|'1'|'2'|'3'|''} [shortKey] 快捷键：ol(1)有序列表，ul(2)无序列表，checklist(3) 检查项
    * @returns 对应markdown的源码
    */
   onClick(selection, shortKey = '') {
+    /**
+     * @type {['', 'ol', 'ul', 'checklist']}
+     */
     const listType = [null, 'ol', 'ul', 'checklist']; // 下标1, 2, 3生效
     const $selection = getSelection(this.editor.editor, selection, 'line', true);
     const [before] = $selection.match(/^\n*/);