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