共计 5579 个字符，预计需要花费 14 分钟才能阅读完成。
DIY.JS 是一款专用于 DIY 定制的 Canvas 图形库
介绍
1. 图层结构
DIY 的可操作区域由两部分组成（两个层叠的 Canvas 对象）：
- 背景图层：用于物品模型绘制，比如衣服、手机壳
- DIY 图层：用于素材绘制，以及定义对应物品的可 DIY 区域
图层
2.DIY 区域
DIY 区域指的是在指定物品上，用户可以进行个性化定制的区域。
DIY 区域
DIY 区域由 Canvas 的 destination-in 的混合模式进行实现（只显示两张图重叠的位置）
3. 自适应设计
对于不同的物品，DIY 区域的大小往往是不一致的，导入导出的素材模板，会按照不同的 DIY 区域来自适应大小和位置。
自适应
添加素材的时候，支持百分比的单位，同时可以自定义百分比转换为实际的大小时，所参照的对象。
假设指定图形的宽度为 50%，DIY 区域宽度为 200px，Canvas 宽度为 500px；
- 设置参照 DIY 区域，则图形的实际宽度为 100px；
- 设置参照 Canvas，则图形的实际宽度为 250px；
4. 演示
以下是几个配置好的支持 DIY 的物品：
5. 功能
专为 DIY 设计增加了多种实用的功能：
- 模板响应式设计
- 导入导出 JSON
- 自定义 DIY 区域
- 更多的图层操作
- 丰富的文字功能
- 可正反面切换
- 自带撤回与恢复
- 图形编组
- …… 更多
用法
下面介绍一些基础用法，方便快速上手：
1. 创建 DIY 面板
首先需要指定一个 dom 来创建操作区域：
import DIY from "@/diy";
const element = document.querySelector("#stage");
const stage = new DIY.Stage(element);
然后设置需要 DIY 的物品模型，以 T 恤（https://douyin.nicen.cn/icon/cloth-w.png）举例：
/**
* 初始化图形，设置坐标位置 (0,0)，初始宽度 100%
*/
const model = new DIY.Image({
x: 0,
y: 0,
url: "https://douyin.nicen.cn/icon/cloth-w.png",
w: '100%'
});
/* 添加到舞台的背景图层 */
stage.addModel(model)
添加后的最终效果如下：
设置模型
设置 DIY 区域（https://douyin.nicen.cn/icon/rect.png），并添加一个素材：
/* 初始化图形 */
const view = new DIY.Image({
x: 0,
y: 0,
url: "https://douyin.nicen.cn/icon/cloth-w.png",
w: '100%'
});
/* 添加到舞台的背景图层 */
stage.setView(view);
/* 新增素材 */
stage.add(new DIY.Image({url: 'https://douyin.nicen.cn/assets/24/9b1445639f6ef9ee3c0430605ac651ee.png'}))
添加后，最终效果如下：
效果
2.JSON 导入导出
假设有一个 DIY 设计任务如下图：
案例
执行导出 JSON 的操作：
// 导出 JSON
stage.toJson();将输出如下 JSON（太长了，点击访问查看）: https://nicen.cn/collect/diy.json
导入对应的 JSON，复现这个 DIY 任务：
// 导入指定 json
stage.loadJson(json);
接口文档
1.Stage
Stage 对象代表整个绘图区域，它是所有图形对象的容器。在用于管理图形对象、处理用户交互、渲染图形以及控制动画等
on
新增舞台指定事件的事件监听器。
on(type: string, callback: Function): void;
- type，事件名称
- callback，事件的回调
Stage 支持的事件如下：
- init（舞台初始化）、
- start（触摸开始）、
- end（操作结束）、
- up（选中图形时抬起）、
- move（图形移动）、
- reset（舞台重置）、
- pinch（图形 pinch）、
- rotate（图形旋转）、
- active（图形激活）、
- deactivate（图形取消）、
- clear（清理所有图形）
- after-delete、before-delete（图形删除）、
- to-do（文字、图片替换按钮被点击）、
- doubleTap（双击事件）、
- after-sort、before-sort（图层改变事件）、
- after-add、before-add（新增图形）
- before-copy、after-copy（复制图形）
- before-adjust、after-adjust（微调图形）
- before-flip、after-flip（翻转图形）
- before-release、after-release（图形编组解绑）
- snap-change（快照改变）
- load-json,loaded-json（json 加载开始、加载完毕）
- click-blank（点击空白）
- use-font（加载字体）
- redo，重做
- undo，撤回
off
移除舞台指定事件的事件监听器。
off(type: string): void;
emit
触发指定事件的事件监听器
emit(type: string, event?: any): void;
add
添加指定的图形对象到舞台
add(shape: Shape, index?: number): void;
- shape，指定的图形对象
- index，类似 css 的 z -index，指定图形 z 轴的层级
get
获取指定名称或者索引的图形对象
get(name: string): Shape | undefined; - name，图形对象的名称
remove
移除指定的图形对象
remove(shape: Shape | string, flag: boolean): void; - shape，要移除的图形对象
- flag，如果图形不允许移除，则强制移除
clear
清除舞台上的所有图形对象
clear(): void; clearModel
清除模型中的所有图形对象
clearModel(): void; reset
重置舞台到初始状态，移除模型、素材、DIY 区域
reset(): void; scale
指定舞台的放大缩小倍数，一般是当前设备的 DPR 值
scale(zoom: number): void; getScale
获取当前的缩放比例
getScale(): number; shapes
获取指定索引处的图形对象数组
shapes(flag: boolean, index: number): Shape[]; - flag，布尔值，指示是否包括模型中的图形
- index，图形对象在数组中的索引
render
渲染舞台
render(): void; setElementStyle
设置舞台绑定的元素的样式
setElementStyle(style: object): void; - style，一个对象，包含要设置的样式属性
enableMultiActive
允许图形多选
enableMultiActive(): void; disableMultiActive
禁止图形多选
disableMultiActive(): void; getIndex
获取指定图形对象在舞台中的索引
getIndex(shape: Shape): number; renderModel
渲染模型
renderModel(): void; getCenterPoint
获取舞台的中心点坐标
getCenterPoint(): { x: number, y: number} getContext
获取 DIY 层的 Canvas 的渲染上下文
getContext(): CanvasRenderingContext2D; createCanvas
创建一个新的 Canvas 元素
createCanvas(w: number, h: number, param?: {}): {elem: HTMLCanvasElement, context: CanvasRenderingContext2D} - w，Canvas 的宽度
- h，Canvas 的高度
- param，可选参数对象
getQueue
获取异步任务队列
getQueue(): []; addQueueTask
添加任务到队列
addQueueTask(task: Function): void; - task，要添加的任务函数
clearQueue
清空任务队列
clearQueue(): void; resetOffset
重置偏移量
resetOffset(): void; export
导出舞台内容
export(config: object): Promise; - config，导出配置对象
关于 config 对象：
{elem: ['model', 'custom', 'view'], // 需要导出的元素，canvas, 导出整个画布 背景图、所有图形、DIY 区域图
view: true, // 仅导出 view 区域
clip: true, // 裁剪多余的透明部分
type: 'base64',// 输出二进制还是 base64
filter: false, // 是否过滤不可导出的图形
ratio: 3.5, // 导出比例
size: null, // 指定导出的图片大小
frame: null // 图框 {height:null,width:null,fillColor:null}
}
addModel
添加图形对象到模型
addModel(shape: Shape): void; - shape，要添加的图形对象
bound
获取舞台的边界
bound(): { x: number; y: number; w: number; h: number; _w: number; _h: number;} dpr
获取设备像素比
dpr(): number; getViewBound
获取可 DIY 区域的边界范围
getViewBound(): { x: number; y: number; w: number, h: number, _x: number; _y: number; _w: number; _h: number} getView
获取可 DIY 区域的图形对象
getView(): Shape; getActive
获取当前激活的图形对象
getActive(): Shape | null; getElement
获取舞台的 HTML 元素
getElement(): HTMLElement; getConfig
获取舞台配置
getConfig(): { maxWidth: number; maxHeight: number; sensitivity: number; minRotatable: number; themeColor: string; activeColor: string;} setConfig
设置舞台配置
setConfig(key: any, value: any): void; - key，配置项的键
- value，配置项的值
load
加载图形对象
load(json: string | object, flag?: boolean): Shape; - json，图形对象的 JSON 表示或对象
- flag，布尔值，指示是否同时添加到模型
toJson
将舞台内容转换为 JSON 字符串
toJson(): string; loadJson
从 JSON 对象加载图形对象
loadJson(json: object, param: object): void; - json，图形对象的 JSON 对象
- param，加载参数对象
loadJsonWithSnap
加载指定的 JSON，但不渲染到舞台，返回舞台的快照。
loadJsonWithSnap(json: object, param: object): object;
- json，图形对象的 JSON 对象
- param，加载参数对象
canMultiActive
检查是否允许多图形对象同时激活
canMultiActive(): boolean;
r
记录当前图形的快照
r(snapshot: null | object): void;
- snapshot，可选的快照对象，如果为 null 则创建新的快照
alter
回滚指定快照到舞台
alter(snapshot : object, flag : boolean): void;
- snapshot，可选的快照对象
- flag，默认为 false，snapshot 为素材的快照，不包括 DIY 区域和背景模型，为 true 时 snapshot 包含三者
undo
撤销上一次操作
undo(): void;
redo
重做上一次撤销的操作
redo(): void;
snap
记录当前舞台的快照（素材部分）
snap(): object;
返回当前快照对象。
clearSnap
清空撤销和恢复的记录
clearSnap(): void;
hiddenOutline
隐藏可 DIY 区域图形的轮廓线
hiddenOutline(): void;
showOutline
显示可 DIY 区域图形的轮廓线
showOutline(): void;
canShowOutline
检查是否可以显示轮廓线
canShowOutline(): void;
pauseEvent
暂停指定的事件
pauseEvent(event: string): void;
- event，要暂停的事件名称
resumeEvent
恢复指定的事件
resumeEvent(event: string): void;
- event，要恢复的事件名称
active
激活指定的图形对象
active(shape: object): void;
- shape，要激活的图形对象
clear
清除舞台中的所有的素材
clear(): void;
getModelShapes
获取舞台的所有模型层图形
getModelShapes(flag: boolean, index: number): Shape;
- flag，布尔值，指示是否包括隐藏的图形对象
- index，图形对象在数组中的索引
stop
停止渲染，不响应任何图形操作
stop(): void;
resume
恢复渲染
resume(): void;
