ali-img

阿里云图像处理工具包

Usage

npm i ali-img -S

const AliImg = require('ali-img')

let img = new AliImg({
	accessKeyId: 'xxx',
	accessKeySecret: 'xxx',
	region: 'oss-cn-shenzhen',
	bucket: 'bucket name'
})

img('test.png').watermark('Hello world').write('save.png')

new AliImg(opt)

opt <Object> 配置对象
- accessKeyId <string> 阿里云账户accessKeyId
- accessKeySecret <string> 阿里云账户accessKeySecret
- region <string> oss bucket 所属区域，如 oss-cn-shenzhen
- bucket <string> oss bucket 名称

传入配置对象，返回 Img 工厂方法。

let img = new AliImg({
	accessKeyId: 'xxx',
	accessKeySecret: 'xxx',
	region: 'oss-cn-shenzhen',
	bucket: 'bucket name'
})

img 工厂方法

可传入本地图片或网络图片路径或 Readable 实例，返回Img实例。

const localImg = img('/path/to/resource.png')
const networkImg = img('https://path/to/resource.png')
const readableImg = img(fs.createReadStream('/path/to/resource.png'))

Img 实例方法

图片缩放
- resize 图片缩放
图片裁剪
- circle 内切圆
- crop 裁剪
- indexCrop 索引切割
- roundedCorners 圆角矩形
图片旋转
- autoOrient 自适应方向
- rotate 旋转角度
图片效果
- blur 模糊效果
- bright 图片亮度
- contrast 图片对比度
- sharpen 图片锐化
格式转换
- format 格式转换
- interlace 渐进显示
- quality 质量变换(相对)
- absQual 质量变换(绝对)
图片水印
- watermark 图片水印
文字效果
- fill 填充颜色
- font 文字字体
- fontSize 文字大小
- textShadow 文字阴影透明度
- textRotate 文字的旋转角度
生成
- save 将处理后的图片保存阿里云OSS，获取保存后的图片URL
- stream 获取处理后图片的数据流
- toBuffer 获取处理后图片的二进制数据
- write 将处理后的图片写入本地文件

resize(opt)

opt <Object>
- width <number> 图片宽度
- height <number> 图片高度
- longest <number> 指定目标缩略图的最长边。
- shortest <number> 指定目标缩略图的最短边。
- limit <number> 指定当目标缩略图大于原图时是否处理。值是 1 表示不处理；值是 0 表示处理。默认是 0
- mode <string> 指定缩略的模式。lfit：等比缩放，限制在设定在指定 width 与 height 的矩形内的最大图片。mfit：等比缩放，延伸出指定 width 与 height 的矩形框外的最小图片。fill：固定宽高，将延伸出指定 width 与 height 的矩形框外的最小图片进行居中裁剪。pad：固定宽高，缩略填充。fixed：固定宽高，强制缩略。Img 类的静态属性 RESIZE_MODE 保存了所有支持的缩略模式。
- color <string> 当缩放模式选择为pad（缩略填充）时，可以选择填充的颜色(默认是白色)参数的填写方式：采用16进制颜色码表示，如00FF00（绿色）。
- percent <number> 倍数百分比。小于100，即是缩小，大于100即是放大。此参数存在则覆盖width和height属性

调整图片尺寸大小。调用 resize，默认是不允许放大。即如果请求的图片对原图大，那么返回的仍然是原图。如果想取到放大的图片，即增加参数调用 limit 。对于缩略图：对缩略后的图片大小有限制，目标缩略图宽与高的乘积不能超过 4096 x 4096，且单边长度不能超过 4096 x 4。当只指定宽度或者高度时，在等比缩放的情况下，都会默认进行单边的缩放。在固定宽高的模式下，会默认宽高一样的情况下进行缩略。

// 图片缩放
img('/path/to/img.png').resize({width: 200, height: 200}).write('/path/to/save.png')

circle(radius)

radius <number> 从图片取出的圆形区域的半径，半径不能超过原图的最小边的一半。如果超过，则圆的大小仍然是原圆的最大内切圆。

图片内切圆。如果图片的最终格式是 png、webp、 bmp 等支持透明通道的图片，那么图片非圆形区域的地方将会以透明填充。如果图片的最终格式是 jpg，那么非圆形区域是以白色进行填充。推荐保存成 png 格式。如果指定半径大于原图最大内切圆的半径，则圆的大小仍然是图片的最大内切圆。

// 将图片裁剪成圆形
img('/path/to/img.png').circle(120).write('/path/to/save.png')

crop(x, y, width, height[, origin])

x <number> 指定裁剪起点横坐标（默认左上角为原点）
y <number> 指定裁剪起点纵坐标（默认左上角为原点）
width <number> 指定裁剪宽度
height <number> 指定裁剪高度
origin <string> 设置裁剪的原点位置，由九宫格的格式，一共有九个地方可以设置，每个位置位于每个九宫格的左上角

裁剪图片,指定裁剪的起始点以及裁剪的宽高来决定裁剪的区域。如果指定的起始横纵坐标大于原图，将会返回错误：BadRequest, 错误内容是：Advance cut’s position is out of image. 如果从起点开始指定的宽度和高度超过了原图，将会直接裁剪到原图结尾。

裁剪原点位置参数示意图：

nw	north	ne
west	center	east
sw	south	se

// 裁剪图片的中心区域 200x200 
img('/path/to/img.png').crop(0, 0, 200, 200, 'center').write('/path/to/save.png')

indexCrop(opt)

opt <Object>
- x <number> 进行水平切割，每块图片的宽度。
- y <number> 进行垂直切割，每块图片的高度。
- i <number> 选择切割后第几个块。（0表示第一块）如果超出最大块数，返回原图。

索引切割（横向或纵向）。将图片分成 x 轴和 y 轴，按指定长度 (length) 切割，指定索引 (index)，取出指定的区域。

// 裁剪图片
img('/path/to/img.png').indexCrop({x: 100, i: 1}).write('/path/to/save.png')

roundedCorners(radius)

radius <number> 圆角的半径。半径最大不能超过原图的最小边的一半。取值范围 [1, 4096]

圆角矩形裁剪。如果图片的最终格式是 png、webp、bmp 等支持透明通道的图片，那么图片非圆形区域的地方将会以透明填充。如果图片的最终格式是 jpg，那么非圆形区域是以白色进行填充。推荐保存成 png 格式。如果指定半径大于原图最大内切圆的半径，则圆角的大小仍然是图片的最大内切圆。

// 裁剪半径20px的圆角矩形
img('/path/to/img.png').roundedCorners(20).write('/path/to/save.png')

autoOrient(value)

value <number> 0：表示按原图默认方向，不进行自动旋转。1：先进行图片进行旋转，然后再进行缩略

自适应方向。某些手机拍摄出来的照片可能带有旋转参数（存放在照片exif信息里面）。可以设置是否对这些图片进行旋转。默认是设置自适应方向。进行自适应方向旋转，要求原图的宽度和高度必须小于 4096。如果原图没有旋转参数，加上auto-orient参数不会对图有影响。

// 自适应方向
img('/path/to/img.png').autoOrient(1).write('/path/to/save.png')

rotate(angle)

angle <number> 图片旋转的角度。正值为顺时针旋转，负值为逆时针旋转。

图片旋转。旋转图片可能会导致图片的尺寸变大。旋转对图片的尺寸有限制，图片的宽或者高不能超过 4096 px。重复调用，在原值上面叠加效果。

// 顺时针旋转90度
img('/path/to/img.png').rotate(90).write('/path/to/save.png')

blur(radius, standard)

radius <number> 模糊半径。值越大图片越模糊，取值[1, 50]。超出边界则取边界值
standard <number> 正态分布的标准差。值越大图片越模糊。取值[1, 50]。超出边界则取边界值

图片模糊操作。重复调用，在原值上面叠加效果

// 对图片进行模糊操作
img('/path/to/img.png').blur(20, 10).write('/path/to/save.png')

bright(brightness)

brightness <number> 亮度调整。0 表示原图亮度，小于 0 表示低于原图亮度，大于 0 表示高于原图亮度。取值[-100, 100]，超出边界则取边界值

调节图片亮度。重复调用，在原值上面叠加效果

// 提高图片亮度
img('/path/to/img.png').bright(50).write('/path/to/save.png')

contrast(value)

value <number> 对比度。0 表示原图对比度，小于 0 表示低于原图对比度，大于 0 表示高于原图对比度。取值[-100, 100]，超出边界则取边界值

调节图片对比度。重复调用，在原值上面叠加效果

// 提高图片对比度
img('/path/to/img.png').contrast(50).write('/path/to/save.png')

sharpen(value)

value <number> 锐化值。参数越大，越清晰。取值[50, 399]，超出边界则取边界值。为达到较优效果，推荐取值为 100。

图片锐化操作，使图片变得清晰。重复调用，在原值上面叠加效果

// 图片锐化操作
img('/path/to/img.png').sharpen(100).write('/path/to/save.png')

format(type)

type <string> 输出的图片格式，可选jpg,png,bmp,webp,gif

将图片转换成对应格式(jpg, png, bmp, webp，gif)。默认不填格式，是按原图格式返回。Img 类的 TYPE_LIST 静态属性包含支持的值列表。

// png 转换成 jpg 格式
img('/path/to/img.png').format('jpg').write('/path/to/save.jpg')

interlace(type)

type <number> 0 表示保存成普通的 jpg 格式，1 表示保存成渐进显示的 jpg 格式

调节 jpg 格式图片的呈现方式

图片格式为 jpg 时有两种呈现方式：

自上而下的扫描式
先模糊后逐渐清晰（在网络环境比较差时明显）

默认保存为第一种，如果要指定先模糊后清晰的呈现方式，请使用渐进显示参数。注意：此参数只有当效果图是 jpg 格式时才有意义。

// 将图片转换成渐进式图片
img('/path/to/img.jpg').interlace(1).write('/path/to/save.jpg')

quality(value)

value <number> 百分比，决定图片的相对质量，对原图按照 value% 进行质量压缩。如果原图质量是 100%，使用 90 会得到质量为 90％的图片；如果原图质量是 80%，使用 90 会得到质量72%的图片。只能在原图是 jpg 格式的图片上使用，才有相对压缩的概念。如果原图为 webp，那么相对质量就相当于绝对质量。传入值超过边界值时，取边界值

如果图片保存成 jpg 或 webp, 可以支持质量变换。重复调用，在原值上面叠加效果

// 调节图片质量
img('/path/to/img.jpg').quality(50).write('/path/to/save.jpg')

absQual(value)

value <number> 百分比，决定图片的绝对质量，把原图质量压到 value%，如果原图质量小于指定数字，则不压缩。如果原图质量是100%，使用”90”会得到质量90％的图片；如果原图质量是95%，使用“90”还会得到质量90%的图片；如果原图质量是80%，使用“90”不会压缩，返回质量80%的原图。只能在保存格式为jpg/webp效果上使用，其他格式无效果。如果同时指定了相对和绝对，按绝对值来处理。传入值超过边界值时，取边界值

如果图片保存成 jpg 或 webp, 可以支持质量变换。

// 调节图片质量
img('/path/to/img.jpg').absQual(80).write('/path/to/save.jpg')

watermark(content[, opt])

content <string | Img> 水印内容，字符串或 Img 实例
opt <Object> 选项
- x <number> 水平边距，就是距离图片边缘的水平距离，这个参数只有当水印位置是左上，左中，左下，右上，右中，右下才有意义。默认值：10 。取值范围：[0 – 4096] 。超过边界，则取边界值。单位：像素（px）
- y <number> 垂直边距, 就是距离图片边缘的垂直距离，这个参数只有当水印位置是左上，中上，右上，左下，中下，右下才有意义。默认值：10 。取值范围：[0 – 4096] 。超过边界，则取边界值。单位：像素(px)
- position <string> 位置，水印打在图的位置，详情参考下方区域数值对应图。取值范围：[nw,north,ne,west,center,east,ne,south]。Img 类的 ORIGIN_LIST 静态属性包含全部可选项
- transparency <number> 透明度。默认值：100，表示 100%（不透明）取值范围: [0-100]，超过边界，则取边界值
- voffset <number> 中线垂直偏移，当水印位置在左中，中部，右中时，可以指定水印位置根据中线往上或者往下偏移。默认值：0 。取值范围：[-1000, 1000] 。超过边界，则取边界值。单位：像素(px)
- fill <number> 进行水印铺满的效果；取值范围：[0,1]，1表示铺满，0表示效果无效

图片水印。水印操作可以在图片上设置另外一张图片或一段文字做为水印。

区域数值以及每个区域对应的基准点如下图

nw	north	ne
west	center	east
sw	south	se

// 文本水印
img('/path/to/img.png').watermark('Hello World').write('/path/to/save.png')

// 图片水印
img('/path/to/background.png').watermark(img('/path/to/headimg.jpg')).write('/path/to/save.png')

fill(color)

color <string> 文字水印的颜色。6位16进制数如：000000表示黑色。FFFFFF表示的是白色。默认值：黑色

设置文字填充颜色

// 设置文字为红色
img('/path/to/img.png').fill('FF0000')

font(name)

name <string> 文字水印的字体类型。默认值：文泉驿正黑。可输入参数对应的中文

设置文字字体。Img 类的静态属性 FONTS_LIST 和 FONTS_LIST_CN 包含支持的值列表

文字类型编码对应表

参数值	中文意思
wqy-zenhei	文泉驿正黑
wqy-microhei	文泉微米黑
fangzhengshusong	方正书宋
fangzhengkaiti	方正楷体
fangzhengheiti	方正黑体
fangzhengfangsong	方正仿宋
droidsansfallback	DroidSansFallback

// 设置文字字体
img('/path/to/img.png').font('方正楷体')

fontSize(size)

size <number> 文字水印大小(px)。取值范围：(0，1000]，传入值超过边界值时，取边界值。默认值：40

设置文字大小

// 设置文字大小
img('/path/to/img.png').fontSize(200)

textShadow(transparency)

transparency <number> 文字阴影的透明度。取值范围：(0, 100]，传入值超过边界值时，取边界值

设置文字水印的阴影透明度

// 设置文字阴影透明度
img('/path/to/img.png').textShadow(80)

textRotate(angle)

angle <number> 文字的旋转角度。正值为顺时针旋转，负值为逆时针旋转。

设置文字的旋转角度

// 设置文字的旋转90度
img('/path/to/img.png').textRotate(90)

save(path)

path <string> 保存至OSS的路径

将处理后的图片保存阿里云OSS，获取保存后的图片URL

let url = await img('/path/to/resource.jpg').save('cloud.jpg')
// http://[bucket].[region].aliyuncs.com/cloud.jpg

stream()

获取处理后图片的数据流

img('/path/to/save.png').stream()

toBuffer()

获取处理后图片的二进制数据

let buffer = await img('/path/to/img.png').toBuffer()

write(fullpath)

fullpath <string> 本地文件路径

将处理后的图片写入本地文件

img('/path/to/img.png').write('/path/to/compress.jpg')

ali-img
Release 0.2.0

Release 0.2.0

1.0.7

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

0.2.4

0.2.3

Documentation

ali-img

Usage

new AliImg(opt)

img 工厂方法

Img 实例方法

resize(opt)

circle(radius)

crop(x, y, width, height[, origin])

indexCrop(opt)

roundedCorners(radius)

autoOrient(value)

rotate(angle)

blur(radius, standard)

bright(brightness)

contrast(value)

sharpen(value)

format(type)

interlace(type)

quality(value)

absQual(value)

watermark(content[, opt])

fill(color)

font(name)

fontSize(size)

textShadow(transparency)

textRotate(angle)

save(path)

stream()

toBuffer()

write(fullpath)

Stats

Development practices

Releases

Contributors

ali-img Release 0.2.0

Release 0.2.0 Toggle Dropdown 1.0.7 1.0.6 1.0.5 1.0.4 1.0.3 1.0.2 1.0.1 1.0.0 0.2.4 0.2.3

Documentation

ali-img

Usage

new AliImg(opt)

img 工厂方法

Img 实例方法

resize(opt)

circle(radius)

crop(x, y, width, height[, origin])

indexCrop(opt)

roundedCorners(radius)

autoOrient(value)

rotate(angle)

blur(radius, standard)

bright(brightness)

contrast(value)

sharpen(value)

format(type)

interlace(type)

quality(value)

absQual(value)

watermark(content[, opt])

fill(color)

font(name)

fontSize(size)

textShadow(transparency)

textRotate(angle)

save(path)

stream()

toBuffer()

write(fullpath)

Stats

Development practices

Releases

Contributors

ali-img
Release 0.2.0

Release 0.2.0

1.0.7

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

0.2.4

0.2.3