cuteimage

CuteImage

使用原生 JavaScript 开发的轻量级前端图片工具助手

检测示例   ◆   压缩示例   ◆   转换示例

主要用途

多用于前端上传图片时，对图片进行：格式判断、宽高检测、文件形式转换、压缩体积等操作。

工具特点

• 完全使用原生 JavaScript 开发，无任何第三方依赖，可自由嵌入到任何前端程序中；
• 所有方法均以异步形式构建，不阻碍其它程序的执行，保证运行效率；
• 提供了多个常用的图片工具方法，满足常规的开发需要。

安装引入

cdn 引入

<script src="https://unpkg.com/cuteimage"></script>
<script src="https://cdn.jsdelivr.net/npm/cuteimage"></script>

npm 安装

npm install cuteimage -S
const CuteImage = require( "cuteimage" );

基本用法

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const isImage = await CuteImage( this.files[ 0 ] ).isImage();
        console.log( isImage ? "是图片" : "不是图片" );
    }
</script>

方法列表

• isImage
• isJPG
• isPNG
• isBMP
• isGIF
• isWEBP
• size
• calcSize
• name
• type
• toBlob
• toDataUrl
• toURL
• toFile
• dimension
• download
• compress
• getHex

isImage

• 功能：检测传入的文件流是否为图片文件，返回 Promise。
  
• 说明：此方法可准确检测出是否为真正的图片，即使将非图片文件的后缀名手动改为图片格式，也能准确识别。
  
• 注意：目前仅支持检测 jpg、jpeg、png、gif、bmp、webp 等格式，如果传入其它格式的图片，将会直接判断为不是图片！！！

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const type = await CuteImage( this.files[ 0 ] ).isImage();

        // isImage() 方法会返回检测出的图片格式
        // 如果返回空字符串，则表示不是图片
        console.log( type ? `是图片，格式为：${ type }` : "不是图片" );
    }
</script>

isJPG

• 功能：检测传入的文件流是否为 jpg 或 jpeg 图片，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 false，否则会正常返回 isJPG 的检测结果：true 或 false。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const isJPG = await CuteImage( this.files[ 0 ] ).isJPG();
        console.log( isJPG ? "是 jpg 图片" : "不是 jpg 图片" );
    }
</script>

isPNG

• 功能：检测传入的文件流是否为 png 图片，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 false，否则会正常返回 isPNG 的检测结果：true 或 false。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const isPNG = await CuteImage( this.files[ 0 ] ).isPNG();
        console.log( isPNG ? "是 png 图片" : "不是 png 图片" );
    }
</script>

isBMP

• 功能：检测传入的文件流是否为 bmp 图片，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 false，否则会正常返回 isBMP 的检测结果：true 或 false。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const isBMP = await CuteImage( this.files[ 0 ] ).isBMP();
        console.log( isBMP ? "是 bmp 图片" : "不是 bmp 图片" );
    }
</script>

isGIF

• 功能：检测传入的文件流是否为 gif 图片，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 false，否则会正常返回 isGIF 的检测结果：true 或 false。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const isGIF = await CuteImage( this.files[ 0 ] ).isGIF();
        console.log( isGIF ? "是 gif 图片" : "不是 gif 图片" );
    }
</script>

isWEBP

• 功能：检测传入的文件流是否为 webp 图片，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 false，否则会正常返回 isWEBP 的检测结果：true 或 false。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const isWEBP = await CuteImage( this.files[ 0 ] ).isWEBP();
        console.log( isWEBP ? "是 webp 图片" : "不是 webp 图片" );
    }
</script>

size

• 功能：获取传入的图片（文件流）的体积，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 0 或 null（在传入 true 参数的情况下），否则会正常返回 size 的获取结果。
• 参数：此方法可根据需要传入一个 true 做为参数，此时返回结果将变为数组形式，包含两个值：
  • 文件体积的字节数
  • 格式化后的文件体积（带有 KB、MB、GB、TB、PB 等单位）

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const size1 = await CuteImage( this.files[ 0 ] ).size();
        console.log( `体积：${ size1 }` );

        const size2 = await CuteImage( this.files[ 0 ] ).size( true );
        console.log( `体积：${ size2 }` );
    }
</script>

calcSize

• 功能：返回传入的字节数的格式化后的体积。
  

<script>
    console.log( CuteImage().calcSize( 5698268 ) )  // 5.43MB
</script>

name

• 功能：获取传入的图片（文件流）的名称，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回空字符串，否则会正常返回 name 的获取结果。
  
• 参数：此方法可根据需要传入一个 true 做为参数，此时返回结果将不包含图片格式信息。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const name = await CuteImage( this.files[ 0 ] ).name();
        console.log( `图片名：${ name }` );
    }
</script>

type

• 功能：获取传入的图片（文件流）的格式，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回空字符串，否则会正常返回 type 的获取结果。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const type = await CuteImage( this.files[ 0 ] ).type();
        console.log( `图片格式：${ type }` );
    }
</script>

toBlob

• 功能：将传入的图片（文件流）转换为 blob 形式 ，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 null，否则会正常返回 toBlob 的转换结果。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const blob = await CuteImage( this.files[ 0 ] ).toBlob();
        console.log( blob );
    }
</script>

toDataUrl

• 功能：将传入的图片（文件流）转换为 dataUrl 形式 ，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回空字符串，否则会正常返回 toDataUrl 的转换结果。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const dataUrl = await CuteImage( this.files[ 0 ] ).toDataUrl();
        console.log( dataUrl );
    }
</script>

toURL

• 功能：将传入的图片（文件流）转换为 url 形式 ，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回空字符串，否则会正常返回 toURL 的转换结果。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const url = await CuteImage( this.files[ 0 ] ).toURL();

        // 此 url 可直接设置到 <img> 的 src 属性中
        console.log( url );
    }
</script>

toFile

• 功能：将传入的图片（类型：File 或 Blob 或 DataUrl）转换为 File 文件流形式 ，返回 Promise。
  
• 说明：此方法会先判断传入的参数是否符合类型要求，然后判断是否为 isImage 方法中所列出的所支持的图片格式，如果不符合上述两点，则直接返回 null，否则会正常返回 toFile 的转换结果。
  
• 注意：
  • 此方法可传入一个参数，用来设置转换后的图片名称，如果忽略此参数，将会自动以一个随机字符串命名。另外，如果传入的参数本身就是符合要求的图片文件流，则直接取原始文件流中的 name。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const file = await CuteImage( this.files[ 0 ] ).toFile( "自定义的图片名称" );
        console.log( file );
    }
</script>

dimension

• 功能：获取传入的图片（文件流）的宽高尺寸，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 null，否则会正常返回 dimension 的获取结果，是数组形式，包含四个值：宽度、高度、宽高比、高宽比。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const dimension = await CuteImage( this.files[ 0 ] ).dimension();
        console.log( dimension );
    }
</script>

download

• 功能：下载传入的图片（文件流），返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 false，否则根据下载情况返回 true 或 false。
• 注意：
  • 此方法可传入一个参数，用来设置下载后的图片名称，如果忽略此参数，将会自动以一个随机字符串命名。
  • 如果一切解析正常，会自动调用浏览器的下载功能进行图片下载，上述的 true 和 false 仅是做为是否成功下载的标识，并且在调起浏览器下载功能后就返回结果，不会等待是否下载完成。

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {
        const result = await CuteImage( this.files[ 0 ] ).download( "自定义的图片名称" );
        console.log( result ? "下载成功" : "下载失败" );
    }
</script>

compress

• 功能：对传入的图片（文件流）进行压缩，返回 Promise。
  
• 说明：此方法内部会先调用 isImage 方法，如果检测出不是图片则直接返回 null，否则会返回压缩结果（压缩成功则返回压缩后的数据，压缩失败返回 null）。
• 注意：
  • 不支持压缩 gif 格式的图片；
  • 压缩后的图片将一律转换为 jpg 格式；
  • 如果原始图片是 png 或 webp 格式且包含透明通道，压缩后由于转换成了 jpg 格式，因此原有的透明通道将失效；
  • 受限于浏览器的性能和渲染限制，对于超大体积（数百MB 甚至达到 GB）或者超大宽高尺寸（宽高均达到数万像素）的图片，不能保证压缩成功。
• 参数：
  • quality：压缩后的图片质量，取 0 - 1 之间的数字，默认值：0.75
  • dimension：压缩后的图片宽高尺寸，支持 Array 和 Function 类型，默认值：[ 1920 ]
    • 若设置为 Array 类型，规则是：[ width, height ]，其中 width 必填，若省略 height，则按照原始宽高比自动设置高度；
    • 若设置为 Function 类型，则可根据实际需要动态设置宽高，函数会将原始宽高做为参数提供给开发者使用，注意，在函数最后需要返回包含宽/高的数组。
• 返回值：
  • dataUrl：压缩后的图片 dataUrl 编码
  • blob：压缩后的图片 blob 流
  • url：压缩后的图片 url 形式
  • file：压缩后的图片文件流（其中包含了一个自定义属性 __calcSize__，表示格式化后的体积）
  • dimension：压缩后的图片宽高尺寸
  • originalFile：原始图片文件流（其中包含了一个自定义属性 __calcSize__，表示格式化后的体积）

<input id="file" type="file" accept="image/*" />

<script>
    document.getElementById( "file" ).onchange = async function () {

        // 此示例中 compress 方法未传入任何参数
        // 则压缩后的图片质量为 0.75，宽度为 1920px，高度按照原始宽高比自动设置
        const result1 = await CuteImage( this.files[ 0 ] ).compress();
        console.log( result1 );


        // 此示例中 compress 方法传入了如下参数
        // 则压缩后的图片质量为 0.6，宽度为 1000px，高度为 500px
        const result2 = await CuteImage( this.files[ 0 ] ).compress({
            quality: 0.6,
            dimension: [ 1000, 500 ]
        });
        console.log( result2 );


        // 此示例中 compress 方法传入了如下参数
        // 则压缩后的图片质量为 0.7，宽高均为原始宽高的一半
        const result3 = await CuteImage( this.files[ 0 ] ).compress({
            quality: 0.7,
            dimension ( width, height, ratioWH, ratioHW ) {

                // width   => 代表原始宽度
                // height  => 代表原始高度
                // ratioWH => 代表原始宽高比
                // ratioHW => 代表原始高宽比
                return [ width / 2, height / 2 ];
            }
        });
        console.log( result3 );
    }
</script>

浏览器支持

Chrome	Firefox	Opera	Edge	Safari	IE
last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions	不支持