安装

环境要求

CustomForge 是仅运行于浏览器的 ESM Library，需要应用环境支持 ES2022 模块、DOM、Canvas 2D、WebGL、ResizeObserver、原生 dialog、容器查询和 color-mix()

浏览器基线为 Chrome 和 Edge 111+、Firefox 113+、Safari 16.4+

Node.js 22+ 和 pnpm 11+ 只用于本仓库的开发与发布。浏览器包不再向消费项目声明 Node.js engine 限制

从 npm 安装

当前正式制品通过 npm 默认的 latest dist-tag 发布

pnpm

pnpm add customforge

npm

npm install customforge

yarn

yarn add customforge

Fabric.js 和 Three.js 是运行时依赖，会自动完成安装

使用方不需要再单独安装这两个引擎

固定具体版本

需要可重复构建时应安装具体版本

pnpm add customforge@0.1.0

导入样式

在应用入口中导入一次公开样式

import 'customforge/style.css'

该样式同时包含核心编辑器、查看器和可选 Workbench 的样式

CustomForge 的选择器限定在自身组件类名下，不会重置宿主页面的全局按钮、输入框或普通元素

选择入口

使用完整 Workbench

import { createWorkbench } from 'customforge/workbench'
import 'customforge/style.css'

或使用不带业务界面的底层 Library

import { createCustomizer } from 'customforge'
import 'customforge/style.css'

只有文档中声明的包路径属于公开入口

不要从 customforge/core、customforge/editor 或 customforge/viewer 等内部路径导入

pnpm 的 canvas 提示

pnpm 可能提示可选的原生 canvas 构建脚本已被忽略

CustomForge 运行在浏览器中，不使用 Node 原生 canvas，因此正常的浏览器项目不需要批准该构建脚本

希望明确记录这一选择的项目可以添加

{
  "pnpm": {
    "ignoredBuiltDependencies": ["canvas"]
  }
}

服务端渲染

只能在浏览器中并且挂载元素已经存在后创建 CustomForge 实例

使用 SSR 框架时，应在客户端挂载生命周期中完成初始化，并在组件卸载时调用 destroy()

下一步

继续阅读快速开始