Fabric.js 快速上手：画布初始化与基本对象操作

作者：竹影

时间：2026-11-04

本文系统讲解 Fabric.js 的快速上手指南，涵盖环境引入、画布初始化（对比交互式 Canvas 与静态 StaticCanvas 的架构差异）、基础几何图形与文本对象的创建、属性调整以及核心重绘机制。

文章目录

前端图形技术 Canvas 封装库阅读时长：约 6 分钟

在浏览器中开发图形编辑器、海报生成工具或数据标注界面时，原生 HTML5 Canvas 往往需要手动管理像素、坐标计算与事件碰撞检测。Fabric.js 在 Canvas 之上构建了一套完整的面向对象模型，把绘制操作转化为可拖拽、缩放、旋转与样式更新的对象实体。本文介绍 Fabric.js 的核心快速上手流程，重点拆解画布初始化（Canvas 与 StaticCanvas 的选择）以及基础几何与文本对象的创建、样式设置与渲染机制。

Fabric.js 快速上手：画布初始化与基本对象操作 — 图 0：Fabric.js 交互式画布与对象模型工作区概念概览

一、环境准备与 DOM 声明

使用 Fabric.js 最快的方式是通过官方 CDN 引入脚本，或者在前端工程项目中通过包管理器安装。在 HTML 中只需要声明一个标准的 <canvas> 标签，并指定明确的 id 与几何宽高。

1. 引入脚本库

在现代工程中可以通过 npm 安装，在纯静态演示页面中也可以直接引入单文件构建包：

<!-- 方式 A：CDN 引入 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>

<!-- 方式 B：npm / yarn 安装（工程化项目） -->
npm install fabric --save

2. 编写 Canvas 容器

在页面中放置画布元素时，必须在 HTML 标签属性中指定宽度和高度，而不是仅通过 CSS 样式进行缩放：

<canvas id="c" width="800" height="500"></canvas>

避坑提示：避免使用类似 style="width: 800px; height: 500px;" 的方式为 Canvas 设置尺寸。HTML 属性 width/height 决定的是底层位图的物理像素网格；而 CSS 的宽和高仅是元素在页面布局中的显示尺寸。如果只设置 CSS 尺寸，Canvas 默认将以 300×150 像素进行拉伸，导致绘制出来的图形严重变形模糊，交互点击位置也会发生错位。

二、画布初始化：Canvas 与 StaticCanvas 的选择

Fabric.js 提供了两个核心画布类：fabric.Canvas 与 fabric.StaticCanvas。虽然两者都能完成图形绘制与对象管理，但它们的底层实现、DOM 结构和性能开销存在显著差异。

1. 关键差异与内部架构解析

为了直观评估两者的差异，我们从结构与机制层面进行对比：

对比维度	fabric.Canvas（交互式）	fabric.StaticCanvas（静态）
DOM 架构	生成包裹容器 `.canvas-container`，内含下层绘制层 `lower-canvas` 与上层交互捕获层 `upper-canvas`	保持单个原生 `<canvas>` 节点，无外层容器，无额外 DOM 生成
事件与交互	完整支持鼠标/手势拖拽、多选框拉取、旋转与 8 方向缩放手柄	完全剥离交互事件监听与控制手柄逻辑，纯粹静态展示
运行时开销	事件侦听器多、内存占用相对较高，适用于动态创作场景	内存和 CPU 消耗极低，渲染性能更高
典型使用场景	海报设计器、图片涂鸦标注、可交互白板、可编辑图表	静态仪表盘、生成缩略图、只读图纸预览、Node.js 服务端出图

2. 代码初始化示例

实例化时将 HTML 中的元素 ID 作为第一个参数传入，第二个参数为配置项：

// 场景 1：如果需要让用户可点击、拖拽和缩放图形
const canvas = new fabric.Canvas('c', {
  backgroundColor: '#F8FAFC', // 画布背景色
  selection: true,             // 允许框选多个对象
  preserveObjectStacking: true // 选中对象时保持原有图层顺序，不自动置顶
});

// 场景 2：如果仅用于只读展示或服务端渲染导出
const staticCanvas = new fabric.StaticCanvas('c', {
  backgroundColor: '#F8FAFC'
});

为什么理解这个差异非常重要？如果在只需要展示折线图或数据卡片的报表页面中错误地使用了 fabric.Canvas，浏览器会为每个实例创建两层 Canvas 和数十个全局事件监听，造成不必要的内存浪费；反之，若在需要拖拽的编辑器中初始化了 fabric.StaticCanvas，则任何鼠标事件都不会触发。

三、基本图形对象的创建与挂载

在原生 Canvas 中，绘制矩形需要调用 ctx.fillRect(x, y, w, h)，绘制完成后该矩形即变成死像素，无法再次获取或修改其位置。而在 Fabric.js 中，一切皆为对象（继承自 fabric.Object）。你只需创建对象实例，并将其添加到画布中。

1. 创建常用内置图元

Fabric.js 提供了包括矩形、圆形、三角形和文本在内的多种基础类：

// 1. 创建矩形 (fabric.Rect)
const rect = new fabric.Rect({
  left: 60,          // 距离画布左边缘距离 (px)
  top: 50,           // 距离画布上边缘距离 (px)
  width: 140,        // 矩形宽度
  height: 90,        // 矩形高度
  fill: '#879B88',   // 填充颜色
  stroke: '#687D8D', // 描边颜色
  strokeWidth: 2,    // 描边粗细
  rx: 6,             // X 轴圆角半径
  ry: 6              // Y 轴圆角半径
});

// 2. 创建圆形 (fabric.Circle)
const circle = new fabric.Circle({
  left: 240,
  top: 50,
  radius: 45,        // 半径
  fill: '#687D8D',
  opacity: 0.85      // 透明度 (0 ~ 1)
});

// 3. 创建可编辑文本 (fabric.IText)
const text = new fabric.IText('双击我输入文本', {
  left: 60,
  top: 170,
  fontSize: 18,
  fontFamily: 'sans-serif',
  fill: '#2C3E50'
});

2. 将对象添加到画布

创建对象后，它们只存在于内存中，必须通过 canvas.add() 将其挂载至目标画布：

// 单个添加
canvas.add(rect);

// 批量添加多个对象
canvas.add(circle, text);

执行 canvas.add() 后，Fabric.js 会把图元加入其内部维护的渲染队列，并默认自动触发一次画面绘制。此时打开浏览器，就可以直接用鼠标点击图形，观察四周出现的边框与操作手柄。

四、对象属性修改与重绘机制

创建对象后，动态修改其位置、颜色或交互行为是日常开发中最频繁的操作。Fabric.js 采用统一的 set() 方法进行状态更新，但必须清楚它的重绘同步时机。

1. 使用 set() 更新属性

你可以传入键值对或对象字面量来更新属性：

// 方式一：修改单个属性
rect.set('fill', '#EF4444');

// 方式二：批量修改多个属性
rect.set({
  left: 120,
  top: 80,
  angle: 15,          // 顺时针旋转 15 度
  scaleX: 1.2,        // 水平缩放 1.2 倍
  selectable: false   // 锁定该对象，禁止用户用鼠标选中
});

2. 理解重绘机制：renderAll 与 requestRenderAll

新手最容易遇到的困惑是：在代码中调用了 rect.set() 后，屏幕上的画面并没有发生变化。这是因为调用 set() 仅仅修改了内存中该 JavaScript 对象的内部状态，并没有触发 Canvas 的位图刷新。

// 修改属性后，必须显式通知画布刷新
rect.set('fill', '#3B82F6');
canvas.renderAll(); // 同步重绘画布

进阶建议（renderAll vs requestRenderAll）：

在常规单次操作中，调用 canvas.renderAll() 会立即清空重绘整个画布；但是在动画循环、高频鼠标拖动或短时间内多次更新属性的场景下，反复调用 renderAll() 会导致严重的重绘开销和卡顿。此时推荐使用 canvas.requestRenderAll()。它通过浏览器原生的 requestAnimationFrame 对重绘请求进行合并防抖，确保同一渲染帧内无论修改多少次属性，仅执行一次物理重绘。

五、常见问题与调试排查清单

在初次使用 Fabric.js 时，如果遇到预期之外的表现，可按照以下顺序快速排查：

添加对象后画面一片空白：优先检查对象坐标（left、top）是否在画布可见范围之外；检查填充色 fill 是否为 transparent 且同时未设置 stroke；如果是在异步回调（如接口返回或图片加载完成）中修改属性，确认是否遗漏了 canvas.renderAll()。
鼠标点击位置与选中框手柄发生偏移：通常是因为通过外部 CSS 对 <canvas> 容器设置了 width/height、transform: scale(...) 或父级元素具有缩放变形。若画布所在页面布局发生了尺寸位移，可调用 canvas.calcOffset() 强制重新校准画布与视口的坐标偏移。
图层前后遮挡与层级调整：后通过 canvas.add() 加入的对象默认位于上层。如果需要改变顺序，可使用内置的层级控制 API，如 canvas.bringToFront(obj)（置顶）、canvas.sendToBack(obj)（置底）、canvas.bringForward(obj)（上移一层）和 canvas.sendBackwards(obj)（下移一层）。