feat:add docs

2022-12-31 22:27:43 +08:00
parent e8f3b2a6da
commit db52ab815d
17 changed files with 1758 additions and 4 deletions
@@ -0,0 +1,529 @@
+# 执行动作命令
+
+## 使用方式
+
+```javascript
+import Editor from "@hufe921/canvas-editor"
+
+const instance = new Editor(container, <IElement[]>data, options)
+instance.command.commandName()
+```
+
+## executeMode
+功能：切换编辑器模式（编辑、清洁、只读）
+
+用法：
+```javascript
+instance.command.executeMode(EditorMode)
+```
+
+## executeCut
+功能：剪切
+
+用法：
+```javascript
+instance.command.executeCut()
+```
+
+## executeCopy
+功能：复制
+
+用法：
+```javascript
+instance.command.executeCopy()
+```
+
+## executePaste
+功能：粘贴
+
+用法：
+```javascript
+instance.command.executePaste()
+```
+
+## executeSelectAll
+功能：全选
+
+用法：
+```javascript
+instance.command.executeSelectAll()
+```
+
+## executeBackspace
+功能：向前删除
+
+用法：
+```javascript
+instance.command.executeBackspace()
+```
+
+## executeSetRange
+功能：设置选区
+
+用法：
+```javascript
+instance.command.executeSetRange(startIndex, endIndex)
+```
+
+## executeUndo
+功能：撤销
+
+用法：
+```javascript
+instance.command.executeUndo()
+```
+
+## executeRedo
+功能：重做
+
+用法：
+```javascript
+instance.command.executeRedo()
+```
+
+## executePainter
+功能：格式刷-复制样式
+
+用法：
+```javascript
+instance.command.executePainter()
+```
+
+## executeApplyPainterStyle
+功能：格式刷-应用样式
+
+用法：
+```javascript
+instance.command.executeApplyPainterStyle()
+```
+
+## executeFormat
+功能：清除样式
+
+用法：
+```javascript
+instance.command.executeFormat()
+```
+
+## executeFont
+功能：设置字体
+
+用法：
+```javascript
+instance.command.executeFont(font)
+```
+
+## executeSizeAdd
+功能：增大字号
+
+用法：
+```javascript
+instance.command.executeSizeAdd()
+```
+
+## executeSizeMinus
+功能：减小字号
+
+用法：
+```javascript
+instance.command.executeSizeMinus()
+```
+
+## executeBold
+功能：字体加粗
+
+用法：
+```javascript
+instance.command.executeBold()
+```
+
+## executeItalic
+功能：字体斜体
+
+用法：
+```javascript
+instance.command.executeItalic()
+```
+
+## executeUnderline
+功能：下划线
+
+用法：
+```javascript
+instance.command.executeUnderline()
+```
+
+## executeStrikeout
+功能：删除线
+
+用法：
+```javascript
+instance.command.executeStrikeout()
+```
+
+## executeSuperscript
+功能：上标
+
+用法：
+```javascript
+instance.command.executeSuperscript()
+```
+
+## executeSubscript
+功能：上下标
+
+用法：
+```javascript
+instance.command.executeSubscript()
+```
+
+## executeColor
+功能：字体颜色
+
+用法：
+```javascript
+instance.command.executeColor()
+```
+
+## executeHighlight
+功能：高亮
+
+用法：
+```javascript
+instance.command.executeHighlight()
+```
+
+## executeLeft
+功能：行居左
+
+用法：
+```javascript
+instance.command.executeLeft()
+```
+
+## executeCenter
+功能：行居中
+
+用法：
+```javascript
+instance.command.executeCenter()
+```
+
+## executeRight
+功能：行居右
+
+用法：
+```javascript
+instance.command.executeRight()
+```
+
+## executeAlignment
+功能：行两端对齐
+
+用法：
+```javascript
+instance.command.executeAlignment()
+```
+
+## executeRowMargin
+功能：行间距
+
+用法：
+```javascript
+instance.command.executeRowMargin(number)
+```
+
+## executeInsertTable
+功能：插入表格
+
+用法：
+```javascript
+instance.command.executeInsertTable(row, col)
+```
+
+## executeInsertTableTopRow
+功能：向上插入一行
+
+用法：
+```javascript
+instance.command.executeInsertTableTopRow()
+```
+
+## executeInsertTableBottomRow
+功能：向下插入一行
+
+用法：
+```javascript
+instance.command.executeInsertTableBottomRow()
+```
+
+## executeInsertTableLeftCol
+功能：向左插入一列
+
+用法：
+```javascript
+instance.command.executeInsertTableLeftCol()
+```
+
+## executeInsertTableRightCol
+功能：向右插入一列
+
+用法：
+```javascript
+instance.command.executeInsertTableRightCol()
+```
+
+## executeDeleteTableRow
+功能：删除当前行
+
+用法：
+```javascript
+instance.command.executeDeleteTableRow()
+```
+
+## executeDeleteTableCol
+功能：删除当前列
+
+用法：
+```javascript
+instance.command.executeDeleteTableCol()
+```
+
+## executeDeleteTable
+功能：删除表格
+
+用法：
+```javascript
+instance.command.executeDeleteTable()
+```
+
+## executeMergeTableCell
+功能：合并表格
+
+用法：
+```javascript
+instance.command.executeMergeTableCell()
+```
+
+## executeCancelMergeTableCell
+功能：取消合并表格
+
+用法：
+```javascript
+instance.command.executeCancelMergeTableCell()
+```
+
+## executeImage
+功能：插入图片
+
+用法：
+```javascript
+instance.command.executeImage({
+  width: number;
+  height: number;
+  value: string;
+})
+```
+
+## executeHyperlink
+功能：插入链接
+
+用法：
+```javascript
+instance.command.executeHyperlink({
+  type: ElementType.HYPERLINK,
+  value: '',
+  url,
+  valueList: IElement[]
+})
+```
+
+## executeDeleteHyperlink
+功能：删除链接
+
+用法：
+```javascript
+instance.command.executeDeleteHyperlink()
+```
+
+## executeCancelHyperlink
+功能：取消链接
+
+用法：
+```javascript
+instance.command.executeCancelHyperlink()
+```
+
+## executeEditHyperlink
+功能：编辑链接
+
+用法：
+```javascript
+instance.command.executeEditHyperlink(newUrl)
+```
+
+## executeSeparator
+功能：插入分割线
+
+用法：
+```javascript
+instance.command.executeSeparator(dashArray)
+```
+
+## executePageBreak
+功能：分页符
+
+用法：
+```javascript
+instance.command.executePageBreak()
+```
+
+## executeAddWatermark
+功能：添加水印
+
+用法：
+```javascript
+instance.command.executeAddWatermark({
+  data: string;
+  color?: string;
+  opacity?: number;
+  size?: number;
+  font?: string;
+})
+```
+
+## executeDeleteWatermark
+功能：添加水印
+
+用法：
+```javascript
+instance.command.executeDeleteWatermark()
+```
+
+## executeSearch
+功能：搜索
+
+用法：
+```javascript
+instance.command.executeSearch(keyword)
+```
+
+## executeSearchNavigatePre
+功能：搜索导航-上一个
+
+用法：
+```javascript
+instance.command.executeSearchNavigatePre()
+```
+
+## executeSearchNavigateNext
+功能：搜索导航-下一个
+
+用法：
+```javascript
+instance.command.executeSearchNavigateNext()
+```
+
+## executeReplace
+功能：搜索替换
+
+用法：
+```javascript
+instance.command.executeReplace(newWord)
+```
+
+## executePrint
+功能：打印
+
+用法：
+```javascript
+instance.command.executePrint()
+```
+
+## executeReplaceImageElement
+功能：替换图片
+
+用法：
+```javascript
+instance.command.executeReplaceImageElement(newUrl)
+```
+
+## executeSaveAsImageElement
+功能：另存为图片
+
+用法：
+```javascript
+instance.command.executeSaveAsImageElement()
+```
+
+## executeChangeImageDisplay
+功能：改变图片行显示方式
+
+用法：
+```javascript
+instance.command.executeSaveAsImageElement(element, display)
+```
+
+## executePageMode
+功能：页面模式
+
+用法：
+```javascript
+instance.command.executePageMode(pageMode)
+```
+
+## executePageScaleRecovery
+功能：恢复页面原始缩放比例
+
+用法：
+```javascript
+instance.command.executePageMode()
+```
+
+## executePageScaleMinus
+功能：页面缩小
+
+用法：
+```javascript
+instance.command.executePageScaleMinus()
+```
+
+## executePageScaleAdd
+功能：页面放大
+
+用法：
+```javascript
+instance.command.executePageScaleAdd()
+```
+
+## executePaperSize
+功能：设置纸张大小
+
+用法：
+```javascript
+instance.command.executePaperSize(width, height)
+```
+
+## executeSetPaperMargin
+功能：设置纸张页边距
+
+用法：
+```javascript
+instance.command.executeSetPaperMargin([top: number, right: number, bottom: number, left: number])
+```
+
+## executeInsertElementList
+功能：插入元素
+
+用法：
+```javascript
+instance.command.executeInsertElementList(IElement[])
+```
+
+## executeRemoveControl
+功能：删除控件
+
+用法：
+```javascript
+instance.command.executeRemoveControl()
+```
@@ -0,0 +1,67 @@
+# 获取数据命令
+
+## 使用方式
+
+```javascript
+import Editor from "@hufe921/canvas-editor"
+
+const instance = new Editor(container, <IElement[]>data, options)
+const value = instance.command.commandName()
+```
+## getValue
+功能：获取当前文档信息
+
+用法：
+```javascript
+const {
+  version: string;
+  width: number;
+  height: number;
+  margins: IMargin;
+  header?: IHeader;
+  watermark?: IWatermark;
+  data: IElement[];
+} = instance.command.getValue()
+```
+
+## getImage
+功能：获取当前页面图片base64字符串
+
+用法：
+```javascript
+const base64StringList = instance.command.getValue()
+```
+
+## getWordCount
+功能：获取文档字数
+
+用法：
+```javascript
+const wordCount = await instance.command.getWordCount()
+```
+## getRangeText
+功能：获取选区文本
+
+用法：
+```javascript
+const rangeText = instance.command.getRangeText()
+```
+
+## getPaperMargin
+功能：获取页边距
+
+用法：
+```javascript
+const [top: number, right: number, bottom: number, left: number] = instance.command.getPaperMargin()
+```
+
+## getSearchNavigateInfo
+功能：获取搜索导航信息
+
+用法：
+```javascript
+const {
+  index: number;
+  count: number;
+} = instance.command.getSearchNavigateInfo()
+```
@@ -0,0 +1,20 @@
+# 自定义右键菜单
+
+## 使用方式
+
+```javascript
+import Editor from "@hufe921/canvas-editor"
+
+const instance = new Editor(container, <IElement[]>data, options)
+instance.register.contextMenuList([
+    {
+      isDivider?: boolean;
+      icon?: string;
+      name?: string;
+      shortCut?: string;
+      when?: (payload: IContextMenuContext) => boolean;
+      callback?: (command: Command, context: IContextMenuContext) => any;
+      childMenus?: IRegisterContextMenu[];
+    }
+  ])
+```
@@ -0,0 +1,36 @@
+# 内部右键菜单
+
+## 全局
+- 剪切
+- 复制
+- 粘贴
+- 全选
+- 打印
+
+## 超链接
+- 删除链接
+- 取消链接
+- 编辑链接
+
+## 图片
+- 更改图片
+- 另存为图片
+- 文字环绕
+  - 嵌入型
+  - 上下型环绕
+
+## 表格
+- 插入行列
+  - 上方插入1行
+  - 下方插入1行
+  - 左侧插入1列
+  - 右侧插入1列
+- 删除行列
+  - 删除1行
+  - 删除1列
+  - 删除整个表格
+- 合并单元格
+- 取消合并
+
+## 控件
+- 删除控件
@@ -0,0 +1,82 @@
+# 事件监听
+
+## 使用方式
+
+```javascript
+import Editor from "@hufe921/canvas-editor"
+
+const instance = new Editor(container, <IElement[]>data, options)
+instance.listener.eventName = ()=>{}
+```
+
+## rangeStyleChange
+功能：选区样式发生改变
+
+用法：
+```javascript
+instance.listener.rangeStyleChange = (payload: IRangeStyle)=>{}
+```
+
+## visiblePageNoListChange
+功能：可见页发生改变
+
+用法：
+```javascript
+instance.listener.visiblePageNoListChange = (payload: number[])=>{}
+```
+
+## intersectionPageNoChange
+功能：当前页发生改变
+
+用法：
+```javascript
+instance.listener.intersectionPageNoChange = (payload: number)=>{}
+```
+
+## pageSizeChange
+功能：当前页数发生改变
+
+用法：
+```javascript
+instance.listener.pageSizeChange = (payload: number)=>{}
+```
+
+## pageScaleChange
+功能：当前页面缩放比例发生改变
+
+用法：
+```javascript
+instance.listener.pageScaleChange = (payload: number)=>{}
+```
+
+## contentChange
+功能：当前内容发生改变
+
+用法：
+```javascript
+instance.listener.contentChange = ()=>{}
+```
+
+## controlChange
+功能：当前光标所在控件发生改变
+
+用法：
+```javascript
+instance.listener.controlChange = (payload: IControl | null)=>{}
+```
+
+## pageModeChange
+功能：页面模式发生改变
+
+用法：
+```javascript
+instance.listener.controlChange = (payload: PageMode)=>{}
+```
+
+## saved
+功能：文档执行保存
+
+用法：
+```javascript
+instance.listener.saved = (payload: IEditorResult)=>{}
+```
@@ -0,0 +1,55 @@
+# 配置
+
+## 使用方式
+
+```javascript
+import Editor from "@hufe921/canvas-editor"
+
+new Editor(container, [], {
+  // 配置项
+})
+```
+
+## 完整配置
+
+```typescript
+interface IEditorOption {
+  mode?: EditorMode; // 编辑器模式：编辑、清洁、只读。默认：编辑
+  defaultType?: string; // 默认元素类型。默认：TEXT
+  defaultFont?: string; // 默认字体。默认：Yahei
+  defaultSize?: number; // 默认字号。默认：16
+  defaultBasicRowMarginHeight?: number; // 默认行高。默认：8
+  defaultRowMargin?: number; // 默认行间距。默认：1
+  defaultTabWidth?: number; // 默认tab宽度。默认：32
+  width?: number; // 纸张宽度。默认：794
+  height?: number; // 纸张高度。默认：1123
+  scale?: number; // 缩放比例。默认：1
+  pageGap?: number; // 纸张间隔。默认：20
+  pageNumberBottom?: number; // 页码距离纸张下边距。默认：60
+  pageNumberSize?: number; // 页码字号。默认：12
+  pageNumberFont?: string; // 页码字体。默认：Yahei
+  underlineColor?: string; // 下划线颜色。默认：#000000
+  strikeoutColor?: string; // 删除线颜色。默认：#FF0000
+  rangeColor?: string; // 选区颜色。默认：#AECBFA
+  rangeAlpha?: number; // 选区透明度。默认：0.6
+  rangeMinWidth?: number; // 选区最小宽度。默认：5
+  searchMatchColor?: string; // 搜索高亮颜色。默认：#FFFF00
+  searchNavigateMatchColor?: string; // 搜索导航高亮颜色。默认：#AAD280
+  searchMatchAlpha?: number; // 搜索高亮透明度。默认：0.6
+  highlightAlpha?: number; // 高亮元素透明度。默认：0.6
+  resizerColor?: string; // 图片尺寸器颜色。默认：#4182D9
+  resizerSize?: number; // 图片尺寸器大小。默认：5
+  marginIndicatorSize?: number; // 页边距指示器长度。默认：35
+  marginIndicatorColor?: string, // 页边距指示器颜色。默认：#BABABA
+  margins?: IMargin, // 页面边距。默认：[100, 120, 100, 120]
+  pageMode?: PageMode; // 纸张模式：连页、分页。默认：分页
+  tdPadding?: number; // 单元格内边距。默认：5
+  defaultTdHeight?: number; // 默认单元格高度。默认：40
+  defaultHyperlinkColor?: string; // 默认超链接颜色。默认：#0000FF
+  headerTop?: number; // 页眉距离上边距。默认：50
+  header?: IHeader; // 页眉信息。{data:string; color?:string; size?:number; font?:string;}
+  watermark?: IWatermark; // 水印信息。{data:string; color?:string; opacity?:number; size?:number; font?:string;}
+  control?: IControlOption; // 控件信息。 {placeholderColor?:string; bracketColor?:string; prefix?:string; postfix?:string;}
+  checkbox?: ICheckboxOption; // 复选框信息。{width?:number; height?:number; gap?:number; lineWidth?:number; fillStyle?:string; fontStyle?: string;}
+}
+```
@@ -0,0 +1,131 @@
+# 数据结构
+
+```typescript
+interface IElement {
+  // 基础
+  id?: string;
+  type?: {
+    TEXT = 'text',
+    IMAGE = 'image',
+    TABLE = 'table',
+    HYPERLINK = 'hyperlink',
+    SUPERSCRIPT = 'superscript',
+    SUBSCRIPT = 'subscript',
+    SEPARATOR = 'separator',
+    PAGE_BREAK = 'pageBreak',
+    CONTROL = 'control',
+    CHECKBOX = 'checkbox',
+    LATEX = 'latex',
+    TAB = 'tab',
+    DATE = 'date',
+    BLOCK = 'block'
+  };
+  value: string;
+  // 样式
+  font?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  bold?: boolean;
+  color?: string;
+  highlight?: string;
+  italic?: boolean;
+  underline?: boolean;
+  strikeout?: boolean;
+  rowFlex?: {
+    LEFT = 'left',
+    CENTER = 'center',
+    RIGHT = 'right',
+    ALIGNMENT = 'alignment'
+  };
+  rowMargin?: number;
+  letterSpacing?: number;
+  // 表格
+  colgroup?: {
+    id?: string;
+    width: number;
+  }[];
+  trList?: {
+    id?: string;
+    height: number;
+    tdList: {
+      colspan: number;
+      rowspan: number;
+      value: IElement[];
+    }[];
+  }[];
+  tdId?: string;
+  trId?: string;
+  tableId?: string;
+  // 超链接
+  valueList?: IElement[];
+  url?: string;
+  hyperlinkId?: string;
+  // 上下标
+  actualSize?: number;
+  // 分割线
+  dashArray?: number[];
+  // 控件
+  control?: {
+    type: {
+      TEXT = 'text',
+      SELECT = 'select',
+      CHECKBOX = 'checkbox'
+    };
+    value: IElement[] | null;
+    placeholder?: string;
+    conceptId?: string;
+    prefix?: string;
+    postfix?: string;
+    code: string | null;
+    min?: number;
+    max?: number;
+    valueSets: {
+      value: string;
+      code: string;
+    }[];
+    checkbox?: {
+      value: boolean | null;
+      code?: string;
+      disabled?: boolean;
+    };
+  };
+  controlId?: string;
+  controlComponent?: {
+    PREFIX = 'prefix',
+    POSTFIX = 'postfix',
+    PLACEHOLDER = 'placeholder',
+    VALUE = 'value',
+    CHECKBOX = 'checkbox'
+  };
+  // 复选框
+  checkbox?: {
+    value: boolean | null;
+    code?: string;
+    disabled?: boolean;
+  };
+  // LaTeX
+  laTexSVG?: string;
+  // 日期
+  dateFormat?: string;
+  dateId?: string;
+  // 图片
+  imgDisplay?: {
+    INLINE = 'inline',
+    BLOCK = 'block'
+  }
+  // 内容块
+  block?: {
+    type: {
+      IFRAME = 'iframe',
+      VIDEO = 'video'
+    };
+    iframeBlock?: {
+      src: string;
+    };
+    videoBlock?: {
+      src: string;
+    };
+  };
+}
+```
@@ -0,0 +1,19 @@
+# 自定义快捷键
+
+## 使用方式
+
+```javascript
+import Editor from "@hufe921/canvas-editor"
+
+const instance = new Editor(container, <IElement[]>data, options)
+instance.register.shortcutList([
+    {
+      key: KeyMap;
+      ctrl?: boolean;
+      shift?: boolean;
+      alt?: boolean;
+      isGlobal?: boolean;
+      callback: (command: Command) => any;
+    }
+  ])
+```
@@ -0,0 +1,82 @@
+# 内部快捷键
+
+## Backspace
+功能：向前删除
+
+## Delete
+功能：向后删除
+
+## Enter
+功能：换行
+
+## ←
+功能：向左移动
+
+## →
+功能：向右移动
+
+## ↑
+功能：向上移动
+
+## ↓
+功能：向下移动
+
+## Esc
+功能：退出格式刷
+
+## Tab
+功能：增加缩进
+
+## Ctrl + Z
+功能：撤销
+
+## Ctrl + Y
+功能：重做
+
+## Ctrl + C
+功能：复制
+
+## Ctrl + X
+功能：剪切
+
+## Ctrl + A
+功能：全选
+
+## Ctrl + S
+功能：保存
+
+## Ctrl + {
+功能：增大字体
+
+## Ctrl + }
+功能：减小字体
+
+## Ctrl + B
+功能：加粗
+
+## Ctrl + I
+功能：斜体
+
+## Ctrl + U
+功能：下划线
+
+## Ctrl + L
+功能：行居左
+
+## Ctrl + E
+功能：行居中
+
+## Ctrl + R
+功能：行居右
+
+## Ctrl + J
+功能：两端对齐
+
+## Ctrl + Shift + X
+功能：删除线
+
+## Ctrl + Shift + >
+功能：上标
+
+## Ctrl + Shift + <
+功能：下标
@@ -0,0 +1,58 @@
+# 入门
+
+> 所见即所得的富文本编辑器。
+
+得益于光标及文字排版的完全自行实现。绘制底层也可由svg渲染，详见代码：[feature/svg](https://github.com/Hufe921/canvas-editor/tree/feature/svg)；或借助pdfjs的完成pdf的绘制，详见代码：[feature/pdf](https://github.com/Hufe921/canvas-editor/tree/feature/pdf)。
+
+::: warning
+官方仅提供编辑器核心层npm包，菜单栏或其他外部工具可自行参考文档扩展，或直接参考[官方](https://github.com/Hufe921/canvas-editor)实现，详见[demo](https://hufe.club/canvas-editor/)。
+:::
+
+## 功能点
+
+- 富文本操作（撤销、重做、字体、字号、加粗、斜体、上下标、对齐方式.....）
+- 插入元素（表格、图片、链接、代码块、分页符、Math公式、日期选择器、内容块......）
+- 打印（基于canvas转图片、pdf绘制）
+- 控件（单选、文本、复选框）
+- 右键菜单（内部、自定义）
+- 快捷键（内部、自定义）
+- 页眉、页码
+- 文字拖拽
+- 页边距
+- 水印
+- 分页
+
+## 待开发
+
+- 渲染性能
+- 控件规则
+- 表格分页
+- 可编辑页眉页脚
+
+## Step. 1: 下载npm包
+
+```sh
+npm i @hufe921/canvas-editor --save
+```
+
+## Step. 2: 准备一个容器
+
+```html
+<div class="canvas-editor"></div>
+```
+
+## Step. 3: 实例化编辑器
+
+```javascript
+import Editor from "@hufe921/canvas-editor"
+
+new Editor(document.querySelector(".canvas-editor"), [
+    {
+      value: "Hello World"
+    }
+  ], {})
+```
+
+## Step. 4: 配置编辑器
+
+详见下一节