docs: add jsdoc

src/index.ts

@@ -5,17 +5,7 @@ import {Hint} from "./ts/hint/index";
 import {IR} from "./ts/ir";
 import {input as irInput} from "./ts/ir/input";
 import {processAfterRender} from "./ts/ir/process";
-import {abcRender} from "./ts/markdown/abcRender";
-import {chartRender} from "./ts/markdown/chartRender";
-import {codeRender} from "./ts/markdown/codeRender";
-import {graphvizRender} from "./ts/markdown/graphvizRender";
-import {highlightRender} from "./ts/markdown/highlightRender";
-import {mathRender} from "./ts/markdown/mathRender";
-import {loadLuteJs, md2htmlByPreview, md2htmlByVditor} from "./ts/markdown/md2html";
-import {mediaRender} from "./ts/markdown/mediaRender";
-import {mermaidRender} from "./ts/markdown/mermaidRender";
-import {previewRender} from "./ts/markdown/previewRender";
-import {speechRender} from "./ts/markdown/speechRender";
+import {loadLuteJs, md2htmlByVditor} from "./ts/markdown/md2html";
 import {Preview} from "./ts/preview/index";
 import {Resize} from "./ts/resize/index";
 import {formatRender} from "./ts/sv/formatRender";
@@ -41,24 +31,15 @@ import {getEditorRange, setSelectionByPosition} from "./ts/util/selection";
 import {WYSIWYG} from "./ts/wysiwyg";
 import {input} from "./ts/wysiwyg/input";
 import {renderDomByMd} from "./ts/wysiwyg/renderDomByMd";
+import VditorMethod from './method'
 
-class Vditor {
-
-    public static codeRender = codeRender;
-    public static graphvizRender = graphvizRender;
-    public static highlightRender = highlightRender;
-    public static mathRender = mathRender;
-    public static mermaidRender = mermaidRender;
-    public static chartRender = chartRender;
-    public static abcRender = abcRender;
-    public static mediaRender = mediaRender;
-    public static speechRender = speechRender;
-    public static md2html = md2htmlByPreview;
-    public static preview = previewRender;
+class Vditor extends VditorMethod {
+    
     public readonly version: string;
     public vditor: IVditor;
 
     constructor(id: string, options?: IOptions) {
+        super()
         this.version = VDITOR_VERSION;
 
         const getOptions = new Options(options);
@@ -126,15 +107,18 @@ class Vditor {
         }
     }
 
+    /** 设置主题 */
     public setTheme(theme: "dark" | "classic") {
         this.vditor.options.theme = theme;
         setTheme(this.vditor);
     }
 
+    /**	获取编辑器内容 */
     public getValue() {
         return getMarkdown(this.vditor);
     }
 
+    /** 聚焦到编辑器 */
     public focus() {
         if (this.vditor.currentMode === "sv") {
             this.vditor.sv.element.focus();
@@ -145,6 +129,7 @@ class Vditor {
         }
     }
 
+    /** 让编辑器失焦 */
     public blur() {
         if (this.vditor.currentMode === "sv") {
             this.vditor.sv.element.blur();
@@ -155,6 +140,7 @@ class Vditor {
         }
     }
 
+    /** 禁用编辑器 */
     public disabled() {
         disableToolbar(this.vditor.toolbar.elements, ["emoji", "headings", "bold", "italic", "strike", "link",
             "list", "ordered-list", "check", "quote", "line", "code", "inline-code", "upload", "record", "table",
@@ -164,6 +150,7 @@ class Vditor {
         this.vditor.wysiwyg.element.setAttribute("contenteditable", "false");
     }
 
+    /** 解除编辑器禁用 */
     public enable() {
         enableToolbar(this.vditor.toolbar.elements, ["emoji", "headings", "bold", "italic", "strike", "link",
             "list", "ordered-list", "check", "quote", "line", "code", "inline-code", "upload", "record", "table", "wysiwyg"]);
@@ -175,6 +162,7 @@ class Vditor {
         this.vditor.ir.element.setAttribute("contenteditable", "true");
     }
 
+    /** 选中从 start 开始到 end 结束的字符串，不支持 wysiwyg 模式 */
     public setSelection(start: number, end: number) {
         if (this.vditor.currentMode !== "sv") {
             console.error("所见即所得模式暂不支持该方法");
@@ -183,6 +171,7 @@ class Vditor {
         }
     }
 
+    /** 返回选中的字符串 */
     public getSelection() {
         if (this.vditor.currentMode === "wysiwyg") {
             return getSelectText(this.vditor.wysiwyg.element);
@@ -193,12 +182,14 @@ class Vditor {
         }
     }
 
+    /** 设置预览区域内容 */
     public renderPreview(value?: string) {
         if (this.vditor.currentMode === "sv") {
             this.vditor.preview.render(this.vditor, value);
         }
     }
 
+    /** 获取焦点位置 */
     public getCursorPosition() {
         if (this.vditor.currentMode === "wysiwyg") {
             return getCursorPosition(this.vditor.wysiwyg.element);
@@ -209,26 +200,32 @@ class Vditor {
         }
     }
 
+    /** 上传是否还在进行中 */
     public isUploading() {
         return this.vditor.upload.isUploading;
     }
 
+    /** 清除缓存 */
     public clearCache() {
         localStorage.removeItem("vditor" + this.vditor.id);
     }
 
+    /** 禁用缓存 */
     public disabledCache() {
         this.vditor.options.cache = false;
     }
 
+    /** 启用缓存 */
     public enableCache() {
         this.vditor.options.cache = true;
     }
 
+    /** HTML 转 md */
     public html2md(value: string) {
         return html2md(this.vditor, value);
     }
 
+    /** 获取预览区内容 */
     public getHTML() {
         if (this.vditor.currentMode === "sv") {
             return md2htmlByVditor(getMarkdown(this.vditor), this.vditor);
@@ -239,14 +236,17 @@ class Vditor {
         }
     }
 
+    /** 消息提示。time 为 0 将一直显示 */
     public tip(text: string, time?: number) {
         this.vditor.tip.show(text, time);
     }
 
+    /** 设置预览模式 */
     public setPreviewMode(mode: keyof IPreviewMode) {
         setPreviewMode(mode, this.vditor);
     }
 
+    /** 删除选中内容 */
     public deleteValue() {
         if (window.getSelection().isCollapsed) {
             return;
@@ -258,6 +258,7 @@ class Vditor {
         }
     }
 
+    /** 更新选中内容 */
     public updateValue(value: string) {
         if (this.vditor.currentMode === "sv") {
             insertText(this.vditor, value, "", true);
@@ -266,6 +267,7 @@ class Vditor {
         }
     }
 
+    /** 在焦点处插入内容，并默认进行 Markdown 渲染 */
     public insertValue(value: string, render = true) {
         if (this.vditor.currentMode === "sv") {
             insertText(this.vditor, value, "");
@@ -286,6 +288,7 @@ class Vditor {
         }
     }
 
+    /** 设置编辑器内容 */
     public setValue(markdown: string) {
         if (this.vditor.currentMode === "sv") {
             formatRender(this.vditor, markdown, {

src/method.ts

@@ -9,19 +9,29 @@ import {mediaRender} from "./ts/markdown/mediaRender";
 import {mermaidRender} from "./ts/markdown/mermaidRender";
 import {previewRender} from "./ts/markdown/previewRender";
 import {speechRender} from "./ts/markdown/speechRender";
-
 class Vditor {
 
+    /** 为 element 中的代码块添加复制按钮 */
     public static codeRender = codeRender;
+    /** 对 graphviz 进行渲染 */
     public static graphvizRender = graphvizRender;
+    /** 为 element 中的代码块进行高亮渲染 */
     public static highlightRender = highlightRender;
+    /** 对数学公式进行渲染 */
     public static mathRender = mathRender;
+    /** 转换 element 中 class 为 className 的元素为流程图/时序图/甘特图 */
     public static mermaidRender = mermaidRender;
+    /** 图表渲染 */
     public static chartRender = chartRender;
+    /** 五线谱渲染 */
     public static abcRender = abcRender;
+    /** 为[特定链接](https://github.com/Vanessa219/vditor/issues/7)分别渲染为视频、音频、嵌入的 iframe */
     public static mediaRender = mediaRender;
+    /** 对选中的文字进行阅读 */
     public static speechRender = speechRender;
+    /** Markdown 文本转换为 HTML */
     public static md2html = md2htmlByPreview;
+    /** 页面 Markdown 文章渲染 */
     public static preview = previewRender;
 }
 

src/ts/types/index.d.ts

@@ -107,40 +107,64 @@ interface IClasses {
     preview?: string;
 }
 
+/** @link https://hacpai.com/article/1549638745630#options-upload */
 interface IUpload {
+    /** 上传 url */
     url?: string;
+    /** 上传文件最大 Byte */
     max?: number;
+    /** 剪切板中包含图片地址时，使用此 url 重新上传 */
     linkToImgUrl?: string;
+    /** CORS 上传验证，头为 X-Upload-Token */
     token?: string;
+    /** 文件上传类型，同 [input accept](https://www.w3schools.com/tags/att_input_accept.asp) */
     accept?: string;
+    /** 跨站点访问控制。默认值: false */
     withCredentials?: boolean;
+    /** 请求头设置 */
     headers?: { [key: string]: string };
-
+    
+    /** 上传成功回调 */
     success?(editor: HTMLPreElement, msg: string): void;
-
+    
+    /** 上传失败回调 */
     error?(msg: string): void;
 
+    /** 文件名安全处理。 默认值: name => name.replace(/\W/g, '') */
     filename?(name: string): string;
 
+    /** 校验，成功时返回 true 否则返回错误信息 */
     validate?(files: File[]): string | boolean;
 
+    /** 自定义上传，当发生错误时返回错误信息 */
     handler?(files: File[]): string | null;
 
+    /** 对服务端返回的数据进行转换，以满足内置的数据结构 */
     format?(files: File[], responseText: string): string;
 
+    /** 将上传的文件处理后再返回  */
     file?(files: File[]): File[];
 }
 
+/** @link https://hacpai.com/article/1549638745630#options-toolbar */
 interface IMenuItem {
+    /** 唯一标示 */
     name: string;
+    /** svg 图标 HTML */
     icon?: string;
+    /** 提示 */
     tip?: string;
+    /** 快捷键，支持⌘/ctrl-key 或 ⌘/ctrl-⇧/shif-key 格式的配置，不支持 wysiwyg 模式 */
     hotkey?: string;
+    /** 插入编辑器中的后缀 */
     suffix?: string;
+    /** 插入编辑器中的前缀 */
     prefix?: string;
+    /** 提示位置：ne, nw */
     tipPosition?: string;
     panelElement?: HTMLElement;
 
+    /** 自定义按钮点击时触发的事件 */
     click?(status?: boolean): void;
 }
 
@@ -150,37 +174,59 @@ interface IPreviewMode {
     editor: string;
 }
 
+/** @link https://hacpai.com/article/1549638745630#options-preview-hljs */
 interface IHljs {
+    /** 是否启用行号。默认值: false */
     lineNumber?: boolean;
+    /** 可选值参见 [Chroma](https://xyproto.github.io/splash/docs/longer/all.html)。 默认值: 'github' */
     style?: string;
+    /** 是否启用代码高亮。默认值: true */
     enable?: boolean;
 }
 
+/** @link https://hacpai.com/article/1549638745630#options-preview-math */
 interface IMath {
+    /** 内联数学公式起始 $ 后是否允许数字。默认值: false */
     inlineDigit: boolean;
+    /** 使用 MathJax 渲染时传入的宏定义。默认值: {} */
     macros: object;
+    /** 数学公式渲染引擎。默认值: 'KaTeX' */
     engine: "KaTeX" | "MathJax";
 }
 
+/** @link https://hacpai.com/article/1549638745630#options-preview-markdown */
 interface IMarkdownConfig {
+    /** 自动空格。默认值: false */
     autoSpace?: boolean;
+    /** 自动矫正术语。默认值: false */
     fixTermTypo?: boolean;
+    /** 自动矫正标点。默认值: false */
     chinesePunct?: boolean;
+    /** 插入目录。默认值: false */
     toc?: boolean;
+    /** 脚注。默认值: true */
     footnotes?: boolean;
 }
 
+/** @link https://hacpai.com/article/1549638745630#options-preview */
 interface IPreview {
+    /** 预览 debounce 毫秒间隔。默认值: 1000 */
     delay?: number;
+    /** 预览区域最大宽度。默认值: 768 */
     maxWidth?: number;
+    /** 显示模式。默认值: 'both' */
     mode?: keyof IPreviewMode;
+    /** md 解析请求 */
     url?: string;
+    /** @link https://hacpai.com/article/1549638745630#options-preview-hljs */
     hljs?: IHljs;
+    /** @link https://hacpai.com/article/1549638745630#options-preview-math */
     math?: IMath;
+    /** @link https://hacpai.com/article/1549638745630#options-preview-markdown */
     markdown?: IMarkdownConfig;
-
+    /** 预览回调 */
     parse?(element: HTMLElement): void;
-
+    /** 渲染之前回调 */
     transform?(html: string): string;
 }
 
@@ -206,12 +252,18 @@ interface IHintData {
     value: string;
 }
 
+/** @link https://hacpai.com/article/1549638745630#options-hint */
 interface IHint {
+    /** 常用表情提示 HTML */
     emojiTail?: string;
+    /** 提示 debounce 毫秒间隔。默认值: 200 */
     delay?: number;
+    /** 默认表情，可从 [lute/emoji_map](https://github.com/88250/lute/blob/master/parse/emoji_map.go#L32) 中选取，也可自定义 */
     emoji?: { [key: string]: string };
+    /** 表情图片地址。默认值: 'https://cdn.jsdelivr.net/npm/vditor@${VDITOR_VERSION}/dist/images/emoji' */
     emojiPath?: string;
 
+    /** `@`用户回调 */
     at?(value: string): IHintData[];
 }
 
@@ -222,40 +274,66 @@ interface IResize {
     after?(height: number): void;
 }
 
+/** @link https://hacpai.com/article/1549638745630#options */
 interface IOptions {
+    /** 编辑器初始化值。默认值: '' */
     value?: string;
+    /** 是否显示日志。默认值: false */
     debugger?: boolean;
+    /** 编辑器异步渲染完成后的回调方法 */
     after?: () => void;
+    /** 是否启用打字机模式。默认值: false */
     typewriterMode?: boolean;
     keymap?: { [key: string]: string };
+    /** 编辑器总高度。默认值: 'auto' */
     height?: number | string;
+    /** 编辑器总宽度，支持 %。默认值: 'auto' */
     width?: number | string;
+    /** 输入区域为空时的提示。默认值: '' */
     placeholder?: string;
+    /** 多语言。默认值: 'zh_CN' */
     lang?: (keyof II18nLang);
+    /** @link https://hacpai.com/article/1549638745630#options-toolbar */
     toolbar?: Array<string | IMenuItem>;
     resize?: IResize;
+    /** 计数器。默认值: '0' */
     counter?: number;
+    /** 是否使用 localStorage 进行缓存。默认值: 'auto' */
     cache?: boolean;
+    /** 模式 */
     mode?: "wysiwyg" | "sv" | "ir";
+    /** @link https://hacpai.com/article/1549638745630#options-preview */
     preview?: IPreview;
+    /** @link https://hacpai.com/article/1549638745630#options-hint */
     hint?: IHint;
+    /** 是否隐藏工具栏。默认值: false */
     hideToolbar?: boolean;
+    /** 主题。默认值: 'classic' */
     theme?: "classic" | "dark";
+    /** @link https://hacpai.com/article/1549638745630#options-upload */
     upload?: IUpload;
     classes?: IClasses;
+    /** 配置自建 CDN 地址。默认值: 'https://cdn.jsdelivr.net/npm/vditor@${VDITOR_VERSION}' */
     cdn?: string;
+    /** tab 键操作字符串，支持 \t 及任意字符串 */
     tab?: string;
 
+    /** 输入后触发 */
     input?(value: string, previewElement?: HTMLElement): void;
 
+    /** 聚焦后触发  */
     focus?(value: string): void;
 
+    /** 失焦后触发 */
     blur?(value: string): void;
 
+    /** `esc` 按下后触发 */
     esc?(value: string): void;
 
+    /** `⌘/ctrl+enter` 按下后触发 */
     ctrlEnter?(value: string): void;
 
+    /** 编辑器中选中文字后触发 */
     select?(value: string): void;
 }