开源组件 | 一款好用的小程序生成图片库

一、项目概述

想到小程序中有如此大量的生成图片需求，而 Canvas 生成方法又是如此难用和坑爹（有关小程序的坑，可看 https://github.com/Kujiale-Mobile/MP-Keng ）。我们就想到可不可以做一款可以很方便生成图片，并且还能屏蔽掉直接使用 Canvas 的一些坑的库呢？对此我们发起了 “画家计划— 通过 json 数据形式，来进行动态渲染并绘制出图片”。 Painter 库的整体架构如下：

首先，我们定义了一套绘图 JSON 规范，开发者可以根据需求构建生成图片的 Palette（调色板），然后在程序运行过程中把调色板传入给 Painter（画家）。Painter 会调用 Pen（画笔），根据 Palette 内容绘制出对应的图片后返回。

经过了一段时间的进步，painter 在大家的建议与贡献下得到了长足的成长。我们感谢各位使用者在这个过程中对 painter 的支持和帮助，这也是我们不断完善 painter 的最大动力。我们将为大家介绍 painter 的新能力，并明确下一阶段的迭代目标。

二、技术特性

功能全，支持文本、图片、矩形、qrcode 类型的 view 绘制
布局全，支持多种布局方式，如 align（对齐方式）、rotate（旋转）
支持圆角，其中图片，矩形，和整个画布支持 borderRadius 来设置圆角
支持边框，同时支持 solid、dashed、dotted 三种类型
支持渐变色，包括线性渐变与径向渐变。
支持 box-shadow 和 text-shadow，统一使用 shadow 表示。
支持文字背景、获取宽度、主动换行
支持自定义字体
支持图片 mode
支持元素的相对定位方法
杠杠的性能优化，我们对网络素材图片加载实现了一套 LRU 存储机制，不用重复下载素材图片。
杠杠的容错，因为某些特殊情况会导致 Canvas 绘图不完整。我们对此加入了对结果图片进行检测机制，如果绘图出错会进行重绘。
生成的图片支持分辨率调节
支持使用拖动等操作动态编辑绘制内容

三、组件文档

属性	类型	说明	必填	默认值
customStyle	string	canvas 的自定义样式	否
palette	IPalette	静态模版，具体规范下文有详细介绍	否
scaleRatio	number	缩放比，会在传入的 palette 中统一乘以该缩放比，作用和 widthPixels 类似，所以不要同时使用	否	1
widthPixels	number	生成的图片的像素宽度，如不传则根据模版动态生成	否
dirty	boolean	是否启用脏检查	否	false
LRU	boolean	是否开启 LRU 机制	否	false
dancePalette	IPalette	动态模版，规范同静态模版	否
customActionStyle	ICustomActionStyle	选择框、缩放图标、删除图标的自定义样式与图片	否
action	IView	动态编辑内容，用于刷新动态模版	否
disableAction	boolean	禁止动态编辑操作	否	false
clearActionBox	boolean	清除动态编辑框	否	false
imgErr	function	图片生成失败，可以从 e.detail.error 获取错误信息	否
imgOk	function	图片生成成功，可以从 e.detail.path 获取生成的图片路径	否
viewUpdate	function	动态模版， view 被更新，可从 e.detail.view 获取更新的 view	否
viewClicked	function	动态模版， view 被选中，可从 e.detail.view 获取点击的 view，如为空，则是选中背景	否
touchEnd	function	动态模版，触碰结束。只有 view，代表触碰的对象；包含 view、type、index，代表点击了删除 icon；	否
didShow	function	动态模版，绘制结束时触发	否
use2D	boolean	是否使用 canvas2d 接口（注意！使用 use2D 就无法使用 dancePalette 与 action）	否	false

五、本地运行

运行例子

git clone https://github.com/Kujiale-Mobile/Painter.git

代码下载后，用小程序 IDE 打开后即可使用。

注：请选择小程序项目，非小游戏，例子中无 appid，所以无法在手机上运行，如果需要真机调试，请在打开例子时，填上自己的小程序 id

快速开始

mpvue 的使用方法请移步 mpvue 接入方案

taro 的使用方法请参考 Taro 接入方案 painter 已发布 taro 版本的 npm 包mina-painter

引入代码

Painter 的核心代码在另一个 repo 中，https://github.com/Kujiale-Mobile/PainterCore.git 。你可以通过 submodule 的方式进行库的引入。有关 submodule 的用法可自行 Google。

git submodule add https://github.com/Kujiale-Mobile/PainterCore.git components/painter
作为自定义组件引入，注意目录为第一步引入的代码所在目录

"usingComponents":{ "painter":"/components/painter/painter"}
组件接收 palette 字段作为画图数据的数据源, 图案数据以 json 形式存在，推荐使用“皮肤模板”的方法进行传递，示例代码如下：

<painter palette="{{data}}" bind:imgOK="onImgOK" />

你可以通过设置 widthPixels 来强制指定生成的图片的像素宽度，否则，会根据你画布中设置的大小来动态调节，比如你用了 rpx，则在 iphone 6 上会生成 0.5 倍像素的图片。由于 canvas 绘制的图片像素直接由 Canvas 本身大小决定，此处通过同比例放大整个画布来实现对最后生成的图片大小的调节。

<painter customStyle='position: absolute; left: -9999rpx;' palette="{{template}}" bind:imgOK="onImgOK" widthPixels="1000"/>
数据传入后，则会自动进行绘图。绘图完成后，你可以通过绑定 imgOK 或 imgErr 事件来获得成功后的图片或失败的原因。

bind:imgOK="onImgOK"bind:imgErr="onImgErr"onImgOK(e) { 其中 e.detail.path 为生成的图片路径},
你也可以通过使用 dancePalette 、 action 等字段开启 painter 的高阶用法。具体使用方式将会在下方有详细描述。在新版 painter 中，静态模版默认相对 painter 本身 left: -9999px 。因此正常情况下使用 painter 时出现在页面上的都是动态模版。如果希望禁止用户的操作，可以按照使用静态模版的做法，只传 palette 属性即可。