docs: 添加文章内容（2013 ~ 2023）

2025-10-09 00:04:57 +08:00
parent 9a4f04e0c4
commit 49ac48892e
276 changed files with 10537 additions and 1 deletions
--- a/docs/content/canvas-library-fabric-js.md
+++ b/docs/content/canvas-library-fabric-js.md
@@ -0,0 +1,675 @@
+---
+title: Fabric.js 简单介绍和使用
+date: 2025-03-15T22:51:22Z
+lastmod: 2025-03-15T22:55:55Z
+tags: [Web 前端,JavaScript,Canvas,Fabric.js]
+---
+
+# Fabric.js 简单介绍和使用
+
+## 参考资料
+
+- [Fabric.js JSDoc](http://fabricjs.com/docs/)
+- [Fabric.js Demos - Event inspector](http://fabricjs.com/events)
+- [Fabric.js 从入门到________](https://juejin.cn/post/7026941253845516324)
+- [Fabric.js 实用指南](https://blackstarxing.github.io/2019-08-17-fabric-doc.html)
+
+## 简介
+
+Fabric.js 是一个功能强大的 Canvas 库，它在原生 Canvas 之上提供了交互式对象模型、多种易用的 API 和 SVG 解析器等，通过简洁的 API 就可以在画布上进行丰富的操作，并且支持多种的事件方法。
+
+注：本文中使用的 Fabric.js 版本为 v5。
+
+## 常用的对象、属性和方法
+
+### 常用对象
+
+|名称|描述|
+| ------| ------------------------------|
+|`ActiveSelection`|选区|
+|`Group`|分组|
+|`Image`|图像|
+|`Line`|线段|
+|`Rect`|矩形|
+|`Text`|文本（不可编辑，不换行）|
+|`IText`|可编辑文本（可编辑，不换行）|
+|`Textbox`|文本框（可编辑，自动换行）|
+
+### 常用属性
+
+|属性|描述|
+| ------| ---------------------------------------------|
+|`type`|对象类型|
+|`data`|用于添加自定义的数据|
+|`originX`|对象转换的水平原点（left / center / right）|
+|`originY`|对象转换的垂直原点（top / center / bottom）|
+|`left`|水平坐标|
+|`top`|垂直坐标|
+|`width`|宽度|
+|`height`|高度|
+|`angle`|旋转角度|
+|`scaleX`|水平方向缩放倍数|
+|`scaleY`|垂直方向缩放倍数|
+|`stroke`|线段颜色|
+|`strokeWidth`|线段宽度|
+|`fill`|填充颜色|
+|`fontFamily`|文本字体名称|
+|`fontSize`|文本字体大小|
+|`opacity`|对象的不透明度|
+|`borderColor`|选区边框颜色|
+|`borderDashArray`|选区边框虚线样式|
+|`borderOpacityWhenMoving`|选区拖拽时的边框透明度|
+|`cornerColor`|选区 “操作点” 填充颜色|
+|`cornerSize`|选区 “操作点” 大小|
+|`cornerStrokeColor`|选区 “操作点” 描边颜色|
+|`cornerStyle`|选区 “操作点” 样式（circle / rect）|
+|`transparentCorners`|选区 “操作点” 中心是否透明（只有描边）|
+|`hasControls`|是否有 “操作点”|
+|`lockRotation`|是否禁止旋转对象|
+|`lockMovementX`|是否禁止水平移动对象|
+|`lockMovementY`|是否禁止垂直移动对象|
+|`lockScaleX`|是否禁止水平缩放对象|
+|`lockScaleY`|是否禁止垂直缩放对象|
+|`selectable`|是否可以被选中|
+|`hoverCursor`|光标在对象上方时的样式（子对象优先）|
+|`moveCursor`|光标在可移动对象上方时的样式（子对象优先）|
+
+### 常用方法
+
+#### 画布（Canvas）
+
+|方法|描述|
+| ------| ------------------------------------|
+|`add(...object)`|添加对象到画布|
+|`insertAt(object, index, nonSplicing)`|添加对象到画布指定层级|
+|`moveTo(object, index)`|更改对象所在的层级|
+|`remove(...object)`|移除画布上的对象|
+|`discardActiveObject()`|取消选中对象|
+|`getActiveObject()`|获取选中的对象|
+|`setActiveObject()`|更改选中的对象|
+|`getPointer()`|传递事件对象，获取相对于画布的坐标|
+|`fire()`|触发画布事件|
+|`forEachObject()`|遍历画布上的对象|
+|`getZoom()`|获取画布缩放比例|
+|`setZoom()`|设置画布缩放比例|
+|`on()`|监听画布事件|
+|`requestRenderAll()`|刷新画布|
+|`set()`|设置画布属性|
+
+#### 对象（Object）
+
+|方法|描述|
+| ------| ------------------------------|
+|`bringToFront()`|改变对象层级，置顶|
+|`bringForward()`|改变对象层级，上移|
+|`sendBackwards()`|改变对象层级，下移|
+|`sendToBack()`|改变对象层级，置底|
+|`intersectsWithObject()`|检测两个对象是否相交（重叠）|
+|`isContainedWithinObject()`|检测对象是在另外一个对象内|
+|`on()`|监听对象事件|
+|`set()`|设置对象属性|
+|`toDataURL()`|转换为 Base64|
+
+## 创建对象
+
+### 画布
+
+```javascript
+let canvas = new fabric.Canvas({
+  // 画布宽度
+  width: 800,
+  // 画布高度
+  height: 480,
+  // 背景颜色
+  backgroundColor: '#FFFFFF',
+  // 激活对象时不将对象置顶
+  preserveObjectStacking: true,
+  // 选区框样式
+  selectionBorderColor: '#4CAF50',
+  selectionColor: '#4CAF5040',
+  selectionFullyContained: true,
+  selectionLineWidth: 1,
+  // 关闭按比例缩放
+  uniformScaling: false,
+  // 其他配置选项
+  ...
+});
+```
+
+### 矩形
+
+```javascript
+// 创建对象
+let el = new fabric.Rect({
+  left: 100,   // 相对于画布左侧的距离
+  top: 100,    // 相对于画布顶部的距离
+  width: 200,  // 对象宽度 100px
+  height: 100, // 对象高度 100px
+  fill: '#FFFFFF',   // 填充颜色
+  stroke: '#1E88E5', // 边框颜色
+  strokeWidth: 2,    // 边框粗细
+});
+// 添加对象
+canvas.add(el);
+```
+
+### 线段
+
+```javascript
+// 创建对象
+let el = new fabric.Line([
+  100, 100, // 起始点坐标
+  200, 100, // 结束点坐标
+], {
+  stroke: '#1E88E5', // 线段颜色
+  strokeWidth: 2,    // 线段粗细
+});
+// 添加对象
+canvas.add(el);
+```
+
+```javascript
+// 创建对象
+let el = new fabric.Line([], {
+  stroke: '#1E88E5',
+  strokeWidth: 2,
+});
+// 设置位置和长度
+el.set({
+  left: 100,
+  top: 100,
+  width: 100,
+  // 注：因为是线段，高度为 0
+  height: 0,
+});
+// 添加对象
+canvas.add(el);
+```
+
+### 图片
+
+```javascript
+let img = new Image();
+
+// 监听图片加载，加载完成后再添加对象
+img.onload = function() {
+  // 创建对象
+  let el = new fabric.Image(img, {
+    top: 100,
+    left: 100,
+    width: 200,
+    height: 150,
+  });
+  // 添加对象
+  canvas.add(el);
+};
+// 设置 crossorigin 属性，开启 CORS 校验
+//   若不设置，无法将画布或画布上的对象导出为图片。
+//   值设置为 anonymous，表示对此元素的 CORS 请求将不设置凭据标志。
+img.setAttribute('crossorigin', 'anonymous');
+// 设置图片地址
+img.setAttribute('src', 'http://fabricjs.com/assets/69.svg');
+```
+
+### 文本框
+
+```javascript
+// 创建对象
+let el = new fabric.Textbox('文本内容', {
+  top: 100,
+  left: 100,
+  // 设置宽度后，文本内容超出宽度后会自动换行。
+  // 注意：文本只会在空格处自动换行。
+  // 高度为自适应，不需要设置。
+  width: 200,
+});
+// 添加对象
+canvas.add(el);
+```
+
+## 场景和实现方法
+
+### 画布内容撤销、恢复
+
+主要通过 Fabric.js 画布对象的 `toObject()` 和 `loadFromJSON()` 方法实现。
+
+为了提高性能，默认情况下 `toObject()` 只会导出对象上**常用**的属性，其他属性（例如 `data`、`selectable`）不会被导出，需要手动在其 `propertiesToInclude` 参数中指定（例如 `canvas.toObject(['data', 'selectable'])`）。
+
+### 画布内容导出为图片
+
+将画布（显示区域）或对象导出为图片：
+
+```javascript
+toDataURL(options)
+```
+
+参数：options（可选）
+
+|属性名|数据类型|默认值|简介|
+| ---------------------| ----------| --------| -----------------------------------------|
+|format|String|png|导出图片的格式，可选值：jpeg、png|
+|quality|Number|1|图片质量（0 \~ 1），仅 jpeg 格式可用|
+|multiplier|Number|1|缩放比例|
+|left|Number||裁剪左偏移量（1.2.14+）|
+|top|Number||裁剪上偏移量（1.2.14+）|
+|width|Number||裁剪宽度（1.2.14+）|
+|height|Number||裁剪高度（1.2.14+）|
+|enableRetinaScaling|Boolean||为克隆图像启用 Retina 缩放（2.0.0+）|
+
+用法示例：
+
+```javascript
+let dataURL = canvas.toDataURL({
+  format: 'jpeg',
+  quality: 0.8,
+});
+```
+
+```javascript
+let dataURL = rect.toDataURL({
+  format: 'png',
+});
+```
+
+注意：
+
+若导出的对象中包含使用 URL（非 DataURL）加载的图片对象，需要使用 `crossOrigin` 属性解决资源跨域问题，否则会出现以下错误提示：
+
+```plaintext
+The canvas has been tainted by cross-origin data.
+```
+
+其中一种解决方式是先使用 `new Image()` 设置 `crossorigin` 属性，加载图片，再创建 `fabric.Image` 对象（参考 “创建对象 - 图片”）。
+
+### 画布自适应父 DOM 元素宽高
+
+#### 方案一：监听浏览器窗口大小变化事件
+
+```javascript
+// 父元素（DOM）
+let el = vm.$el;
+// 画布对象
+let canvas = vm.canvasInstance;
+// 防抖定时器
+let debounce = null;
+
+// 事件处理函数
+const handler = function () {
+  clearTimeout(debounce);
+  debounce = setTimeout(() => {
+    if (canvas) {
+      // 设置宽高
+      canvas.setWidth(el.clientWidth);
+      canvas.setHeight(el.clientHeight);
+      // 刷新画布（正常情况下设置宽高后会自动刷新）
+      // canvas.requestRenderAll();
+    } else {
+      console.error('处理失败，画布对象不存在！');
+    }
+  }, 500);
+};
+
+// 添加事件监听
+window.addEventListener('resize', handler);
+
+// 移除事件监听
+window.removeEventListener('resize', handler);
+clearTimeout(debounce);
+```
+
+#### 方案二：使用 ResizeObserver 监听 DOM 元素大小更改
+
+参考资料：[ResizeObserver - Web API 接口参考 | MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/ResizeObserver)
+
+方案优点：在窗口大小不变化的情况下也能实现自适应
+
+```javascript
+// 父元素（DOM）
+let el = vm.$el;
+// 画布对象
+let canvas = vm.canvasInstance;
+// 防抖定时器
+let debounce = null;
+
+/**
+ * @desc 观察器回调函数
+ * @type {ResizeObserverCallback}
+ */
+const handler = function (entries) {
+  clearTimeout(debounce);
+  debounce = setTimeout(() => {
+    const entry = entries[0];
+
+    if (canvas && entry) {
+      const { width, height } = entry.contentRect;
+      // 设置宽高
+      canvas.setWidth(width);
+      canvas.setHeight(height);
+      // 刷新画布（正常情况下设置宽高后会自动刷新）
+      // canvas.requestRenderAll();
+    } else {
+      console.error('处理失败，Canvas 或 ResizeObserverEntry 不存在！');
+    }
+  }, 500);
+};
+
+/**
+ * @desc 观察器配置选项
+ * @type {ResizeObserverOptions}
+ */
+const options = {
+  // 设置观察器以哪种盒子模型来观察变化
+  //   可选值：content-box（默认）、border-box、device-pixel-content-box
+  box: 'border-box',
+};
+
+// 创建观察器，并传递回调函数
+const observer = new ResizeObserver(handler);
+
+// 传递配置选项
+observer.observe(el, options);
+
+// 停止观察器
+observer.disconnect();
+clearTimeout(debounce);
+```
+
+### 解决画布缩放后，对象显示模糊
+
+把对象的 `objectCaching` 属性设置为 `false`，关闭缓存即可。
+
+例如：
+
+```javascript
+const rect = new fabric.Rect({
+  left: 100,
+  top: 100,
+  width: 200,
+  height: 200,
+  fill: '#FFFFFF',
+  stroke: '#66CCFF',
+  strokeWidth: 2,
+  objectCaching: false,
+});
+
+canvas.add(rect);
+```
+
+注意：不建议大量使用，以免影响性能。
+
+### 实现对象溢出隐藏（裁剪）效果
+
+主要用到了 `clipPath` 功能，设置对象的裁剪路径。
+
+```javascript
+// 创建用于作为“容器”的对象
+const container = new fabric.Rect({
+  left: 0,
+  top: 0,
+  width: 800,
+  height: 480,
+  fill: '#FFFFFF',
+  stroke: '#000000',
+  strokeWidth: 2,
+  // 将该属性设置为 true 后，裁剪的区域会动态更新
+  absolutePositioned: true,
+});
+
+// 创建子对象
+const item = new fabric.Rect({
+  left: 100,
+  top: 100,
+  width: 200,
+  height: 100,
+  fill: '#FFFFFF',
+  stroke: '#66CCFF',
+  strokeWidth: 2,
+  // 将 container 对象设为该对象的 clipPath
+  clipPath: container,
+});
+```
+
+**关于** **`absolutePositioned`** **属性：**
+
+仅当对象作为 `clipPath` 使用时才有意义。如果为 `true`，`clipPath` 的位置将会相对于画布，且不受对象变换影响。（[JSDoc: Class: Object#absolutePositioned](http://fabricjs.com/docs/fabric.Object.html#absolutePositioned)）
+
+**注意：**
+
+后续通过 `.set()` 更新对象的 `clipPath` 属性时，建议同时将其 `dirty` 属性设置为 `true`，以便清除缓存，防止裁剪区域没有更新。（[JSDoc: Class: Object#dirty](http://fabricjs.com/docs/fabric.Object.html#dirty)）
+
+```javascript
+item.set({ clipPath: null, dirty: true });
+```
+
+### 鼠标滚轮缩放画布
+
+主要用到了画布的鼠标事件（`mouse:wheel`）以及调用画布的 `zoomToPoint()` 方法改变视图缩放。
+
+```javascript
+// 监听事件：鼠标滚轮
+canvas.on('mouse:wheel', function (ev) {
+
+  const evt = ev.e;
+  const cursorX = evt.offsetX;
+  const cursorY = evt.offsetY;
+
+  // 若按下 Ctrl 键，则为缩放
+  if (evt.ctrlKey) {
+    evt.preventDefault();
+  } else {
+    return;
+  }
+
+  // 若按下 Alt 键，则为重置缩放
+  if (evt.altKey) {
+    canvas.zoomToPoint({
+      x: cursorX,
+      y: cursorY,
+    }, 1);
+    return;
+  }
+
+  // 正数：向下滚动
+  // 负数：向上滚动
+  const delta = evt.deltaY;
+
+  // 画布当前缩放值
+  let zoom = canvas.getZoom();
+  let min = 0.1;
+  let max = 10;
+
+  zoom += zoom * (delta > 0 ? -0.2 : 0.2);
+
+  // 限制缩放范围
+  (zoom < min) && (zoom = min);
+  (zoom > max) && (zoom = max);
+
+  // 设置画布缩放比例
+  // 参数1：将画布的缩放点设置为鼠标当前位置
+  // 参数2：传入缩放值
+  canvas.zoomToPoint({
+    x: cursorX,
+    y: cursorY,
+  }, zoom);
+
+});
+```
+
+### 鼠标拖拽移动画布
+
+主要用到了画布的鼠标事件（`mouse:down`、`mouse:move` 和 `mouse:up`）以及调用画布的 `setViewportTransform()` 方法改变视图偏移量。
+
+注意：在拖拽前，若鼠标选中了对象，需要将对象的 `lockMovementX` 和 `lockMovementY` 属性设置为 `true`，锁定对象的移动，否则拖拽后对象的位置会变化。
+
+```javascript
+// 监听事件：鼠标按下
+canvas.on('mouse:down', function ({ e: evt, target }) {
+
+  // 仅在按下了 Ctrl 键时为拖拽画布
+  if (!evt.ctrlKey) {
+    return;
+  }
+
+  if (target) {
+    if (target.lockMovementX || target.lockMovementY) {
+      // 记录原始锁定状态
+      target.isLock = true;
+    } else {
+      // 记录原始锁定状态
+      target.isLock = false;
+      // 锁定对象的移动
+      target.set({
+        lockMovementX: true,
+        lockMovementY: true,
+      });
+    }
+  }
+
+  canvas.set({
+    // 关闭选区框
+    selection: false,
+    // 自定义属性，标记拖拽状态
+    isDragCanvas: true,
+    // 自定义属性，记录起始位置
+    startPosX: evt.clientX,
+    startPosY: evt.clientY,
+    startVpt: [...canvas.viewportTransform],
+  });
+
+});
+
+// 监听事件：鼠标移动
+canvas.on('mouse:move', function (ev) {
+  // 检测是否为拖拽画布模式
+  if (canvas.isDragCanvas) {
+    const evt = ev.e;
+    const vptOld = canvas.startVpt;
+    const vptNew = [...vptOld];
+
+    // 计算新的偏移量
+    vptNew[4] += (evt.clientX - canvas.startPosX);
+    vptNew[5] += (evt.clientY - canvas.startPosY);
+
+    // 更新视图偏移量
+    canvas.setViewportTransform(vptNew);
+  }
+});
+
+// 监听事件：鼠标松开
+canvas.on('mouse:up', function ({ target }) {
+  // 解锁对象的移动（如果可以）
+  if (target && !target.isLock) {
+    target.set({
+      lockMovementX: false,
+      lockMovementY: false,
+    });
+  }
+  // 更新画布属性
+  canvas.set({
+    // 开启选区框
+    selection: true,
+    // 自定义属性，标记拖拽状态
+    isDragCanvas: false,
+  });
+});
+```
+
+### 鼠标事件中获取分组（Group）内的目标对象
+
+默认情况下，对于分组，`ev.target` 只能获取到整个分组，并不能具体到其中的对象。
+
+在创建分组时，将 `subTargetCheck` 属性设置为 `true`，即可通过 `ev.subTargets` 获取触发事件时的子对象。
+
+对于支持该功能的事件（`mouse:down`、`mouse:up`、`mouse:move` 等），该属性为 `fabric.Object` 数组；
+
+对于不支持该功能的事件，该属性为 `undefined`。
+
+例如：
+
+```javascript
+const group = new fabric.Group([obj1, obj2], {
+  subTargetCheck: true,
+  ...
+});
+
+canvas.add(group);
+
+canvas.on('mouse:down', function (ev) {
+  console.log(ev.subTargets);
+});
+```
+
+### 文本框强制自动换行
+
+Fabeic.js 的文本框对象（Textbox）默认支持文本自动换行，但只能在**空格**处换行，对于类似中文句子这种不带空格的字符串并不会换行，且文本框的宽度会自动被撑开。
+
+在 Fabric.js 2.6.0 版本中，新增了一个 `splitByGrapheme` 属性，将其设置为 `true` 即可启用在任意字符之间自动换行（参考：[JSDoc: Global](http://fabricjs.com/docs/global.html#splitByGrapheme)），例如：
+
+```javascript
+const textbox = new fabric.Textbox('文本框', {
+  left: 100,
+  top: 100,
+  width: 200,
+  splitByGrapheme: true,
+});
+
+canvas.add(textbox);
+```
+
+### 选中并聚焦对象（将对象置于视图的中心）
+
+```javascript
+// 获取对象的中心点坐标
+//   坐标值相对于画布左上角起始点
+//   坐标值不受缩放比例影响
+const {
+  x: elCenterX,
+  y: elCenterY,
+} = el.getCenterPoint();
+
+// 获取画布当前的缩放比例
+const zoom = canvas.getZoom();
+
+// 计算新的视图坐标
+//   中心点坐标值需要与画布缩放比例相乘，与视图统一
+//   画布坐标的起始点在左上角，坐标值需要减去画布宽高的一半
+const point = {
+  x: elCenterX * zoom - canvas.width / 2,
+  y: elCenterY * zoom - canvas.height / 2,
+};
+
+// 移动视图
+canvas.absolutePan(point);
+// 选中对象
+canvas.setActiveObject(el);
+```
+
+### 选中多个对象，创建选区
+
+主要用到了 Fabric.js 的 `ActiveSelection` 对象，手动创建选区：
+
+```javascript
+// 画布对象
+const canvas = this.canvasInstance;
+
+// 选区中包含的对象
+const items = [a, b, c, ...];
+
+// 新建一个选区对象
+const sel = new fabric.ActiveSelection(items, {
+  // 选区所属的画布
+  //   必须包含该参数，否则会出现奇怪的问题（不会报错）
+  canvas,
+  // 其他配置选项，例如：
+  //  borderColor,
+  //  borderDashArray,
+  //  opacity,
+  //  hasControls,
+  ...
+});
+
+// 使选区生效
+canvas.setActiveObject(sel);
+```
+
+‍