1 | # ali-img
|
2 |
|
3 | Ali cloud image processing tool package
|
4 |
|
5 | ### Usage
|
6 |
|
7 | ```bash
|
8 | npm i -S ali-img
|
9 | ```
|
10 |
|
11 | ```javascript
|
12 | const fs = require('fs')
|
13 | const AliImg = require('ali-img')
|
14 |
|
15 | const img = new AliImg({
|
16 | accessKeyId: '',
|
17 | accessKeySecret: '',
|
18 | region: '',
|
19 | bucket: ''
|
20 | })
|
21 |
|
22 | img('test.png')
|
23 | .drawText(100, 100, '测试')
|
24 | .format('png')
|
25 | .resize(400, 400)
|
26 | .stream()
|
27 | .pipe(fs.createWriteStream('save.png'))
|
28 |
|
29 | ```
|
30 |
|
31 | ## img 工厂方法
|
32 |
|
33 | 可传入`本地图片`或`网络图片`路径,返回`Img`实例。
|
34 |
|
35 | ```javascript
|
36 | const localImg = img('/path/to/resource.png')
|
37 | const networkImg = img('https://path/to/resource.png')
|
38 | ```
|
39 |
|
40 | ### Img 实例方法
|
41 |
|
42 | - 图片缩放
|
43 | - [resize 图片缩放](#resize)
|
44 | - 图片裁剪
|
45 | - [circle 内切圆](#circle)
|
46 | - [crop 裁剪](#crop)
|
47 | - [indexCropX 索引切割(横向)](#indexcropx)
|
48 | - [indexCropY 索引切割(纵向)](#indexcropy)
|
49 | - [roundedCorners 圆角矩形](#roundedcorners)
|
50 | - 图片旋转
|
51 | - [autoOrient 自适应方向](#autoorient)
|
52 | - [rotate 旋转](#rotate)
|
53 | - 图片效果
|
54 | - [blur 模糊效果](#blur)
|
55 | - [bright 亮度](#bright)
|
56 | - [contrast 对比度](#contrast)
|
57 | - [sharpen 锐化](#sharpen)
|
58 | - 格式转换
|
59 | - [format 格式转换](#format)
|
60 | - [interlace 渐进显示](#interlace)
|
61 | - [quality 质量变换(相对)](#quality)
|
62 | - [absoluteQuality 质量变换(绝对)](#absolutequality)
|
63 | - 图片水印
|
64 | - [watermark 图片水印](#watermark)
|
65 | - [drawText 绘制文字](#drawtext)
|
66 | - [fill 填充颜色](#fill)
|
67 | - [font 文字字体](#font)
|
68 | - [fontSize 文字大小](#fontsize)
|
69 | - 生成
|
70 | - [stream 返回图片流](#stream)
|
71 | - [toBuffer 取得图片Buffer对象](#tobuffer)
|
72 | - [write 写入本地文件](#write)
|
73 |
|
74 | ### resize
|
75 |
|
76 | 调整图片尺寸大小。
|
77 |
|
78 | `resize(width, height [, options])`
|
79 |
|
80 | ### 参数
|
81 |
|
82 | | 名称 | 类型 | 必填 | 描述 |
|
83 | | --- | --- | --- | --- |
|
84 | | width | number & null | 是 | 图片宽度 |
|
85 | | height | number & null | 是 | 图片高度 |
|
86 | | options | object | 否 | 其他选项 |
|
87 |
|
88 | ### options 对象属性
|
89 |
|
90 | | 名称 | 类型 | 描述 |
|
91 | | --- | --- | --- |
|
92 | | limit | number | 指定当目标缩略图大于原图时是否处理。<br/>值是 1 表示不处理;值是 0 表示处理。默认是 0 |
|
93 | | mode | string | 指定缩略的模式:<br/>- lfit:等比缩放,限制在设定在指定w与h的矩形内的最大图片。<br/>- mfit:等比缩放,延伸出指定w与h的矩形框外的最小图片。<br/>- fill:固定宽高,将延伸出指定w与h的矩形框外的最小图片进行居中裁剪。<br/>- pad:固定宽高,缩略填充。<br/>- fixed:固定宽高,强制缩略 |
|
94 | | color | string | 当缩放模式选择为pad(缩略填充)时,可以选择填充的颜色(默认是白色)参数的填写方式:采用16进制颜色码表示,如00FF00(绿色)。|
|
95 | | percent | number | 倍数百分比。 小于100,即是缩小,大于100即是放大。 此参数存在则覆盖`width`和`height`属性 |
|
96 |
|
97 | ### circle
|
98 |
|
99 | 图片内切圆。
|
100 |
|
101 | `circle(radius)`
|
102 |
|
103 | | 名称 | 类型 | 必填 | 描述 |
|
104 | | --- | --- | --- | --- |
|
105 | | radius | number | 是 | 从图片取出的圆形区域的半径<br/>半径 r 不能超过原图的最小边的一半。<br/>如果超过,则圆的大小仍然是原圆的最大内切圆。 |
|
106 |
|
107 | #### 注意事项
|
108 |
|
109 | > - 如果图片的最终格式是 png、webp、 bmp 等支持透明通道的图片,那么图片非圆形区域的地方将会以透明填充。<br/>如果图片的最终格式是 jpg,那么非圆形区域是以白色进行填充。推荐保存成 png 格式。
|
110 | > - 如果指定半径大于原图最大内切圆的半径,则圆的大小仍然是图片的最大内切圆。
|
111 |
|
112 | ### crop
|
113 |
|
114 | 裁剪图片,指定裁剪的起始点以及裁剪的宽高来决定裁剪的区域。
|
115 |
|
116 | `crop(x, y, width, height [, origin])`
|
117 |
|
118 | ### 参数
|
119 |
|
120 | | 名称 | 类型 | 必填 | 描述 |
|
121 | | --- | --- | --- | --- |
|
122 | | x | number | 是 | 指定裁剪起点横坐标(默认左上角为原点) |
|
123 | | y | number | 是 | 指定裁剪起点纵坐标(默认左上角为原点) |
|
124 | | width | number | 是 | 指定裁剪宽度 |
|
125 | | height | number | 是 | 指定裁剪高度 |
|
126 | | origin | string | 否 | 设置裁剪的原点位置,由九宫格的格式,一共有九个地方可以设置,每个位置位于每个九宫格的左上角 |
|
127 |
|
128 | #### 裁剪原点位置参数示意图:
|
129 |
|
130 | | nw | north | ne |
|
131 | | :---: | :---: | :---: |
|
132 | | west | center | east |
|
133 | | sw | south | se |
|
134 |
|
135 | #### 注意事项
|
136 |
|
137 | > 如果指定的起始横纵坐标大于原图,将会返回错误:BadRequest, 错误内容是:Advance cut’s position is out of image. <br/>如果从起点开始指定的宽度和高度超过了原图,将会直接裁剪到原图结尾。
|
138 |
|
139 | ### indexCropX
|
140 |
|
141 | 索引切割(横向)。将图片分成 x 轴,按指定长度 (length) 切割,指定索引 (index),取出指定的区域。
|
142 |
|
143 | `indexCropX(width, index)`
|
144 |
|
145 | ### 参数
|
146 |
|
147 | | 名称 | 类型 | 必填 | 描述 |
|
148 | | --- | --- | --- | --- |
|
149 | | width | number | 是 | 进行水平切割,每块图片的宽度。 |
|
150 | | index | number | 是 | 选择切割后第几个块。(0表示第一块)<br/>如果超出最大块数,返回原图。 |
|
151 |
|
152 | ### indexCropY
|
153 |
|
154 | 索引切割(纵向)。将图片分成 y 轴,按指定长度 (length) 切割,指定索引 (index),取出指定的区域。
|
155 |
|
156 | `indexCropY(height, index)`
|
157 |
|
158 | ### 参数
|
159 |
|
160 | | 名称 | 类型 | 必填 | 描述 |
|
161 | | --- | --- | --- | --- |
|
162 | | height | number | 是 | 进行垂直切割,每块图片的高度。 |
|
163 | | index | number | 是 | 选择切割后第几个块。(0表示第一块)<br/>如果超出最大块数,返回原图。 |
|
164 |
|
165 | ### roundedCorners
|
166 |
|
167 | 可以把图片保存成圆角矩形,并可以指定圆角的大小 。
|
168 |
|
169 | `roundedCorners(radius)`
|
170 |
|
171 | ### 参数
|
172 |
|
173 | | 名称 | 类型 | 必填 | 描述 |
|
174 | | --- | --- | --- | --- |
|
175 | | radius | number | 是 | 将图片切出圆角,指定圆角的半径。<br/>生成的最大圆角的半径不能超过原图的最小边的一半。 |
|
176 |
|
177 | #### 注意事项
|
178 |
|
179 | > - 如果图片的最终格式是 png、webp、bmp 等支持透明通道的图片,那么图片非圆形区域的地方将会以透明填充。如果图片的最终格式是 jpg, 那么非圆形区域是以白色进行填充 。推荐保存成 png 格式。
|
180 | > - 如果指定半径大于原图最大内切圆的半径,则圆角的大小仍然是图片的最大内切圆。
|
181 |
|
182 | ### autoOrient
|
183 |
|
184 | 自适应方向。某些手机拍摄出来的照片可能带有旋转参数(存放在照片exif信息里面)。可以设置是否对这些图片进行旋转。默认是设置自适应方向。
|
185 |
|
186 | `autoOrient(value)`
|
187 |
|
188 | ### 参数
|
189 |
|
190 | | 名称 | 类型 | 必填 | 描述 |
|
191 | | --- | --- | --- | --- |
|
192 | | value | number | 是 | 进行自动旋转<br/>0:表示按原图默认方向,不进行自动旋转。<br/>1:先进行图片进行旋转,然后再进行缩略 |
|
193 |
|
194 | #### 注意事项
|
195 |
|
196 | > - 进行自适应方向旋转,要求原图的宽度和高度必须小于 4096。
|
197 | > - 如果原图没有旋转参数,加上auto-orient参数不会对图有影响。
|
198 |
|
199 | ### rotate
|
200 |
|
201 | 可以将图片按顺时针旋转。
|
202 |
|
203 | `rotate(angle)`
|
204 |
|
205 | ### 参数
|
206 |
|
207 | | 名称 | 类型 | 必填 | 描述 |
|
208 | | --- | --- | --- | --- |
|
209 | | angle | number | 是 | 图片按顺时针旋转的角度。默认值为 0,表示不旋转。 |
|
210 |
|
211 | #### 注意事项
|
212 |
|
213 | > - 旋转图片可能会导致图片的尺寸变大。
|
214 | > - 旋转对图片的尺寸有限制,图片的宽或者高不能超过 4096。
|
215 |
|
216 | ### blur
|
217 |
|
218 | 可以对图片进行模糊操作。
|
219 |
|
220 | `blur(radius, standard)`
|
221 |
|
222 | ### 参数
|
223 |
|
224 | | 名称 | 类型 | 必填 | 描述 |
|
225 | | --- | --- | --- | --- |
|
226 | | radius | number | 是 | 模糊半径。取值[1,50]<br/>r 越大图片越模糊。 |
|
227 | | standard | number | 是 | 正态分布的标准差。取值[1,50]<br/>s 越大图片越模糊。 |
|
228 |
|
229 | ### bright
|
230 |
|
231 | 可以对处理后的图片进行亮度调节。
|
232 |
|
233 | `bright(value)`
|
234 |
|
235 | ### 参数
|
236 |
|
237 | | 名称 | 类型 | 必填 | 描述 |
|
238 | | --- | --- | --- | --- |
|
239 | | value | number | 是 | 亮度调整。0 表示原图亮度,小于 0 表示低于原图亮度,大于 0 表示高于原图亮度。取值[-100, 100] |
|
240 |
|
241 | ### contrast
|
242 |
|
243 | 可以对处理后的图片进行对比度调节。
|
244 |
|
245 | `contrast(value)`
|
246 |
|
247 | ### 参数
|
248 |
|
249 | | 名称 | 类型 | 必填 | 描述 |
|
250 | | --- | --- | --- | --- |
|
251 | | value | number | 是 | 对比度调整。0 表示原图对比度,小于 0 表示低于原图对比度,大于 0 表示高于原图对比度。取值[-100, 100] |
|
252 |
|
253 | ### sharpen
|
254 |
|
255 | 可以对处理后的图片进行锐化,使图片变得清晰。
|
256 |
|
257 | `sharpen(value)`
|
258 |
|
259 | ### 参数
|
260 |
|
261 | | 名称 | 类型 | 必填 | 描述 |
|
262 | | --- | --- | --- | --- |
|
263 | | value | number | 是 | 表示进行锐化处理。取值为锐化参数,参数越大,越清晰。取值[50, 399]。为达到较优效果,推荐取值为 100。 |
|
264 |
|
265 | ### format
|
266 |
|
267 | 可以将图片转换成对应格式(jpg, png, bmp, webp,gif)。 默认不填格式,是按原图格式返回。
|
268 |
|
269 | `format(value)`
|
270 |
|
271 | ### 参数
|
272 |
|
273 | | 名称 | 类型 | 必填 | 描述 |
|
274 | | --- | --- | --- | --- |
|
275 | | value | string | 是 | 指定输出的图片格式,可选`jpg`,`png`,`bmp`,`webp`,`gif` |
|
276 |
|
277 | ### interlace
|
278 |
|
279 | 图片格式为 jpg 时有两种呈现方式:
|
280 | - 自上而下的扫描式
|
281 | - 先模糊后逐渐清晰(在网络环境比较差时明显)
|
282 |
|
283 | 默认保存为第一种,如果要指定先模糊后清晰的呈现方式,请使用渐进显示参数。
|
284 |
|
285 | `interlace(value)`
|
286 |
|
287 | ### 参数
|
288 |
|
289 | | 名称 | 类型 | 必填 | 描述 |
|
290 | | --- | --- | --- | --- |
|
291 | | value | number | 是 | 1 表示保存成渐进显示的 jpg 格式<br/>0 表示保存成普通的 jpg 格式 |
|
292 |
|
293 | > 注意:此参数只有当效果图是 jpg 格式时才有意义 。
|
294 |
|
295 | ### quality
|
296 |
|
297 | 如果图片保存成 jpg 或 webp, 可以支持质量变换。
|
298 |
|
299 | `quality(value)`
|
300 |
|
301 | ### 参数
|
302 |
|
303 | | 名称 | 类型 | 必填 | 描述 |
|
304 | | --- | --- | --- | --- |
|
305 | | value | number | 是 | 决定图片的相对质量,对原图按照 q% 进行质量压缩。如果原图质量是 100%,使用 90q 会得到质量为 90% 的图片;如果原图质量是 80%,使用 90q 会得到质量72%的图片。 <br/>只能在原图是 jpg 格式的图片上使用,才有相对压缩的概念。如果原图为 webp,那么相对质量就相当于绝对质量。 |
|
306 |
|
307 | ### absoluteQuality
|
308 |
|
309 | 如果图片保存成 jpg 或 webp, 可以支持质量变换。
|
310 |
|
311 | `absoluteQuality(value)`
|
312 |
|
313 | ### 参数
|
314 |
|
315 | | 名称 | 类型 | 必填 | 描述 |
|
316 | | --- | --- | --- | --- |
|
317 | | value | number | 是 | 决定图片的绝对质量,把原图质量压到Q%,如果原图质量小于指定数字,则不压缩。如果原图质量是100%,使用”90Q”会得到质量90%的图片;如果原图质量是95%,使用“90Q”还会得到质量90%的图片;如果原图质量是80%,使用“90Q”不会压缩,返回质量80%的原图。 <br/>只能在保存格式为jpg/webp效果上使用,其他格式无效果。 如果同时指定了q和Q,按Q来处理。 |
|
318 |
|
319 | ### watermark
|
320 |
|
321 | 图片水印。水印操作可以在图片上设置另外一张图片做为水印。
|
322 |
|
323 | `watermark(x, y, image [, options])`
|
324 |
|
325 | ### 参数
|
326 |
|
327 | | 名称 | 类型 | 必填 | 描述 |
|
328 | | --- | --- | --- | --- |
|
329 | | x | number | 是 | 参数意义:水平边距, 就是距离图片边缘的水平距离, 这个参数只有当水印位置是左上,左中,左下, 右上,右中,右下才有意义<br/>默认值:10 <br/>取值范围:[0 – 4096] <br/>单位:像素(px) |
|
330 | | y | number | 是 | 参数意义:垂直边距, 就是距离图片边缘的垂直距离, 这个参数只有当水印位置是左上,中上, 右上,左下,中下,右下才有意义<br/>默认值:10 <br/>取值范围:[0 – 4096] <br/>单位:像素(px) |
|
331 | | image | object | 是 | AliImage 实例 |
|
332 | | options | object | 否 | 选项对象 |
|
333 |
|
334 | ### options 对象属性
|
335 |
|
336 | | 名称 | 类型 | 描述 |
|
337 | | --- | --- | --- |
|
338 | | position | string | 参数意义:位置,水印打在图的位置,详情参考下方区域数值对应图。<br/>取值范围:[nw,north,ne,west,center,east,ne,south] |
|
339 | | transparency | number | 参数意义:透明度。<br/>默认值:100, 表示 100%(不透明) 取值范围: [0-100] |
|
340 | | voffset | number | 参数意义: 中线垂直偏移,当水印位置在左中,中部,右中时,可以指定水印位置根据中线往上或者往下偏移。 <br/>默认值:0 <br/>取值范围:[-1000, 1000] <br/>单位:像素(px) |
|
341 |
|
342 | #### 注意事项
|
343 |
|
344 | > 水平边距、垂直边距、中线垂直偏移不仅可以调节水印在图片中的位置,而且当图片存在多重水印时,也可以调节两张水印在图中的布局。
|
345 | 用到的URL安全的Base64位编码可以参考文档下方的解释。
|
346 | 区域数值以及每个区域对应的基准点如下图。
|
347 |
|
348 | | nw | north | ne |
|
349 | | :---: | :---: | :---: |
|
350 | | west | center | east |
|
351 | | sw | south | se |
|
352 |
|
353 | ### drawText
|
354 |
|
355 | 绘制文字
|
356 |
|
357 | `drawText(x, y, text [, options])`
|
358 |
|
359 | ### 参数
|
360 |
|
361 | | 名称 | 类型 | 必填 | 描述 |
|
362 | | --- | --- | --- | --- |
|
363 | | x | number | 是 | 参数意义:水平边距, 就是距离图片边缘的水平距离, 这个参数只有当水印位置是左上,左中,左下, 右上,右中,右下才有意义<br/>默认值:10 <br/>取值范围:[0 – 4096] <br/>单位:像素(px) |
|
364 | | y | number | 是 | 参数意义:垂直边距, 就是距离图片边缘的垂直距离, 这个参数只有当水印位置是左上,中上, 右上,左下,中下,右下才有意义<br/>默认值:10 <br/>取值范围:[0 – 4096] <br/>单位:像素(px) |
|
365 | | text | string | 是 | 文字内容 |
|
366 | | options | object | 否 | 选项对象 |
|
367 |
|
368 | ### options 对象属性
|
369 |
|
370 | | 名称 | 类型 | 描述 |
|
371 | | --- | --- | --- |
|
372 | | position | string | 参数意义:位置,水印打在图的位置,详情参考下方区域数值对应图。<br/>取值范围:[nw,north,ne,west,center,east,ne,south] |
|
373 | | transparency | number | 参数意义:透明度。<br/>默认值:100, 表示 100%(不透明) 取值范围: [0-100] |
|
374 | | voffset | number | 参数意义: 中线垂直偏移,当水印位置在左中,中部,右中时,可以指定水印位置根据中线往上或者往下偏移。 <br/>默认值:0 <br/>取值范围:[-1000, 1000] <br/>单位:像素(px) |
|
375 | | shadow | number | 参数意义:文字水印的阴影透明度 <br/>取值范围:(0,100] |
|
376 | | rotate | number | 参数意义:文字顺时针旋转角度 <br/>取值范围:[0,360] |
|
377 | | fill | number | 参数意义:进行水印铺满的效果;<br/>取值范围:[0,1],1表示铺满,0表示效果无效 |
|
378 |
|
379 | ### fill
|
380 |
|
381 | 设置填充颜色
|
382 |
|
383 | `fill(color)`
|
384 |
|
385 | | 名称 | 类型 | 必填 | 描述 |
|
386 | | --- | --- | --- | --- |
|
387 | | color | string | 是 | 参数意义:文字水印文字的颜色 <br/>参数的构成必须是:六个十六进制数 如:000000表示黑色。 000000每两位构成RGB颜色,FFFFFF表示的是白色 <br/>默认值:000000黑色 |
|
388 |
|
389 | ### font
|
390 |
|
391 | 设置文字字体
|
392 |
|
393 | `font(name)`
|
394 |
|
395 | | 名称 | 类型 | 必填 | 描述 |
|
396 | | --- | --- | --- | --- |
|
397 | | name | string | 是 | 参数意义:表示文字水印的文字类型<br/>取值范围:见下表(文字类型编码对应表) <br/>默认值:wqy-zenhei<br/>可输入参数对应的中文 |
|
398 |
|
399 | ### 文字类型编码对应表
|
400 |
|
401 | | 参数值 | 中文意思 |
|
402 | | --- | --- |
|
403 | | wqy-zenhei | 文泉驿正黑 |
|
404 | | wqy-microhei | 文泉微米黑 |
|
405 | | fangzhengshusong | 方正书宋 |
|
406 | | fangzhengkaiti | 方正楷体 |
|
407 | | fangzhengheiti | 方正黑体 |
|
408 | | fangzhengfangsong | 方正仿宋 |
|
409 | | droidsansfallback | DroidSansFallback |
|
410 |
|
411 | ### fontSize
|
412 |
|
413 | 设置文字大小
|
414 |
|
415 | `fontSize(size)`
|
416 |
|
417 | | 名称 | 类型 | 必填 | 描述 |
|
418 | | --- | --- | --- | --- |
|
419 | | size | number | 是 | 参数意义:文字水印文字大小(px) <br/>取值范围:(0,1000] <br/>默认值:40 |
|
420 |
|
421 | ### stream
|
422 |
|
423 | 获取图片流
|
424 |
|
425 | `stream()`
|
426 |
|
427 | 返回图片流
|
428 |
|
429 | ### toBuffer
|
430 |
|
431 | 获取图片Buffer
|
432 |
|
433 | `toBuffer(callback)`
|
434 |
|
435 | ### 回调函数内参数
|
436 |
|
437 | | 名称 | 类型 | 描述 |
|
438 | | --- | --- | --- |
|
439 | | err | object | 错误对象 |
|
440 | | buffers | buffer | 图片buffer数据 |
|
441 |
|
442 | ### write
|
443 |
|
444 | 写入本地文件
|
445 |
|
446 | `write(fullpath, callback)`
|
447 |
|
448 | ### 参数
|
449 |
|
450 | | 名称 | 类型 | 必填 | 描述 |
|
451 | | --- | --- | --- | --- |
|
452 | | fullpath | string | 是 | 写入路径 |
|
453 | | callback | function | 是 | 回调函数 |
|
454 |
|
455 | ### 回调函数内参数
|
456 |
|
457 | | 名称 | 类型 | 描述 |
|
458 | | --- | --- | --- |
|
459 | | err | object | 错误对象 | |
\ | No newline at end of file |