@sjtu-nic/jwb-app-invoker

v1.3.1

Published

3 months ago

jwb-app-invoker

0High
0Medium
0Low

@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

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

Import global variable by script tag

<!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。

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

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

<!-- 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 参数，脚本引入后会自动注册。

<!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)
新窗口打开链接
参数说明:
urlOrOptions 链接地址或选项对象，当其为字符串时代表链接地址，当其为对象时代表选项，包括以下内容
- url 必填，链接地址
- back 选填，是否标题栏显示回退按钮，缺省 false 显示的是关闭按钮
- title 选填，自定义标题，不传该参数时将自动获取页面标题作为标题
- color 选填，自定义标题栏颜色，不传该参数时由交我办决定标题栏颜色
- fullScreen 选填，是否全屏显示，缺省 false
```
// 打开bing网站
openLink('https://bing.com');

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

// 全屏方式打开bing网站
openLink({
    url: 'https://bing.com',
    fullScreen: true
});
```
closeAndOpenLink(urlOrOptions)
新窗口打开链接，并关闭原先的窗口。
参数说明:
urlOrOptions 链接地址或选项对象，当其为字符串时代表链接地址，当其为对象时代表选项，包括以下内容
- url 必填，链接地址，支持原生 url
- back 选填，是否标题栏显示回退按钮，缺省 false 显示的是关闭按钮
- title 选填，自定义标题，不传该参数时将自动获取页面标题作为标题
- color 选填，自定义标题栏颜色，不传该参数时由交我办决定标题栏颜色
- fullScreen 选填，是否全屏显示，缺省 false
openNative(url)
打开交我办原生应用，其实是调用 invoke('openNative',{name:'url',value:url})的快捷方式
目前支持的原生 url 列表如下:
- 思源码 '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 用户需长按语音按钮开始说话
例子

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

openScanner(callback:(data:string)=>void)
打开交我办扫码窗口，并将扫码的结果在回调方法中返回
值得注意的是这个方法和 openNative 中打开扫码功能的区别是，openNative 中打开的扫码如果扫到一个链接会直接打开，而 openScanner 的回调方法中返回的结果需要用户自行处理
参数说明:
callback 扫码结果回调方法，参数为扫码结果字符串，如果用户关闭了扫码界面，将返回 null 或者空字符串
例子

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sjtu-nic/jwb-app-invoker

Install

Usage

Import ES Module

Import global variable by script tag

Custom

api