@logicflow/extension 2.0.0-beta.2 → 2.0.0-beta.4

package/src/tools/snapshot/README.md

@@ -1,9 +1,134 @@
-## 截取logic-flow内部图形保存为文件并下载
+# 导出 Snapshot
 
-## 往logicflow上下文中添加api getSnapshot
+我们经常需要将画布内容通过图片的形式导出来，我们提供了一个独立的插件包 `Snapshot` 来使用这个功能。
 
-```ts
+## 使用
+
+### 1. 注册
+
+两种注册方式，全局注册和局部注册，区别是全局注册每一个`lf`实例都可以使用。
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Snapshot } from "@logicflow/extension";
+
+// 全局注册
 LogicFlow.use(Snapshot);
-const lf = new LogicFlow({});
-lf.getSnapshot();
+
+// 局部注册
+const lf = new LogicFlow({
+  ...config,
+  plugins: [Snapshot]
+});
+
+```
+
+### 2. 使用
+
+注册后，`lf`实例身上将被挂载`getSnapshot()`方法，通过`lf.getSnapshot()`方法调用。
+
+```tsx | pure
+
+// 可以使用任意方式触发，然后将绘制的图形下载到本地磁盘上
+document.getElementById("button").addEventListener("click", () => {
+  lf.getSnapshot();
+
+  // 或者 1.1.13版本
+  // lf.extension.snapshot.getSnapshot()
+});
+
 ```
+
+值得一提的是：通过此插件截取下载的图片不会因为偏移、缩放受到影响。
+
+## 自定义设置 css
+
+当自定义元素在导出图片时需要额外添加 css 样式时，可以用如下方式实现：
+
+为了保持流程图生成的图片与画布上效果一致，`snapshot`插件默认会将当前页面所有的 `css` 规则都加载到导出图片中, 但是可能会因为 css 文件跨域引起报错，参考 issue575。可以修改useGlobalRules来禁止加载所有 css 规则，然后通过`customCssRules`属性来自定义增加css样式。
+
+```tsx
+
+// 默认开启css样式
+lf.extension.snapshot.useGlobalRules = true
+// 不会覆盖css样式，会叠加，customCssRules优先级高
+lf.extension.snapshot.customCssRules = `
+    .uml-wrapper {
+      line-height: 1.2;
+      text-align: center;
+      color: blue;
+    }
+  `
+  
+```
+
+## API
+
+### lf.getSnapshot(...)
+
+导出图片。
+
+```ts
+
+getSnapshot(fileName?: string, toImageOptions?: ToImageOptions) : Promise<void>
+
+```
+
+`fileName` 为文件名称，不填为默认为`logic-flow.当前时间戳`，`ToImageOptions` 描述如下：
+
+| 属性名  | 类型 | 默认值 | 必填 | 描述   |
+| --------- | -------- | -------------------------- | -------- | ----------------------------------------------------------------- |
+| fileType | string | png |  |  图片类型: 默认不填是png 还可以设置有webp、gif、jpeg、svg |
+| width | number | - | | 自定义导出图片的宽度，不设置即可，设置可能会拉伸图形 |
+| height | numebr | - | | 自定义导出图片的宽度，不设置即可，设置可能会拉伸图形 |
+| backgroundColor | string | - | | 图片背景，不设置背景默认透明 |
+| quality | number | - | | 图片质量，在指定图片格式为 jpeg 或 webp 的情况下，可以从 0 到 1 的区间内选择图片的质量。如果超出取值范围，将会使用默认值 0.92。其他不合法参数会被忽略 |
+| padding | number | 40 | | 图片内边距: 元素内容所在区之外空白空间，不设置默认有40的内边距 |
+| partial | boolean | - |  | 导出时是否开启局部渲染，false：将导出画布上所有的元素，true：只导出画面区域内的可见元素，不设置默认为lf实例身上partial值 |
+
+注意：
+-  `svg`目前暂不支持`width`，`height`， `backgroundColor`， `padding` 属性。
+- 自定义宽高后，可能会拉伸图形，这时候`padding`也会被拉伸导致不准确。
+
+### lf.getSnapshotBlob(...)
+
+`snapshot` 除了支持图片类型导出，还支持下载<a href="https://developer.mozilla.org/zh-CN/docs/Web/API/Blob" target="_blank"> Blob文件对象 </a> 和 <a href="https://developer.mozilla.org/zh-CN/docs/Glossary/Base64" target="_blank"> Base64文本编码 </a>
+
+获取`Blob`对象。
+
+```ts
+
+async getSnapshotBlob(backgroundColor?: string, fileType?: string) : Promise<SnapshotResponse>
+
+// example
+const { data : blob } = await lf.getSnapshotBlob()
+console.log(blob)
+
+```
+`backgroundColor`: 背景，不填默认为透明。
+
+`fileType`: 文件类型，不填默认为png。
+
+`SnapshotResponse`: 返回对象。
+
+```tsx | pure
+
+export type SnapshotResponse = {
+  data: Blob | string // Blob对象 或 Base64文本编码文本
+  width: number // 图片宽度
+  height: number // 图片高度
+}
+
+```
+
+### lf.getSnapshotBase64(...)
+
+获取`Base64文本编码`文本。
+
+```ts
+
+async getSnapshotBase64(backgroundColor?: string, fileType?: string) : Promise<SnapshotResponse>
+
+// example
+const { data : base64 } = await lf.getSnapshotBlob()
+console.log(base64)

package/src/tools/snapshot/index.ts

@@ -1,12 +1,58 @@
+import LogicFlow from '@logicflow/core'
+import { updateImageSource, copyCanvas } from './utils'
+
+// 导出图片
+export type ToImageOptions = {
+  /**
+   * 导出图片的格式，可选值为：`png`、`webp`、`gif`、`jpeg`、`svg`，默认值为 `png`
+   */
+  fileType?: string
+  /**
+   * 导出图片的宽度，通常无需设置，设置后可能会拉伸图形
+   */
+  width?: number
+  /**
+   * 导出图片的高度，通常无需设置，设置后可能会拉伸图形
+   */
+  height?: number
+  /**
+   * 导出图片的背景色，默认为透明
+   */
+  backgroundColor?: string
+  /**
+   * 导出图片的质量。
+   *
+   * 在指定图片格式为 `jpeg` 或 `webp` 的情况下，可以从 0 到 1 的区间内选择图片的质量，如果超出取值范围，将会使用默认值 0.92。导出为其他格式的图片时，该参数会被忽略。
+   */
+  quality?: number
+  /**
+   * 导出图片的内边距，即元素内容所在区域边界与图片边界的距离，单位为像素，默认为 40
+   */
+  padding?: number
+  /**
+   * 导出图片时是否开启局部渲染
+   * - `false`：将导出画布上所有的元素
+   * - `true`：只导出画面区域内的可见元素
+   */
+  partial?: boolean
+}
+
+// Blob | base64
+export type SnapshotResponse = {
+  data: Blob | string
+  width: number
+  height: number
+}
+
 /**
  * 快照插件，生成视图
  */
 export class Snapshot {
   static pluginName = 'snapshot'
-  lf: any
+  lf: LogicFlow
   offsetX?: number
   offsetY?: number
-  fileName: string = 'snapshot.png'
+  fileName?: string // 默认是 logic-flow.当前时间戳
   customCssRules: string
   useGlobalRules: boolean
 
@@ -14,38 +60,70 @@ export class Snapshot {
     this.lf = lf
     this.customCssRules = ''
     this.useGlobalRules = true
+
     /* 下载快照 */
-    lf.getSnapshot = (fileName: string, backgroundColor: string) => {
-      this.getSnapshot(fileName, backgroundColor)
+    lf.getSnapshot = async (
+      fileName?: string,
+      toImageOptions?: ToImageOptions,
+    ) => {
+      const curPartial = this.lf.graphModel.getPartial()
+      const { partial = curPartial } = toImageOptions ?? {}
+      // 画布当前渲染模式和用户导出渲染模式不一致时，需要更新画布
+      if (curPartial !== partial) {
+        this.lf.graphModel.setPartial(partial)
+        this.lf.graphModel.eventCenter.once('graph:updated', async () => {
+          await this.getSnapshot(fileName, toImageOptions)
+          // 恢复原来渲染模式
+          this.lf.graphModel.setPartial(curPartial)
+        })
+      } else {
+        await this.getSnapshot(fileName, toImageOptions)
+      }
     }
+
     /* 获取Blob对象，用户图片上传 */
-    lf.getSnapshotBlob = (backgroundColor: string) =>
-      this.getSnapshotBlob(backgroundColor)
+    lf.getSnapshotBlob = async (backgroundColor?: string, fileType?: string) =>
+      await this.getSnapshotBlob(backgroundColor, fileType)
+
     /* 获取Base64对象，用户图片上传 */
-    lf.getSnapshotBase64 = (backgroundColor: string) =>
-      this.getSnapshotBase64(backgroundColor)
+    lf.getSnapshotBase64 = async (
+      backgroundColor?: string,
+      fileType?: string,
+    ) => await this.getSnapshotBase64(backgroundColor, fileType)
   }
 
-  /* 获取svgRoot对象 */
-  getSvgRootElement(lf) {
-    const svgRootElement = lf.container.querySelector('.lf-canvas-overlay')
+  /**
+   * 获取svgRoot对象dom: 画布元素（不包含grid背景）
+   * @param lf LogicFlow
+   * @returns
+   */
+  getSvgRootElement(lf: LogicFlow) {
+    const svgRootElement = lf.container.querySelector('.lf-canvas-overlay')!
     return svgRootElement
   }
 
-  triggerDownload(imgURI: string) {
+  /**
+   * 通过 imgUrl 下载图片
+   * @param imgUrl
+   */
+  triggerDownload(imgUrl: string) {
     const evt = new MouseEvent('click', {
       view: document.defaultView,
       bubbles: false,
       cancelable: true,
     })
     const a = document.createElement('a')
-    a.setAttribute('download', this.fileName)
-    a.setAttribute('href', imgURI)
+    a.setAttribute('download', this.fileName!)
+    a.setAttribute('href', imgUrl)
     a.setAttribute('target', '_blank')
     a.dispatchEvent(evt)
   }
 
-  removeAnchor(element) {
+  /**
+   * 删除锚点
+   * @param element ChildNode
+   */
+  private removeAnchor(element: ChildNode) {
     const { childNodes } = element
     let childLength = element.childNodes && element.childNodes.length
     for (let i = 0; i < childLength; i++) {
@@ -59,7 +137,11 @@ export class Snapshot {
     }
   }
 
-  removeRotateControl(element) {
+  /**
+   * 删除旋转按钮
+   * @param element
+   */
+  private removeRotateControl(element: ChildNode) {
     const { childNodes } = element
     let childLength = element.childNodes && element.childNodes.length
     for (let i = 0; i < childLength; i++) {
@@ -73,27 +155,56 @@ export class Snapshot {
     }
   }
 
-  /* 下载图片 */
-  getSnapshot(fileName: string, backgroundColor: string) {
-    this.fileName = fileName || `logic-flow.${Date.now()}.png`
+  /**
+   * 下载图片
+   * @param fileName string
+   * @param toImageOptions
+   */
+  private async getSnapshot(
+    fileName?: string,
+    toImageOptions?: ToImageOptions,
+  ) {
+    const { fileType = 'png', quality } = toImageOptions ?? {}
+    this.fileName = `${fileName ?? `logic-flow.${Date.now()}`}.${fileType}`
     const svg = this.getSvgRootElement(this.lf)
-    this.getCanvasData(svg, backgroundColor).then(
-      (canvas: HTMLCanvasElement) => {
-        const imgURI = canvas
-          .toDataURL('image/png')
-          .replace('image/png', 'image/octet-stream')
-        this.triggerDownload(imgURI)
-      },
-    )
+    await updateImageSource(svg as SVGElement)
+    if (fileType === 'svg') {
+      const copy = this.cloneSvg(svg)
+      const svgString = new XMLSerializer().serializeToString(copy)
+      const blob = new Blob([svgString], {
+        type: 'image/svg+xml;charset=utf-8',
+      })
+      const url = URL.createObjectURL(blob)
+      this.triggerDownload(url)
+    } else {
+      this.getCanvasData(svg, toImageOptions ?? {}).then(
+        (canvas: HTMLCanvasElement) => {
+          // canvas元素 => url   image/octet-stream: 确保所有浏览器都能正常下载
+          const imgUrl = canvas
+            .toDataURL(`image/${fileType}`, quality)
+            .replace(`image/${fileType}`, 'image/octet-stream')
+          this.triggerDownload(imgUrl)
+        },
+      )
+    }
   }
 
-  /* 获取base64对象 */
-  getSnapshotBase64(backgroundColor: string) {
+  /**
+   * 获取base64对象
+   * @param backgroundColor string | undefined
+   * @param fileType string | undefined
+   * @returns Promise<SnapshotResponse>
+   */
+  private async getSnapshotBase64(
+    backgroundColor?: string,
+    fileType?: string,
+  ): Promise<SnapshotResponse> {
     const svg = this.getSvgRootElement(this.lf)
+    await updateImageSource(svg as SVGElement)
     return new Promise((resolve) => {
-      this.getCanvasData(svg, backgroundColor).then(
+      this.getCanvasData(svg, { backgroundColor }).then(
         (canvas: HTMLCanvasElement) => {
-          const base64 = canvas.toDataURL('image/png')
+          const base64 = canvas.toDataURL(`image/${fileType ?? 'png'}`)
           // 输出图片数据以及图片宽高
           resolve({
             data: base64,
@@ -105,26 +216,42 @@ export class Snapshot {
     })
   }
 
-  /* 获取Blob对象 */
-  getSnapshotBlob(backgroundColor: string) {
+  /**
+   * 获取Blob对象
+   * @param backgroundColor string | undefined
+   * @param fileType string | undefined
+   * @returns
+   */
+  private async getSnapshotBlob(
+    backgroundColor?: string,
+    fileType?: string,
+  ): Promise<SnapshotResponse> {
     const svg = this.getSvgRootElement(this.lf)
+    await updateImageSource(svg as SVGElement)
     return new Promise((resolve) => {
-      this.getCanvasData(svg, backgroundColor).then(
+      this.getCanvasData(svg, { backgroundColor }).then(
         (canvas: HTMLCanvasElement) => {
-          canvas.toBlob((blob) => {
-            // 输出图片数据以及图片宽高
-            resolve({
-              data: blob,
-              width: canvas.width,
-              height: canvas.height,
-            })
-          }, 'image/png')
+          canvas.toBlob(
+            (blob) => {
+              // 输出图片数据以及图片宽高
+              resolve({
+                data: blob!,
+                width: canvas.width,
+                height: canvas.height,
+              })
+            },
+            `image/${fileType ?? 'png'}`,
+          )
         },
       )
     })
   }
 
-  getClassRules() {
+  /**
+   * 获取脚本css样式
+   * @returns rules string
+   */
+  private getClassRules(): string {
     let rules = ''
     if (this.useGlobalRules) {
       const { styleSheets } = document
@@ -141,37 +268,19 @@ export class Snapshot {
     return rules
   }
 
-  // 获取图片生成中中间产物canvas对象，用户转换为其他需要的格式
-  getCanvasData(
-    svg: SVGGraphicsElement,
-    backgroundColor: string,
-  ): Promise<any> {
-    // TODO: 确认返回 Promise 的类型
-    const copy = svg.cloneNode(true)
-    const graph = copy.lastChild
-    let childLength = graph?.childNodes?.length
-    if (childLength) {
-      for (let i = 0; i < childLength; i++) {
-        const lfLayer = graph?.childNodes[i] as SVGGraphicsElement
-        // 只保留包含节点和边的基础图层进行下载，其他图层删除
-        const layerClassList =
-          lfLayer.classList && Array.from(lfLayer.classList)
-        if (layerClassList && layerClassList.indexOf('lf-base') < 0) {
-          graph?.removeChild(graph.childNodes[i])
-          childLength--
-          i--
-        } else {
-          // 删除锚点
-          const lfBase = graph?.childNodes[i]
-          lfBase &&
-            lfBase.childNodes.forEach((item) => {
-              const element = item as SVGGraphicsElement
-              this.removeAnchor(element.firstChild)
-              this.removeRotateControl(element.firstChild)
-            })
-        }
-      }
-    }
+  /**
+   * 获取图片生成中间产物canvas对象，用户转换为其他需要的格式
+   * @param svg Element
+   * @param toImageOptions ToImageOptions
+   * @returns Promise<HTMLCanvasElement>
+   */
+  private async getCanvasData(
+    svg: Element,
+    toImageOptions: ToImageOptions,
+  ): Promise<HTMLCanvasElement> {
+    const { width, height, backgroundColor, padding = 40 } = toImageOptions
+    const copy = this.cloneSvg(svg, false)
+
     let dpr = window.devicePixelRatio || 1
     if (dpr < 1) {
       // https://github.com/didi/LogicFlow/issues/1222
@@ -187,46 +296,50 @@ export class Snapshot {
       // 当dpr小于1的时候，我们强制转化为1，并不会产生绘制模糊等问题
       dpr = 1
     }
-    const canvas = document.createElement('canvas')
     /*
     为了计算真实宽高需要取图的真实dom
     真实dom存在缩放影响其宽高数值
     在得到真实宽高后除以缩放比例即可得到正常宽高
     */
+
     const base = this.lf.graphModel.rootEl.querySelector('.lf-base')
     const bbox = (base as Element).getBoundingClientRect()
-    const layout = this.lf.container
-      .querySelector('.lf-canvas-overlay')
-      .getBoundingClientRect()
+    const layoutCanvas = this.lf.container.querySelector('.lf-canvas-overlay')!
+    const layout = layoutCanvas.getBoundingClientRect()
     const offsetX = bbox.x - layout.x
     const offsetY = bbox.y - layout.y
     const { graphModel } = this.lf
     const { transformModel } = graphModel
     const { SCALE_X, SCALE_Y, TRANSLATE_X, TRANSLATE_Y } = transformModel
-    // offset值加10，保证图形不会紧贴着下载图片的左边和上边
-    ;(copy.lastChild as SVGGElement).style.transform = `matrix(1, 0, 0, 1, ${
-      (-offsetX + TRANSLATE_X) * (1 / SCALE_X) + 10
-    }, ${(-offsetY + TRANSLATE_Y) * (1 / SCALE_Y) + 10})`
+    ;(copy.lastChild as SVGElement).style.transform = `matrix(1, 0, 0, 1, ${
+      (-offsetX + TRANSLATE_X) * (1 / SCALE_X)
+    }, ${(-offsetY + TRANSLATE_Y) * (1 / SCALE_Y)})`
+    // 包含所有元素的最小宽高
     const bboxWidth = Math.ceil(bbox.width / SCALE_X)
     const bboxHeight = Math.ceil(bbox.height / SCALE_Y)
-    // width,height 值加40，保证图形不会紧贴着下载图片的右边和下边
+    const canvas = document.createElement('canvas')
     canvas.style.width = `${bboxWidth}px`
     canvas.style.height = `${bboxHeight}px`
-    canvas.width = bboxWidth * dpr + 80
-    canvas.height = bboxHeight * dpr + 80
+    // 宽高值 默认加padding 40，保证图形不会紧贴着下载图片
+    canvas.width = bboxWidth * dpr + padding * 2
+    canvas.height = bboxHeight * dpr + padding * 2
     const ctx = canvas.getContext('2d')
     if (ctx) {
+      // 清空canvas
       ctx.clearRect(0, 0, canvas.width, canvas.height)
       ctx.scale(dpr, dpr)
       // 如果有背景色，设置流程图导出的背景色
       if (backgroundColor) {
         ctx.fillStyle = backgroundColor
-        ctx.fillRect(0, 0, bboxWidth * dpr + 80, bboxHeight * dpr + 80)
+        ctx.fillRect(0, 0, canvas.width, canvas.height)
       } else {
-        ctx.clearRect(0, 0, bboxWidth, bboxHeight)
+        ctx.clearRect(0, 0, canvas.width, canvas.height)
       }
     }
+
     const img = new Image()
+
+    // 设置css样式
     const style = document.createElement('style')
     style.innerHTML = this.getClassRules()
     const foreignObject = document.createElement('foreignObject')
@@ -238,26 +351,37 @@ export class Snapshot {
         try {
           if (isFirefox) {
             createImageBitmap(img, {
-              resizeWidth: canvas.width,
-              resizeHeight: canvas.height,
+              resizeWidth:
+                width && height
+                  ? copyCanvas(canvas, width, height).width
+                  : canvas.width,
+              resizeHeight:
+                width && height
+                  ? copyCanvas(canvas, width, height).height
+                  : canvas.height,
             }).then((imageBitmap) => {
-              // 在回调函数中使用 drawImage() 方法绘制图像
-              ctx?.drawImage(imageBitmap, 0, 0)
-              resolve(canvas)
+              ctx?.drawImage(imageBitmap, padding / dpr, padding / dpr)
+              resolve(
+                width && height ? copyCanvas(canvas, width, height) : canvas,
+              )
             })
           } else {
-            ctx?.drawImage(img, 0, 0)
-            resolve(canvas)
+            ctx?.drawImage(img, padding / dpr, padding / dpr)
+            resolve(
+              width && height ? copyCanvas(canvas, width, height) : canvas,
+            )
           }
+          // 如果局部渲染本来是开启的，继续开启
+          // partial && this.lf.graphModel.setPartial(true)
         } catch (e) {
-          ctx?.drawImage(img, 0, 0)
-          resolve(canvas)
+          ctx?.drawImage(img, padding / dpr, padding / dpr)
+          resolve(width && height ? copyCanvas(canvas, width, height) : canvas)
         }
       }
+
       /*
       因为svg中存在dom存放在foreignObject元素中
-      SVG图形转成img对象
-      todo: 会导致一些清晰度问题这个需要再解决
+      svg dom => Base64编码字符串 挂载到img上
       fixme: XMLSerializer的中的css background url不会下载图片
       */
       const svg2Img = `data:image/svg+xml;charset=utf-8,${new XMLSerializer().serializeToString(
@@ -270,6 +394,48 @@ export class Snapshot {
       img.src = imgSrc
     })
   }
+
+  /**
+   * 克隆并处理画布节点
+   * @param svg Node
+   * @returns
+   */
+  private cloneSvg(svg: Element, addStyle: boolean = true): Node {
+    const copy = svg.cloneNode(true)
+    const graph = copy.lastChild
+    let childLength = graph?.childNodes?.length
+    if (childLength) {
+      for (let i = 0; i < childLength; i++) {
+        const lfLayer = graph?.childNodes[i] as SVGGraphicsElement
+        // 只保留包含节点和边的基础图层进行下载，其他图层删除
+        const layerClassList =
+          lfLayer.classList && Array.from(lfLayer.classList)
+        if (layerClassList && layerClassList.indexOf('lf-base') < 0) {
+          graph?.removeChild(graph.childNodes[i])
+          childLength--
+          i--
+        } else {
+          // 删除锚点
+          const lfBase = graph?.childNodes[i]
+          lfBase &&
+            lfBase.childNodes.forEach((item) => {
+              const element = item as SVGGraphicsElement
+              this.removeAnchor(element.firstChild!)
+              this.removeRotateControl(element.firstChild!)
+            })
+        }
+      }
+    }
+    // 设置css样式
+    if (addStyle) {
+      const style = document.createElement('style')
+      style.innerHTML = this.getClassRules()
+      const foreignObject = document.createElement('foreignObject')
+      foreignObject.appendChild(style)
+      copy.appendChild(foreignObject)
+    }
+    return copy
+  }
 }
 
 export default Snapshot