feat: 画布导出的安全系数和安全边距支持配置 fix #2213

Author: DymoneLewis

examples/feature-examples/src/pages/extensions/snapshot/index.tsx

@@ -76,6 +76,20 @@ export default function SnapshotExample() {
  const [quality, setQuality] = useState<number>() // 图片质量
  const [partial, setPartial] = useState<boolean>(false) // 导出局部渲染
 
+ // 快照插件样式控制
+ const [useGlobalRules, setUseGlobalRules] = useState<boolean>(true) // 是否注入全局样式
+ const [customCssRules, setCustomCssRules] = useState<string>(`
+ .uml-wrapper {
+ line-height: 1.2;
+ text-align: center;
+ color: blue;
+ }
+ `) // 自定义样式规则，将叠加到导出图片中
+
+ // 画布尺寸安全参数
+ const [safetyFactor, setSafetyFactor] = useState<number>(1.1) // 画布导出安全系数
+ const [safetyMargin, setSafetyMargin] = useState<number>(40) // 画布导出安全边距
+
  const [blobData, setBlobData] = useState('')
  const [base64Data, setBase64Data] = useState('')
 
@@ -118,16 +132,12 @@ export default function SnapshotExample() {
  })
  })
 
- // 默认开启css样式
- lf.extension.snapshot.useGlobalRules = true
- // 不会覆盖css样式，会叠加，customCssRules优先级高
- lf.extension.snapshot.customCssRules = `
- .uml-wrapper {
- line-height: 1.2;
- text-align: center;
- color: blue;
- }
- `
+ // 设置快照插件样式参数（通过类型断言访问扩展实例属性）
+ const snapshotExt = lf.extension?.snapshot as unknown as Snapshot
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules
+ snapshotExt.customCssRules = customCssRules
+ }
 
  lf.render(data)
  lf.translateCenter()
@@ -146,8 +156,17 @@ export default function SnapshotExample() {
  height,
  padding,
  quality,
+ safetyFactor,
+ safetyMargin,
  }
  console.log(params, 'params')
+ // 在导出前更新快照扩展的样式控制参数
+ const snapshotExt = lfRef.current?.extension
+ ?.snapshot as unknown as Snapshot
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules
+ snapshotExt.customCssRules = customCssRules
+ }
  await lfRef.current?.getSnapshot(fileName, params)
  // await lfRef.current?.extension.snapshot?.getSnapshot(fileName, params)
  // 测试
@@ -172,6 +191,15 @@ export default function SnapshotExample() {
  height,
  padding,
  quality,
+ safetyFactor,
+ safetyMargin,
+ }
+ // 在预览前更新快照扩展的样式控制参数
+ const snapshotExt = lfRef.current.extension
+ ?.snapshot as unknown as Snapshot
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules
+ snapshotExt.customCssRules = customCssRules
  }
  lfRef.current
  .getSnapshotBlob(backgroundColor, fileType, params)
@@ -204,6 +232,15 @@ export default function SnapshotExample() {
  height,
  padding,
  quality,
+ safetyFactor,
+ safetyMargin,
+ }
+ // 在预览前更新快照扩展的样式控制参数
+ const snapshotExt = lfRef.current.extension
+ ?.snapshot as unknown as Snapshot
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules
+ snapshotExt.customCssRules = customCssRules
  }
  const result = await lfRef.current.getSnapshotBase64(
  'white',
@@ -287,6 +324,16 @@ export default function SnapshotExample() {
  value={height}
  onChange={(value) => handleInputChange(value, 'height')}
  />
+ <InputNumber
+ addonBefore="安全系数："
+ value={safetyFactor}
+ onChange={(value) => setSafetyFactor(value ?? 1.1)}
+ />
+ <InputNumber
+ addonBefore="安全边距："
+ value={safetyMargin}
+ onChange={(value) => setSafetyMargin(value ?? 40)}
+ />
  </Space>
  <p></p>
  <Space>
@@ -307,6 +354,20 @@ export default function SnapshotExample() {
  />
  <span>导出局部渲染：</span>
  <Switch onChange={(partial) => setPartial(partial)} />
+ <span>注入全局样式：</span>
+ <Switch
+ checked={useGlobalRules}
+ onChange={(checked) => setUseGlobalRules(checked)}
+ />
+ </Space>
+ <p></p>
+ <Space style={{ width: '100%' }} direction="vertical">
+ <Input.TextArea
+ rows={4}
+ placeholder="自定义导出样式，支持标准CSS语法"
+ value={customCssRules}
+ onChange={(e) => setCustomCssRules(e.target.value)}
+ />
  </Space>
  <Divider />
  <Space>

packages/extension/src/tools/snapshot/index.ts

@@ -35,6 +35,14 @@ export type ToImageOptions = {
  * - `true`：只导出画面区域内的可见元素
  */
  partial?: boolean
+ /**
+ * 导出图片时的安全系数，用于确保导出的图片能够容纳所有元素，默认值为 1.1
+ */
+ safetyFactor?: number
+ /**
+ * 导出图片时的安全边距，用于确保导出的图片能够容纳所有元素，默认值为 40
+ */
+ safetyMargin?: number
 }
 
 // Blob | base64
@@ -381,7 +389,7 @@ export class Snapshot {
  // 计算实际宽高，考虑缩放因素
  // 在宽画布情况下，getBoundingClientRect可能无法获取到所有元素的边界
  // 因此我们添加一个安全系数来确保能够容纳所有元素
- const safetyFactor = 1.1 // 安全系数，增加20%的空间
+ const safetyFactor = toImageOptions.safetyFactor || 1.1 // 安全系数，增加10%的空间
  const actualWidth = (bbox.width / SCALE_X) * safetyFactor
  const actualHeight = (bbox.height / SCALE_Y) * safetyFactor
 
@@ -394,7 +402,7 @@ export class Snapshot {
 
  // 宽高值 默认加padding 40，保证图形不会紧贴着下载图片
  // 为宽画布添加额外的安全边距，确保不会裁剪
- const safetyMargin = 40 // 额外的安全边距
+ const safetyMargin = toImageOptions.safetyMargin || 40 // 额外的安全边距
 
  // 获取当前浏览器类型，不同浏览器对canvas的限制不同
  const { maxCanvasDimension, otherMaxCanvasDimension } =

sites/docs/docs/tutorial/extension/snapshot.en.md

@@ -6,7 +6,6 @@ group:
 title: Snapshot
 order: 6
 toc: content
-tag: Optimization
 ---
 
 We often need to export the canvas content as an image. LogicFlow provides an independent plug-in package `Snapshot` to support exporting the canvas as an image.
@@ -53,15 +52,17 @@ In version 2.0, we have comprehensively upgraded the export functionality:
 
 The export method supports the `toImageOptions` parameter with the following configuration options:
 
-| Property Name | Type | Default Value | Description |
-| ------------- | ---- | ------------- | ----------- |
-| fileType | string | png | Export format: `png`, `webp`, `jpeg`, `svg` |
-| width | number | - | Image width (may cause image stretching) |
-| height | number | - | Image height (may cause image stretching) |
-| backgroundColor | string | - | Background color, transparent by default |
-| quality | number | 0.92 | Image quality, only effective for `jpeg` and `webp`, value range 0-1 |
-| padding | number | 40 | Inner margin, in pixels |
-| partial | boolean | false | Whether to export only the visible area |
+| Property Name | Type | Default Value | Description |
+| --------------- | ------- | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| fileType | string | png | Export format: `png`, `webp`, `jpeg`, `svg` |
+| width | number | - | Image width (may cause image stretching) |
+| height | number | - | Image height (may cause image stretching) |
+| backgroundColor | string | - | Background color, transparent by default |
+| quality | number | 0.92 | Image quality, only effective for `jpeg` and `webp`, value range 0-1 |
+| padding | number | 40 | Inner margin, in pixels |
+| partial | boolean | false | Whether to export only the visible area |
+| safetyFactor | number | 1.1 | Safety factor: for wide canvas scenarios, enlarges the export bounds proportionally to ensure all elements are included |
+| safetyMargin | number | 40 | Safety margin: extra margin for wide canvas scenarios to avoid cropping |
 
 :::warning{title=Notes}
 - SVG format does not support `width`, `height`, `backgroundColor`, `padding` attributes
@@ -70,6 +71,9 @@ The export method supports the `toImageOptions` parameter with the following con
 - During export, silent mode will be automatically enabled, disabling canvas interaction
 - Automatically converts relative path images in SVG to Base64 encoding <Badge type="warning">2.0.14 New</Badge>
 - When the image exceeds the browser's canvas limit, it will automatically scale the image size to ensure successful export, but it will affect image clarity
+- You can fine-tune wide canvas behavior via `safetyFactor` and `safetyMargin` to avoid element cropping
+- If `partial` is not explicitly provided, it defaults to the current canvas partial rendering state; during export, the rendering mode may be temporarily switched and will be restored afterward
+- Anchors and rotate controls are automatically removed during export to prevent auxiliary elements from appearing in the image
 :::
 
 ### Custom CSS Styles

sites/docs/docs/tutorial/extension/snapshot.zh.md

@@ -6,7 +6,6 @@ group:
 title: 导出图片 (Snapshot)
 order: 6
 toc: content
-tag: 优化
 ---
 
 我们常常有需要将画布内容以图片的形式导出来的情况，因此LogicFlow提供了一个独立的插件包 `Snapshot` 以支持用户将画布导出为图片。
@@ -52,15 +51,17 @@ lf.getSnapshot('流程图');
 
 导出方法支持`toImageOptions`参数，提供以下配置项：
 
-| 属性名 | 类型 | 默认值 | 描述 |
-| --------------- | ------- | ------ | ----------------------------------------- |
-| fileType | string | png | 导出格式：`png`、`webp`、`jpeg`、`svg` |
-| width | number | - | 图片宽度（可能导致图形拉伸） |
-| height | number | - | 图片高度（可能导致图形拉伸） |
-| backgroundColor | string | - | 背景色，默认透明 |
-| quality | number | 0.92 | 图片质量，仅对`jpeg`和`webp`有效，取值0-1 |
-| padding | number | 40 | 内边距，单位像素 |
-| partial | boolean | false | 是否只导出可见区域 |
+| 属性名 | 类型 | 默认值 | 描述 |
+| --------------- | ------- | ------ | ---------------------------------------------------------------------- |
+| fileType | string | png | 导出格式：`png`、`webp`、`jpeg`、`svg` |
+| width | number | - | 图片宽度（可能导致图形拉伸） |
+| height | number | - | 图片高度（可能导致图形拉伸） |
+| backgroundColor | string | - | 背景色，默认透明 |
+| quality | number | 0.92 | 图片质量，仅对`jpeg`和`webp`有效，取值0-1 |
+| padding | number | 40 | 内边距，单位像素 |
+| partial | boolean | false | 是否只导出可见区域 |
+| safetyFactor | number | 1.1 | 安全系数：用于宽画布场景，导出时按比例扩大画布边界，确保所有元素被包含 |
+| safetyMargin | number | 40 | 安全边距：用于宽画布场景，导出时额外增加边距，避免被裁剪 |
 
 :::warning{title=注意事项}
 - 导出SVG格式的图片时不支持`width`、`height`、`backgroundColor`、`padding`属性
@@ -69,6 +70,9 @@ lf.getSnapshot('流程图');
 - 导出过程中会自动开启静默模式，禁用画布交互
 - 自动将SVG中的相对路径图片转换为Base64编码<Badge type="warning">2.0.14新增</Badge> 
 - 导出图片超过浏览器对canvas限制时，会自动缩放图片尺寸，确保导出成功，但会影响图片清晰度
+- 可通过 `safetyFactor` 与 `safetyMargin` 精细调整宽画布的安全余量，避免元素裁剪
+- `partial` 未显式传入时，默认沿用当前画布的局部渲染状态；导出期间如需切换渲染模式会临时切换并在导出完成后还原
+- 导出时会自动移除锚点与旋转控件，避免辅助元素进入图片
 :::
 
 ### 自定义CSS样式

sites/docs/examples/extension/native/demo/snapshot.tsx

@@ -1,4 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
+
+declare const insertCss: (css: string) => void;
 import {
  Button,
  Col,
@@ -222,7 +224,19 @@ const SnapshotExample: React.FC = () => {
  const [backgroundColor, setBackgroundColor] = useState<string>('white'); // 背景颜色
  const [padding, setPadding] = useState<number>(); //padding
  const [quality, setQuality] = useState<number>(); // 图片质量
- const [partial, setPartial] = useState<boolean>(true); // 导出局部渲染
+ const [partial, setPartial] = useState<boolean>(false); // 导出局部渲染
+
+ // 快照插件样式控制
+ const [useGlobalRules, setUseGlobalRules] = useState<boolean>(true); // 是否注入全局样式
+ const [customCssRules, setCustomCssRules] = useState<string>(`.uml-wrapper {
+ line-height: 1.2;
+ text-align: center;
+ color: blue;
+ }`); // 自定义样式规则，将叠加到导出图片中
+
+ // 画布尺寸安全参数
+ const [safetyFactor, setSafetyFactor] = useState<number>(1.1); // 画布导出安全系数
+ const [safetyMargin, setSafetyMargin] = useState<number>(40); // 画布导出安全边距
 
  const [blobData, setBlobData] = useState('');
  const [base64Data, setBase64Data] = useState('');
@@ -259,16 +273,12 @@ const SnapshotExample: React.FC = () => {
  });
  });
 
- // 默认开启css样式
- lf.extension.snapshot.useGlobalRules = true;
- // 不会覆盖css样式，会叠加，customCssRules优先级高
- lf.extension.snapshot.customCssRules = `
- .uml-wrapper {
- line-height: 1.2;
- text-align: center;
- color: blue;
- }
- `;
+ // 设置快照插件样式参数（通过类型断言访问扩展实例属性）
+ const snapshotExt = lf.extension?.snapshot;
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules;
+ snapshotExt.customCssRules = customCssRules;
+ }
 
  lf.render(data);
  lf.translateCenter();
@@ -287,8 +297,16 @@ const SnapshotExample: React.FC = () => {
  height,
  padding,
  quality,
+ safetyFactor,
+ safetyMargin,
  };
  console.log(params, 'params');
+ // 在导出前更新快照扩展的样式控制参数
+ const snapshotExt = lfRef.current?.extension?.snapshot;
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules;
+ snapshotExt.customCssRules = customCssRules;
+ }
  await lfRef.current?.getSnapshot(fileName, params);
  };
 
@@ -304,7 +322,15 @@ const SnapshotExample: React.FC = () => {
  height,
  padding,
  quality,
+ safetyFactor,
+ safetyMargin,
  };
+ // 在预览前更新快照扩展的样式控制参数
+ const snapshotExt = lfRef.current.extension?.snapshot;
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules;
+ snapshotExt.customCssRules = customCssRules;
+ }
  lfRef.current
  .getSnapshotBlob(backgroundColor, fileType, params)
  .then(
@@ -336,7 +362,15 @@ const SnapshotExample: React.FC = () => {
  height,
  padding,
  quality,
+ safetyFactor,
+ safetyMargin,
  };
+ // 在预览前更新快照扩展的样式控制参数
+ const snapshotExt = lfRef.current.extension?.snapshot;
+ if (snapshotExt) {
+ snapshotExt.useGlobalRules = useGlobalRules;
+ snapshotExt.customCssRules = customCssRules;
+ }
  lfRef.current
  .getSnapshotBase64(backgroundColor, fileType, params)
  .then(
@@ -428,6 +462,16 @@ const SnapshotExample: React.FC = () => {
  value={height}
  onChange={(value) => handleInputChange(value, 'height')}
  />
+ <InputNumber
+ addonBefore="安全系数："
+ value={safetyFactor}
+ onChange={(value) => setSafetyFactor(value ?? 1.1)}
+ />
+ <InputNumber
+ addonBefore="安全边距："
+ value={safetyMargin}
+ onChange={(value) => setSafetyMargin(value ?? 40)}
+ />
  </Space>
  <p></p>
  <Space>
@@ -447,7 +491,21 @@ const SnapshotExample: React.FC = () => {
  onChange={(value) => handleInputChange(value, 'quality')}
  />
  <span>导出局部渲染：</span>
- <Switch defaultChecked onChange={(partial) => setPartial(partial)} />
+ <Switch checked={partial} onChange={(checked) => setPartial(checked)} />
+ <span>注入全局样式：</span>
+ <Switch
+ checked={useGlobalRules}
+ onChange={(checked) => setUseGlobalRules(checked)}
+ />
+ </Space>
+ <p></p>
+ <Space style={{ width: '100%' }} direction="vertical">
+ <Input.TextArea
+ rows={4}
+ placeholder="自定义导出样式，支持标准CSS语法"
+ value={customCssRules}
+ onChange={(e) => setCustomCssRules(e.target.value)}
+ />
  </Space>
  <Divider />
  <Space>