1. id扫呀JS API 快速入门


    ver 0.99   2024-7

 

扫呀 JS API 是用来控制图像采集设备采集图像，生成PDF，并兼具OCR卡证识别的 Javascript 应用开发接口。它通过一致的接口，跨平台操作图像采集设备，如windows, linux, macos等。

 

一、第一个能扫描的Web页面

1. 下载安装windows客户端，
https://saoya.jatools.com/setup.exe

2. 编写网页，参照在线演示页面：

https://saoya.jatools.com/demos/hello-saoya.html

    <!-- 引入 saoya.js -->

    <script src="https://saoya.jatools.com/saoya.js"></script>

    <script>

        // 取得当前可用的扫描设备

        function getDevices() {

            getSAOYA().getCaptureDevices(devices => {

                let deviceSelect = document.getElementById("devices");

                for (const d of devices) {

                    // add option to deviceSelect

                    let option = new Option(d.name, d.id);

                    deviceSelect.appendChild(option);

                }

            });

        }

        // 采集图像

        function capture() {

            let device = document.getElementById("devices").value;

            // 从选中的扫描设置，默认参数，不启用UI,

            if (device)

                getSAOYA().capture(device, {}, false, (result) => {

                    // 显示采集到的图像

                    document.getElementById("captured").src = result.url;

                })

        }

    </script>

...

<body onload="getDevices()">

    <select id="devices"></select>

    <input type="button" value="扫描" onclick="capture()">

    <img id="captured" />

</body>

...

 

 

二、API 参考手册

  2. 1全局方法 
    1. 1.1getSAOYA 取得SAOYA实例 

原型

getSAOYA()

参数：

名称

类型

是否必选

说明

返回：SAOYA实例

­­­­­­

用法:

 

 

  1. 2SAOYA 实例方法 
    1. 2.1getCaptureDevices取得图像采集设备列表 

原型

getCaptureDevices(callback)

getCaptureDevices(type,callback)

参数：

名称

类型

是否必选

说明

type

String

可选

使用哪种扫描API获取扫描设备，在Windows下支持的扫描API有："TWAIN"和"WIA"

默认为 "WIA"

callback

Function(devices)

可选

获得设备列表后回调

devices:Array<Object>

取得的设备列表，每个设置是一个对象，有如下字段：

{

"id" // 设置id, 取设置状态，及扫描的API，都用这个来标识设备称

"name"  // 可以显示在界面上的名称

}

 

用法:

//列出可用采集设备名称，使用 WIA API

getSAOYA().getCaptureDevices(function (devices) {

    for (const d of devices) {

        console.log(d.id,d.name);

    }

}

//列出可用采集设备名称，使用 TWAIN API

getSAOYA().getCaptureDevices("TWAIN",function (devices) {

    for (const d of devices) {

        console.log(d.id,d.name);

    }

}

 

    1. 2.2getDeviceCapabilities 查询设备支持的参数 

原型

getDeviceCapabilities(device,callback)

参数：

名称

类型

是否必选

说明

device

String

必选

对哪一台设备进行查询

callback

Function(result)

必选

获得设备参数回调

result:Object/null

sources: Array<Object> ,设备的扫描口，有些打印机有多个扫描口，比如自动送纸的，和平推的。每个扫描口，是一个对象，有如下字段

{

   "id" // 扫描口id

   "type" // 扫描口类型  "Flatbed"表示平推的扫描口，"ADF" 表示自动送纸的扫描口

}

 

dpi:String, 采集分辨率, 如果以":default"结尾，是默认的分辨率；

color:String, 采集颜色模式， 如果以":default"结尾，是默认颜色模式：

"BW":黑

"Gray ":灰度

"Color": 彩色

 

result为null,表示不在线。

用法:

// 查询设备支持的参数

let device = getDevice();

getSAOYA().getDeviceCapabilities(device, function (result) {

    if (!result)

        console.log(`${device} 不在线`);

    else {

        // 支持的 DPI 列表

        for (let d of result.dpi) {

            let dpi = d.split(":")[0];

            if (dpi !== d) {

                console.log(`默认dpi:${dpi}`);

            } else

                console.log(dpi);

        }

        // 支持的颜色模式

        for (let c of result['color']) {

            let color = c.split(":")[0];

            if (color !== c) {

                console.log(`默认颜色模式:${color}`);

            } else

                console.log(color);

        }

        // 扫描口

        for (let source of result.sources) {

            log(source.id, source.type);

        }

 

    }

}

 

 

    1. 2.3capture采集图像 

原型

capture (device,settings,ui, paged,done)

参数：

名称

类型

是否必选

说明

device

String

必选

对哪一台设备进行图像采集

settings

Object

必选

图像采集参数：

source:String 从哪个扫描口采集；

dpi:String, 采集用的分辨率；

color:String, 采集使用的种颜色模式：

"BW":黑白

"Gray ":灰度

"Color": 彩色

ui

Boolean

必选

是否打开厂商的参数对话框进行采集，当共享方式使用扫呀时不支持。

paged

Function(

result:Object)

必选

采集到图像后，回调

url:String 图片的url

LORP:String,图片纵横方向推荐：
     "L" ：表示图片宽度大于高度，适合横放
     "P" ：表示图片高度大于宽度，适合纵放

done

Function()

可选

采集全部结束后回调

 

 

// 采集图像

let device = getDevice();

let settings = {

    dpi: '300'

}

getSAOYA().capture(device, settings, false, (result) => {

    console.log(`采集到图像: ${result.url}，适合${result.LORP == 'P' ? '竖' : '横'}放. `);

})

 

 

    1. 2.4chooseFile在本地选一个文件，并以url 返回 

原型

chooseFile(filter,callback)

参数：

名称

类型

是否必选

说明

filter

String

必选

文件类型过滤，以[说明](过滤字符)说明每一项，并以";;"分割，如：
"图片文件(*.jpg);;图片文件(*.png);;图片文件(*.gif);;所有(*.*)"

callback

Function(result:Object)

必选

用户选择成功或者退出文件对话框时调用

result：Object/null:

url:String 图片的url

LORP:String,图片纵横方向推荐：
     "L" ：表示图片宽度大于高度，适合横放
     "P" ：表示图片高度大于宽度，适合纵放

 

如果result为null 表示用户打开文件对话框后，选择退出

 

用法:

// 在本地选一个文件，并以url 返回

getSAOYA().chooseFile("图片文件(*.jpg);;图片文件(*.png);;图片文件(*.gif);;所有(*.*)",

    (result) => {

        if (result)

            console.log(`已选择文件，可以从这个地址访问${result.url}`);

        else

            console.log("用户没有选择文件.");

    })

 

 

 

    1. 2.5uploadImages 上传图片到服务端，支持生成PDF 

原型

uploadImages(url,images,watermark,fileType,callback)

参数：

名称

类型

是否必选

说明

url

String

必选

接收图片的 URL 地址

images

Array<Object>

必选

要上传的图片数组，每个元素是一张图片，其中属性：
url:String,该图片的url，

LORP:String, 表示纸张方向，默认为纵向

"P": 表示纵向，

"L": 表示横向，

deg:Number, 表示图片的按时针的旋转角度，允许取值为 90、180、270度，默认不旋转

watermark

String

必选

水印的HTML代码，为空则表示不设置水印

fileType

String

必选

保存的文件格式，可以是 pdf,png,jpg,gif,bmp

callback

Function(result:Object)

必选

上传结束后调用

result：

格式，用户可以自定义。

 

用法:

 

// 上传图片到服务端

let images = [];

// 第一张图片，纵向，不旋转

images[0] = { url: 'https://print.jatools.com/image/banner1.jpg' };

// 第二张图片，横向，旋转180度

images[1] = {

    url: 'https://print.jatools.com/image/banner2.jpg',

    LORP: 'L',

    deg: 180

};

// 上传格式用PDF

getSAOYA().uploadImages("http://localhost:8080/upload", images, "pdf", function (result) {

    console.log(result);

});

 

    1. 2.6exportImages 把图片导出到本地，支持PDF格式 

原型

exportImages(images,watermark,toFileType,afterExport,callback)

参数：

名称

类型

是否必选

说明

images

Array<Object>

必选

要导出的图片数组，每个元素是一张图片，其中属性：
url:String,该图片的url，

LORP:String, 表示纸张方向，不指定时表示纵向

"P": 表示纵向，

"L": 表示横向，

watermark

String

必选

水印的HTML代码，这空则表示不设置水印

toFileType

String

必选

保存的文件格式，可以是 pdf,png,jpg,gif,bmp

openFolder

Boolean

必选

保存后是否用系统的文件浏览器打开导出目录

true打开，false不打开

callback

Function(result:Object)

必选

保存后，或者放弃后调用

result：

为空则表示用户放弃选择

否则表示成功

 

用法:

//加图片导出到本地

let images = [];

images[0] = { url: 'https://print.jatools.com/image/banner2.jpg' }

getSAOYA().exportImages(images, '', 'pdf', true, function (result) {

    console.log(result);

 

});

 

 

    1. 2.7ocr卡证识别 

原型

ocr (url,cardType,callback)

参数：

名称

类型

是否必选

说明

url

String

必选

要识别的图片url

cardType

String

必选

可用卡证类型，见用法

callback

Function(result)

必选

回调，返回转换结果

result：Object，如果正常被识别，result.words_result 数组或者对象，含识别出来的内容；

1、通用("accurate_basic")证卡识别，返回的是数组，类似：

{"words_result":[{"words":"PLUS"},{"words":"除了玩水"},…}

2、其他证卡识别，返回的是对像，类似：

{"words_result":{"经营范围":{"words":"技术开发、技术…"}…}}

 

如果result含有"error",则识别出错，该字段显示出错内容

 

用法:

// 支持的证卡类别:

// accurate_basic:通用

// qrcode:二维码识别

// idcard:身份证识别

// bankcard:银行卡识别

// business_license:营业执照识别

// passport:护照识别

// overseas_passport:护照识别（港澳台地区及境外）

// social_security_card:社保卡识别

// household_register:户口本识别

// birth_certificate:出生医学证明识别

// businesslicense_verification_standard:企业工商信息查询（标准版）

// businesslicense_verification_detailed:企业工商信息查询（高级版）

// two_factors_verification:企业二要素核验

// three_factors_verification:企业三要素核验

// four_factors_verification:企业四要素核验

// hk_macau_taiwan_exitentrypermit:港澳台证件识别

// marriage_certificate:结婚证识别

// real_estate_certificate:房产证识别

// account_opening:开户许可证识别

// foreign_resident_id_card:外国人永久居住证识别

// food_business_license:食品经营许可证识别

// food_product_license:食品生产许可证识别

 

// 将一个身份证图片识别出来

let url = getURL();

getSAOYA().ocr(url, "idcard", (result) => {

    if (result && result["words_result"]) {

        //{"words_result":{"经营范围":{"location":{"top":1104,"left":531,"width":861,"height":117},

        //"words":"技术开发、技术咨询:计算机软件;其他无需报经审批的一...

        let words = [];

        let words_result = result["words_result"];

        for (let val of words_result) {

            words.push([val["words"]]);

        }

        console.log(`识别到:${words.join(",")}`);

        return;

    }

    console.log("识别出错:${result.error}");

}, function (result) {

    console.log("网络出错:${result.error}");

})

 

    1. 2.8toBase64将一个url的图片转换成Base64 

clearsettings.htm

原型

toBase64 (url,callback)

参数：

名称

类型

是否必选

说明

url

String

必选

转换的图片url

callback

Function(result)

必选

回调，返回转换结果

result：String，转换成功的base64字串

 

用法:

// 将图片从url转换到 base64 字串

getSAOYA().toBase64('https://print.jatools.com/image/banner2.jpg', function (result) {

    console.log(result);

});