移动端 JSAPI
## 一.快速接入
### 1.引入JS
```html
<script type="text/javascript" src="http://ip:port/sdko/context/ws.loader.js"></script>
```
### 2.定义视图节点
文件签字视图会在已定义的div节点内渲染。请指定有效的height、width风格样式，请保证id的唯一性。
```javascript
<div id="ctx" style="height: 100%; width: 100%;"></div>
```
### 3.引入移动端API，并实例化渲染
``` javascript
WSLoader.loadMobile(() => { // 引入移动端AP
var ctx = new WSContext('#ctx', { // 实例化
token: 'xxx', // token
fileIds: 'xxx1,xxx2', // 文件 id 字符串，多文件使用逗号分隔
userId: 'xxx',
userName: 'xxx'
})
})
```
***请勿将`ctx`对象放到 `vue` 的 `data` 、 `react` 的 `state` 中***
### 4.查看JSAPI版本号
```javascript
const version = WSContext.version
```
## 二.基础配置
- **`token: string`**：授权口令
- **`fileIds: string`**：文件签字ID信息，多个文件用`,`分隔
- **`userId: string`**：用户ID
- `userName: string`：用户名称
- `baseURL: string`：好签SDKO后台接口请求地址,不配置默认取引用的js访问地址前缀
```javascript
const ctx = new WSContext('#ctx', {
token: 'xxx',
fileIds: 'xxx1,xxx2',
userId: 'wellsign',
userName: '好签',
baseURL: 'http://test.wellsign.cn:28080/sdko'
})
```
## 三.功能
### 1.签名模板
#### 配置项
- `isSignboardAutoAdd: boolean`：签名模板新增的签名是否自动插入到文件中，默认`true`
- `isWithTimestamp: boolean`：插入签名模板的时候是否自动插入时间戳，默认`false`
- `signtmplWidth: number`：插入签名模板时的初始最值，即宽高的最大值，默认`100`
- `>= 1`时，宽度单位为`px`,例：`100`时，显示宽度为`100px`
- `< 1`时，宽度单位为**页宽**的比例，例：`0.3`时，宽度为页宽的`30%`
- `timestampWidth: number`：插入的时间戳的文本宽度，默认`100`
- `>= 1`时，宽度单位为`px`,例：`100`时，显示宽度为`100px`
- `< 1`时，宽度单位为**页宽**的比例，例：`0.3`时，宽度为页宽的`30%`
- `timestampDistance: number`：插入的时间戳和签名的距离，默认`10`
- `>= 1`时，距离单位为`px`,例：`15`时，显示距离为`15px`。
- `< 1`时，距离单位为**页宽**的比例，例：`0.1`时，距离为页宽的`10%`。
- `timestampPosition: string`：时间戳相对签名的位置，默认`bottom`正下方
- `topLeft、top、topRight`：上左、上、上右
- `rightTop、right、rightBottom`：右上、右、右下
- `bottomLeft、bottom、bottomRight`：下左、下、下右
- `leftTop、left、leftBottom`：左上、左、左下
- 
- `timestampFormat: Function`：定义签名的时间戳格式
- `isGroupSelect: boolean`：签名模板和时间戳是否绑定选中，默认`false`
- `isGroupSelectSingle: boolean`：签名模板和时间戳绑定选中后，是否支持选中单个，默认`true`
```javascript
new WSContext('#ctx', {
isSignboardAutoAdd: true,
isWithTimestamp: false,
signtmplWidth: 100,
timestampWidth: 100,
timestampDistance: 10,
timestampPosition: 'bottom',
timestampFormat: () => {
return ['2022年10月01日', '2022-02-02']
},
isGroupSelect: false,
isGroupSelectSingle: true
})
```
#### insertSignTemp
描述：弹出签名模板窗口，插入签名模板。
```javascript
ctx.insertSignTemp()
```
#### addSigntmpl
描述：点击插入签名模板
参数：`tmplId: string`签名模板id。
```javascript
ctx.addSigntmpl('xxx')
```
### 2.签字板
#### showSignboard
描述：显示签字板，以插入签名，此签名不会保存为签名模板
参数：
- `pageIdx: number`：页码，从0开始计数。
- `rx:number`：签名X轴坐标/页宽，0-1。
- `ry:number`：签名Y轴坐标/页高，0-1。
- `rw:number`：签名宽度/页宽，0-1。
- `ry:number`：签名高度/页高，0-1。
```javascript
// 不传参数时会把笔迹插入到签字界面中央。
ctx.showSignboard()
// 传参数时会插入到指定页，指定位置。
ctx.showSignboard(1, 0.1, 0.1, 0.3, 0.2)
```
#### closeSignboard
描述：关闭签字板
```javascript
ctx.closeSignboard()
```
#### 签字板显示隐藏回调
- `onSignboardShow: Function`：签字板显示回调
- `onSignboardHide: Function`：签字板隐藏回调
```javasctipt
new WSContext('#ctx', {
onSignboardShow: () => {
// ...to do
},
onSignboardHide: () => {
// ...to do
}
})
```
#### 签字板笔迹参数设置
- `setSize(size: number)`：设置签字板笔迹尺寸，`size: number`笔迹的粗细，范围`1-9`
- `setColor(color: string)`：设置签字板笔迹颜色，`color: string`笔迹的颜色
- `clear()`：清除签字板的笔迹
- `setEraser(value: boolean)`：设置签字板是否进入擦除状态
- `true`：进入擦除状态
- `false`：进入书写状态
- `ok()`：确认插入签字板上的笔迹
- `close()`：关闭签字板
- 手笔分离状态、打开关闭，同 `isSeparate`、`setIsSeparate`
```javascript
ctx.signboard.setSize(5)
ctx.signboard.setColor('#00a0ff')
ctx.signboard.clear()
ctx.signboard.setEraser(true)
ctx.signboard.ok()
ctx.signboard.close()
```
### 3.文本&文本模板
#### 配置项
- `usePowerTxtModal: boolean`：使用更强大的文本输入框功能，可以调整文本颜色、字体、常用语功能。
#### insertIText
描述：插入文本到文件
```javascript
ctx.insertIText()
```
#### onITextEdit
类型： `Function`
描述：通过`onITextEdit`自定义文本输入框
```javasctipt
new WSContext('#ctx', {
onITextEdit: (text: string, color: string, fontId: number, textAlign: 'left' | 'right' | 'center') => new Promise((resolve) => {
const newText = prompt('请输入文本', text)
if (newText !== null) {
resolve({
text: newText ,
color: '#00a0ff',
fontId: 2,
textAlign: 'left'
})
}
}),
})
```
#### addIText
描述：自定义插入文本。如果自定义文本输入框，可以配合`onITextEdit`回调方法使用。
参数：
- `text: string`文本字符串
- `color: string`文本颜色
- `fontId: number`字体ID，1宋体、2仿宋、3楷体、4黑体。
- `fontSize: number`文本大小，插入文件后展示的文本大小，建议20。
- `pageIdx?: number`插入页的页码。从`0`计数
- `x?: number`插入中心点坐标和页宽的比。`0-1`。
- `y?: number`插入中心点坐标和页宽的比。`0-1`。
- `textAlign?: 'left' | 'center' | 'right'`文本对齐方式。默认left居左
(**pageIdx、x、y改为非必传 参数，没有传值时，会将文本插入到签字界面中央**)
```
// 插入文本 hellow world!，颜色 #00a0ff，宋体，显示大小20px，签字界面中央。
ctx.addIText('hello world!', '#00a0ff', 1, 20)
// 插入文本 hellow world!，颜色 #00a0ff，宋体，显示大小20px，第1页，页面中央。
ctx.addIText('hello world!', '#00a0ff', 1, 20, 0, 0.5, 0.5, 'center')
// 插入文本 hellow world!，颜色 #00a0ff，宋体，居中，显示大小20px，签字界面中央。
ctx.addIText('hello world!', '#00a0ff', 1, 20, undefined, undefined, undefined, 'center')
```
#### insertTexttmpl
描述：显示文本模板窗口
```javascript
ctx.insertTexttmpl()
```
### 4.图片
#### insertImage
描述：插入图片到文件
```javascript
ctx.insertImage()
```
### 5.圈批
#### 配置项
- `isSeparate: boolean`：是否启动手笔分离，默认`false`
- `isCustomStroke: boolean`：是否自定义圈批工具栏，值为`true`时将不显示好签默认的圈批工具栏。默认`false`
- `isMemoryStrokeInfo: boolean`:是否开启，记忆圈批、签字板的笔迹粗细信息。默认`false`
```javasctipt
new WSContext('#ctx', {
isSeparate: false，
isCustomStroke：false,
isMemoryStrokeInfo: false
})
```
#### 回调方法
- `onEnterStroke: Function`：当签字界面进入圈批状态
- `onQuitStroke: Function`：当签字界面退出圈批状态
- `onStrokeStart: Function`：圈批状态下，当用户开始书写
```javasctipt
new WSContext('#ctx', {
onEnterStroke: () => {
// 进入圈批状态
},
onQuitStroke: () => {
// 进入圈批状态
},
onStrokeStart: () => {
// 用户开始书写
}
})
```
#### enterStroke
描述：进入圈批
```javascript
await ctx.enterStroke()
```
#### quitStroke
描述：退出圈批
```javascript
await ctx.quitStroke()
```
#### clearStroke
描述：清除当前页上的圈批笔迹
```javascript
await ctx.clearStroke()
```
#### switchStrokeState
描述：切换圈批状态。如果签字界面不在圈批模式，会主动进入圈批模式。
参数：
- `shapeFillR` 实心矩形
- `shapeR` 矩形
- `shapeC` 圆形
- `shapeL` 直线
- `shapeA` 箭头
- `stroke` 笔迹书写
- `eraser` 橡皮擦
```javascript
await ctx.switchStrokeState('stroke')
```
#### isInStroke
描述：界面中的文件是否在圈批状态。
```javascript
const isInStroke:boolean = ctx.isInStroke
```
#### setIsSeparate
描述：设置手笔分离状态
```javascript
await ctx.setIsSeparate(false) // false 关闭手笔分离，true 开启手笔分离
```
#### setStrokeSize
描述：设置圈批笔迹的粗细
参数：`size: number`笔迹的粗细，范围`1-8`
```javascript
await ctx.setStrokeSize(4)
```
#### setStrokeColor
描述：设置圈批笔迹的颜色
参数：`color: string`笔迹的颜色
```javascript
await ctx.setStrokeColor('#00a0ff')
```
### 6.验签
#### 配置项
- `verifyMod: 'readonly' | 'readwrite' | 'readwrite-myself'`：验签模式。默认'readwrite-myself'
- `readonly` 验签只读模式，只能查看验签信息
- `readwrite` 验签读写模式，可以查看、删除所有验签信息
- `readwrite-myself`验签签字人读写模式，可以查看所有验签、删除自己的验签信息
```javascript
new WSContext({
verifyMod: 'readwrite-myself'
})
```
#### showVerifyModal
描述：显示验签弹窗
```javascript
ctx.showVerifyModal()
```
#### getVerifyArr
描述：获取验签数据
```
interface VerifyData {
type: number // 类型,0签名，1图片，2文本，3批注，6批注，8注释
id: string // 数据ID
data: number // 时间
p: string // 位置信息 x, y, width, height
ps: string // 页尺寸 width,height
sI: string // 签署人ID, 对应userId
sN: string // 签署人名称，对应userName
page: number // 页码
}
const verifyArr: VerifyData[] = ctx.getVerifyArr()
```
#### selectVerify
描述：选中验签数据
```
const verifyArr = ctx.getVerifyArr()
ctx.selectVerify(verifyArr[0]) // 选中第一个验签
```
#### deselectVerify
描述：取消选中验签数据
```
ctx.deselectVerify()
```
#### deleteVerify
描述：删除验签数据
```
const verifyArr = ctx.getVerifyArr()
ctx.deleteVerify(verifyArr[0]) // 删除第一个验签
```
### 7.缩略图
#### showThumbModal
描述：显示缩略图弹窗
```javascript
ctx.showThumbModal()
```
#### getThumb
描述：获取文件缩略图
参数：
- `startIdx`：起始页序号（从0计数，包括此页）
- `endIdx`：结束页序号（从0计数，不包括此页）
```javascript
const arr: string[] = await ctx.getThumb(0, 10) // 获取从0 - 9 页的缩略图
```
#### getPageTotal
描述：获取文件总页数
```javascript
const pageTotal: number = ctx.getPageTotal()
```
### 8.保存
#### haveUnsaveData
描述：当前文件是否有未保存的数据
```javascript
const isHave: boolean = ctx.haveUnsaveData()
```
#### haveUnsaveDataAll
描述：多文件渲染时,检查所有文件是否有未保存的数据
```javascript
const isHaveArr: boolean[] = ctx.haveUnsaveDataAll()
```
#### save
描述：保存当前文件的数据
```javascript
const result = await ctx.save()
// result: { success: boolean, msg: string }
```
#### saveAll
描述：多文件渲染时，保存所有文件的笔迹数据
```javascript
const resultArr = await ctx.saveAll()
// result: { success: boolean, msg: string }[]
```
#### isExportRecord
类型：`boolean`
描述：是否在保存的返回当次保存的笔迹信息。默认`false`。
```
const result = await ctx.save()
const signRecords: ISignRecord[] = result.data.signRecords
interface ISignRecord {
type: 'signname' | 'image' | 'itext' | 'line' | 'circ' | 'rect' | 'stroke', // 笔迹类型 签名、图片、文本、直线、椭圆、矩形、圈批
x: number, // 笔迹X坐标 和页宽百分比
y: number, // 笔迹Y坐标 和页高百分比
w: number, // 笔迹宽度 和页宽百分比
h: number, // 笔迹高度 和页高百分比
rotate: number, // 笔迹旋转角度
base64: string, // 笔迹图片 base64 字符串
page: number // 页码，从0计数
}
```
### 9.印章
#### insertSeal
描述：插入印章到页面中
参数：`option: { surname: string, personalName: string, sealColor: string, alpha?: number, dateTime: string }`
- `surname: string` 印章 姓
- `personalName: string`印章 名称
- `sealColor: string`印章 颜色
- `alpha?: number`印章透明度，0-1
- `dateTime?: string`印章日期
- `defaultSize?: number`插入到签字界面后印章显示大小，单位`px`，默认`150`
```
ctx.insertSeal({
surname: '郝',
personalName: '签',
sealColor: '#dd444c',
alpha: 0.8,
dateTime: '2022-08-08'
})
ctx.insertSeal({
surname: '郝',
personalName: '签',
sealColor: '#dd444c',
alpha: 0.8,
dateTime: '2022-08-08',
defaultSize: 50
})
```
### 10.水印
#### 配置项
- `useWaterMark: boolean`：是否显示水印，默认`false`
- `waterMarkText: string`：水印文本内容，默认`签字用好签`
- `waterMarkColor: string`：水印文字颜色，默认`rgba(220, 220, 220, 0.3)`
```javascript
new WSContext('#ctx', {
useWaterMark: true,
waterMarkText: '签字用好签',
waterMarkColor: 'rgba(0, 0, 0, 0.2)'
})
```
### 11.屏幕同步
#### 配置项
- `useAsyncScreen: boolean`：是否默认开启屏幕同步功能，默认`false`
- `useAsyncScreenHost: boolean`：是否是屏幕同步的主机（只有主机能滚动签字界面）,默认`false`
- `useAsyncScreenSendTimer: number`：屏幕同步主机发送消息的时间间隔，单位毫秒，默认`500`
```javascript
new WSContext('#ctx', {
useAsyncScreen: true,
useAsyncScreenHost: true,
useAsyncScreenSendTimer： 500
})
```
#### openAsyncScreen
描述：开启屏幕同步功能（默认未开启屏幕同步功能时，可以调用本方法开启）
参数：
- `useHost: boolean`是否是主机，默认`false`。
```javascript
// 开启屏幕同步，并是主机。可通过此方式设置为主机
ctx.openAsyncScreen(true)
// 开启屏幕同步，不是主机。
ctx.openAsyncScreen(false)
```
#### closeAsyncScreen
描述：关闭屏幕同步功能
```javascript
ctx.closeAsyncScreen()
```
### 12.录音
#### insertAudio
描述：显示录音弹窗
权限：需运行在 localhost 或 https 的地址，并通过浏览器的录音权限
```javascript
ctx.insertAudio()
```
### 13.注释
#### showAnnoModal
描述：显示注释弹窗
```javascript
ctx.showAnnoModal()
```
### 13.其他功能
#### 配置项
- `renderBottomTools: boolean`：是否渲染底部工具栏
- `safeAreaHeight: number`：安全区域高度。默认`0`
- `isReadSigData: boolean`：是否读取/显示文件自带的验签信息。默认`false`
- `useCommitUpdate: boolean`: 已提交的笔迹可选中、编辑、移动、调整尺寸、删除。笔迹是否可选中同时受验签模式的影响。默认`false`
- `useAutoStorage: boolean`: 是否开启定时暂存功能。默认`false`。开启后用户已添加、未保存的笔迹可以定时暂存到后台，避免页面刷新导致签字笔迹丢失。
- `autoStorageTime: number`：定时暂存的时间长度，单位“毫秒”。默认`15000`，15秒。
- `useRealTimeDisplay: boolean`:是否实时显示其他用户签署笔迹数据，默认`false`
- `useImgRender`: boolean：是否在开启纯图PDF渲染模式。默认`false`。由于兼容性问题，在部分版本老旧的浏览器、web容器运行时，会出现文字部分丢失的现象，需要设置成`true`，文本才能正常渲染出来。(此功能也需要好签后台配置开启，如签字界面需要运行在钉钉手机端、旧版本chromium内核浏览器，请联系好签打开此功能)
#### 回调方法
- `onRenderEnd: Function`：渲染结束回调方法
- `onSave: Function`：保存结束回调
- `onPsdModalCancel: Function`：当用户数据文件密码点击取消的回调
- `onScrollEnd: Fucntion`：当签字界面滚动结束
- `onAddSigntmplClick: Function`：通过`addSigntmpl`方法添加签名时，用户点击插入签名时的回调
- `onDeleteVerify： Function`：当用户删除已保存笔迹时回调
```javascript
const ctx = new WSContext('#ctx' {
onRenderEnd: (result) => {
// result = { success: boolean, msg?: string, data?: { fileId: string, pageTotal: number } }
},
onSave: (result) => {
// result = { success: boolean, msg: string, data?: { fileId: string } }
}
onPsdModalCancel: () => {},
onScrollEnd: (pageNum: number) => {
// 当前界面页码
},
onAddSigntmplClick: () => {},
onDeleteVerify: (verifyArr: IVerify[]) => {
// verifyArr 被删除的笔迹验签信息数组
}
})
```
#### scrollToPage
参数：`pageNumber: number`页码，从0计数
描述：滚动到指定页
```javascript
await ctx.scrollToPage(10)
```
#### corePageIdx
描述： 获取签字界面中心页码，下标从0计数
```javascript
const pageNum = ctx.corePageIdx
```
#### zoomTo
参数：`zoom: number`，范围`zoom <= 4 && zoom >= 1`
描述：签字界面缩放
```javascript
ctx.zoomTo(2)
```
#### pushBlank
描述：新增空白页
```javascript
ctx.pushBlank()
```
#### switchFile
参数： `fileId: string` signInfos中文件的fileId
描述：多文件渲染时，切换文件。
```javascript
ctx.switchFile('xxx')
```
#### resize
描述：当父容器大小变化时，调整签字界面尺寸
```javascript
ctx.resize()
```
#### destroy
描述：销毁签字界面
```javascript
ctx.destroy()
ctx = undefined
```