npm package: @sjtu-nic/jwb-app-invoker
Description: jwb-app-invoker
Author: yech
Latest version: 1.3.1

# @sjtu-nic/jwb-app-invoker

为了您的网页和交我办 app 通信，交我办 app 封装了一些方法供调用，使用 jwb-app-invoker 后可以很方便的调用这些封装的方法。

## Install

```
npm install @sjtu-nic/jwb-app-invoker
```

## Usage

有两种方式可供选择，如果您的项目使用 npm 管理依赖，推荐作为 es 模块导入方式：

-   作为 es 模块导入
-   使用 script 标签全局引入

### Import ES Module

```javascript
import {invoke, close, setTitle} from '@sjtu-nic/jwb-app-invoker';
...
invoke('close');
```

### Import global variable by script tag

```html
<!DOCTYPE html>
<html>
    <head>
        <!-- 将本项目dist目录中的invoker.global.prod.js放到自己网站合适的目录中并全局引入，引入后会产生全局变量JwbAppInvoker -->
        <script src="scripts/invoker.global.prod.js"></script>
    </head>
    <body>
        <div style="display: flex; flex-direction: column;">
            <!-- 调用封装在JwbAppInvoker上的方法即可 -->
            <button onclick="JwbAppInvoker.invoke('close')">close me</button>
            <button onclick="JwbAppInvoker.close()">close me</button>
        </div>
    </body>
</html>
```

### Custom

如果您使用的是定制版的交我办 App，请在引入 @sjtu-nic/jwb-app-invoker 后调用 init 方法，并传入 { custom: true } 参数。此举将跳过交我办的部分内置校验逻辑，帮助您更顺利地使用 SDK。

```javascript
// Import ES Module
import { init } from '@sjtu-nic/jwb-app-invoker';
init({ custom: true });
```

如果您使用 script 标签全局引入，请在引入链接后拼接`custom=true`参数。

```html
<!-- Import global variable by script tag -->
<script src="scripts/invoker.global.prod.js?custom=true"></script>
```

## api

目前该开发包封装了以下方法，除了特殊指明返回类型的方法，其他所有方法返回值均为布尔值表示是否调用成功，如果返回 false 多数是由交我办版本过低造成的，可提示用户升级交我办

-   invoke(methodName,param1,param2,...)

    调用 app 封装的方法，第一个参数是方法名，后面参数是 app 封装方法使用的参数，格式为{name,value}的键值对，参数次序必须和 app 封装方法的参数次序一致，使用本方法可以调用所有 app 封装的方法。

-   register(id)

    向交我办注册当前应用，其实是调用 invoke('register',{name:'certId', value:id})的快捷方式。注册后标题栏将显示网络信息中心技术支持、主管部门、联系方式等信息。参数 id 是应用认证 id，第三方可以联系网络信息中心获取。该方法开发者可自己调用，也可在 script 引用时加入注册的 id 参数，脚本引入后会自动注册。

```html
<!DOCTYPE html>
<html>
    <head>
        <!-- 引入脚本时加入id参数可自动注册 -->
        <script src="scripts/invoker.global.prod.js?id=xxxx"></script>
    </head>
</html>
```

-   isApp():boolean

    返回布尔值，判断是否在交我办中

-   getVersion():string

    返回交我办版本，如果不在交我办中会返回空字符串

-   close()

    关闭本窗口，其实是调用 invoke('close')的快捷方式

-   setTitle(title)

    设置窗口标题，其实是调用 invoke('setTitle',{name:'title',value:'新的标题'})的快捷方式

-   openLink(urlOrOptions)

    新窗口打开链接

    参数说明:<br>

    urlOrOptions 链接地址或选项对象，当其为字符串时代表链接地址，当其为对象时代表选项，包括以下内容

    -   url 必填，链接地址
    -   back 选填，是否标题栏显示回退按钮，缺省 false 显示的是关闭按钮
    -   title 选填，自定义标题，不传该参数时将自动获取页面标题作为标题
    -   color 选填，自定义标题栏颜色，不传该参数时由交我办决定标题栏颜色
    -   fullScreen 选填，是否全屏显示，缺省 false

    ```javascript
    // 打开bing网站
    openLink('https://bing.com');

    // 打开bing网站，并自定义标题
    openLink({
        url: 'https://bing.com',
        title: '搜索'
    });

    // 全屏方式打开bing网站
    openLink({
        url: 'https://bing.com',
        fullScreen: true
    });
    ```

-   closeAndOpenLink(urlOrOptions)

    新窗口打开链接，并关闭原先的窗口。

    参数说明:<br>

    urlOrOptions 链接地址或选项对象，当其为字符串时代表链接地址，当其为对象时代表选项，包括以下内容

    -   url 必填，链接地址，支持原生 url
    -   back 选填，是否标题栏显示回退按钮，缺省 false 显示的是关闭按钮
    -   title 选填，自定义标题，不传该参数时将自动获取页面标题作为标题
    -   color 选填，自定义标题栏颜色，不传该参数时由交我办决定标题栏颜色
    -   fullScreen 选填，是否全屏显示，缺省 false

-   openNative(url)

    打开交我办原生应用，其实是调用 invoke('openNative',{name:'url',value:url})的快捷方式

    目前支持的原生 url 列表如下:<br>

    -   思源码 'taskcenter://edu.sjtu.push/unicode'
    -   扫一扫 'taskcenter://edu.sjtu.push/scan'
    -   校园卡 'taskcenter://edu.sjtu.push/campusCard'
    -   日程 'taskcenter://edu.sjtu.push/schedule'
    -   消息中心 'taskcenter://edu.sjtu.push/messageCenter'
    -   应用分类 'taskcenter://edu.sjtu.push/app_list?type=分类名'

-   closeAndOpenNative(url)

    新窗口打开交我办原生应用，并关闭原先的窗口。

-   getLocation(callback ｜ LocationOptions)

    获取当前定位信息。

    参数说明:

    -   callback: (data: LocationData) => void; 回调函数；
    -   LocationOptions: callback、lang。 lang 参数为语言类型，目前支持枚举类型 LocationErrorLang:zh、en（默认中文)；

    LocationData 对象包含以下字段：

    |   字段    | 含义     |
    | :-------: | :------- |
    | latitude  | 经度     |
    | longitude | 纬度     |
    | accuracy  | 精确度   |
    | errorCode | 错误码   |
    | errorInfo | 错误信息 |

    返回错误码请参照下表：

    | 错误码 | 含义                                                                   |
    | :----: | :--------------------------------------------------------------------- |
    |   0    | 定位成功                                                               |
    |   1    | App 定位权限未开启                                                     |
    |   2    | 系统定位权限未开启                                                     |
    |   3    | 请稍后再试,或检查网络                                                  |
    |   4    | 定位失败,请重试                                                        |
    |   5    | 旧版 app 中无法判断缺失 App 定位权限或系统定位权限，返回笼统无权限信息 |
    |  999   | 解析错误，请重试                                                       |

-   startVoiceRecording(callback : string | (isSuccess: boolean) => void)

    开启语音录音，callback 参数为回调函数名称或回调函数。若为回调函数名，window 对象上应该挂载了这个名称对应的回调函数。回调函数接受一个参数 isSuccess，为 true 时表示成功，其它情况表示失败。

-   endVoiceRecording(callback : string | (data) => void)

    结束语音录音，callback 参数为回调函数名称或回调函数。若为回调函数名，window 对象上应该挂载了这个名称对应的回调函数。回调函数接受一个参数 data，内容为所录音频 base64 编码数据。

-   openSpeech(options: OpenSpeechOptions)

    打开语音识别

    参数说明:

    options 打开语音识别的选项，包括以下内容

    -   callback: (data: string) => void; 回调方法，参数为语音识别结果字符串
    -   title?: string; 语音弹窗标题(可选，默认空字符串)
    -   hint?: string; 语音弹窗提示信息(可选，默认空字符串)
    -   autoStart?: boolean; 是否自动开始语音识别(可选，默认 false)，true 自动开始识别，false 用户需长按语音按钮开始说话

    例子

```javascript
import { openSpeech } from '@sjtu-nic/jwb-app-invoker';
openSpeech({
    callback: (data) => {
        console.log('语音转换的文字:', data);
    }
});
```

-   openScanner(callback:(data:string)=>void)

    打开交我办扫码窗口，并将扫码的结果在回调方法中返回

    值得注意的是这个方法和 openNative 中打开扫码功能的区别是，openNative 中打开的扫码如果扫到一个链接会直接打开，而 openScanner 的回调方法中返回的结果需要用户自行处理

    参数说明:

    callback 扫码结果回调方法，参数为扫码结果字符串，如果用户关闭了扫码界面，将返回 null 或者空字符串

    例子

```javascript
import { openScanner } from '@sjtu-nic/jwb-app-invoker';
openScanner((data) => {
    console.log('扫码结果:', data);
});
```