移动端JSAPI
## 1.快速接入
### 1.1引入JS、CSS文件
获取 [CSS最新资源](https://pub.wellsign.cn/sdko/h5/V2.3.0/ws.sdko.m.css) 到本地,并引入CSS文件
```javascript
<link rel="stylesheet" href="本地路径/ws.sdko.m.css" />
```
获取 [JS最新资源](https://pub.wellsign.cn/sdko/h5/V2.3.0/ws.sdko.m.js) 到本地,并引入js文件
```javascript
<script type="text/javascript" src="本地路径/ws.sdko.m.js"></script>
```
### 2.定义视图节点
文件签字视图会在已定义的div节点内渲染。请指定有效的height、width风格样式,请保证id的唯一性。
```javascript
<div id="ctx" style="height: 100%; width: 100%;"></div>
```
### 3.渲染
``` javascript
var ctx = new WSContext('#ctx', { // 实例化
token: 'xxx', // token
fileIds: 'xxx1, xxx2', // 文件 id 字符串,多文件使用逗号分隔
userId: 'xxx',
userName: 'xxx',
baseURL: 'http://ip:28080/sdko' // SDK接口请求地址
})
```
## 2.配置
### token、必传
类型:`string`
描述:授权口令
### fileIds、必传
类型:`string`
描述:签字文件信息
### userId、必传
类型:`string`
描述:用户Id
### userName
类型:`string`
描述:用户名称
### baseURL
类型:`string`,如`http://ip:28080/sdko`
描述:SDK接口请求地址
### renderBottomTools
类型:`boolean`
描述:渲染底部工具栏
### isCustomStroke
类型: `boolean`
描述:是否自定义圈批工具栏,值为`true`时将不显示好签默认的圈批工具栏。默认`false`
### safeAreaHeight
类型:`number`
描述:安全区域高度。默认`0`
### modalWrapId
类型:`string`
描述:好签弹出层挂载节点的ID,如果挂载在body下面,弹窗层`position`为`fixed`,否则为`absolute`
### isSeparate
类型:`boolean`
描述:是否启动手笔分离,默认`false`
### isWithTimestamp
类型:`boolean`
描述:插入签名模板的时候是否自动插入时间戳,默认`false`。
### signtmplWidth
类型:`number`
描述:插入签名模板时的初始最值,即宽高的最大值,默认`100`。
- `>= 1`时,宽度单位为`px`,例:`100`时,显示宽度为`100px`。
- `< 1`时,宽度单位为**页宽**的比例,例:`0.3`时,宽度为页宽的`30%`。
### timestampWidth
****注意:原有参数`timestampFontsize`已删除,已被此参数替换。****
类型:`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`:左上、左、左下
![16736615571.png](https://cos.easydoc.net/66058286/files/lcvavsiq.png)
### timestampFormat
类型:`Function`
描述:定义签名的时间戳格式
```javascript
new Context('#ctx', {
timestampFormat: () => {
return ['2022年10月01日', '2022-02-02']
}
})
```
### isGroupSelect
类型:`boolean`
描述:签名模板和时间戳是否绑定选中,默认`false`。
### isGroupSelectSingle
类型:`boolean`
描述:签名模板和时间戳绑定选中后,是否支持选中单个,默认`true`
### commitSelectEvent
类型:`('delete')[]`
描述:设置已经提交的笔迹交互事件,默认`[]`无交互。
参数类型:
- `delete`可点击选中,显示删除按钮。(是否显示删除同时受验签模式影响)
```
new WSContext({
commitSelectEvent: ['delete'] // 已提交的笔迹可选中,显示删除按钮
})
```
### isSignboardAutoAdd
类型:`boolean`
描述:签名模板新增的签名是否自动插入到文件中,默认`true`。
### verifyMod
类型:`'readonly' | 'readwrite' | 'readwrite-myself'`
描述:验签模式。默认'readwrite-myself'
- `readonly` 验签只读模式,只能查看验签信息
- `readwrite` 验签读写模式,可以查看、删除所有验签信息
- `readwrite-myself`验签签字人读写模式,可以查看所有验签、删除自己的验签信息
### 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计数
}
```
### isReadSigData
类型:`boolean`
描述:是否读取/显示文件自带的验签信息。默认`false`
## 3.回调方法
### onRenderEnd
类型:`Function`
描述:渲染结束回调方法。
```javascript
new Context('#ctx', {
onRenderEnd: (result) => {
// result = { success: boolean, msg?: string, data?: { fileId: string, pageTotal: number } }
}
})
```
### onSave
类型:`Function`
描述:保存结束回调
```javascript
new Context('#ctx', {
onSave: (result) => {
// result = { success: boolean, msg: string, data?: { fileId: string } }
}
})
```
### onPsdModalCancel
类型:`Function`
描述:当用户数据文件密码点击取消的回调
```javasctipt
new WSContext('#ctx', {
onPsdModalCancel: () => {
// 用户点击了取消
}
})
```
### onEnterStroke
类型:`Function`
描述:当签字界面进入圈批状态
```javasctipt
new WSContext('#ctx', {
onEnterStroke: () => {
// 进入圈批状态
}
})
```
### onQuitStroke
类型:`Function`
描述:当签字界面退出圈批状态
```javasctipt
new WSContext('#ctx', {
onQuitStroke: () => {
// 进入圈批状态
}
})
```
### onStrokeStart
类型:`Function`
描述:圈批状态下,当用户开始书写。
```
new WSContext('#ctx', {
onStrokeStart: () => {
// 用户开始书写
}
})
```
### onScrollEnd
类型:`Function`
描述:当签字界面滚动结束
```javasctipt
new WSContext('#ctx', {
onScrollEnd: (pageNum: number) => {
// 当前界面页码
}
})
```
### onSignboardShow
类型:`Function`
描述:签字板显示回调
```javasctipt
new WSContext('#ctx', {
onSignboardShow: () => {}
})
```
### onSignboardHide
类型:`Function`
描述:签字隐藏回调
```javasctipt
new WSContext('#ctx', {
onSignboardHide: () => {}
})
```
### onAddSigntmplClick
类型: `Function`
描述:通过`addSigntmpl`方法添加签名时,用户点击插入签名时的回调。
```javasctipt
new WSContext('#ctx', {
onAddSigntmplClick: () => {}
})
```
### onITextEdit
类型: `Function`
描述:通过`onITextEdit`自定义文本输入框
```javasctipt
new WSContext('#ctx', {
onITextEdit: (text, color, fontId) => new Promise((resolve) => {
const newText = prompt('请输入文本', text)
if (newText !== null) {
resolve({
text: newText ,
color: '#00a0ff',
fontId: 2
})
}
}),
})
```
### onDeleteVerify
类型:`Function`
描述:当用户删除已保存笔迹时回调。
```javascript
const ctx = new WSContext('#ctx' {
onDeleteVerify: (verifyArr: IVerify[]) => {
// verifyArr 被删除的笔迹验签信息数组
}
})
```
## 4.方法
### 1.签名
#### insertSignTemp
描述:插入签名模板
```javascript
ctx.insertSignTemp()
```
#### addSigntmpl
描述:点击插入签名模板
参数:`tmplId: string`签名模板id。
```javascript
ctx.addSigntmpl('xxx')
```
#### showSignboard
描述:显示签字板,以插入签名,此签名不会保存为签名模板
参数:
- `pageIdx: number`:页码,从0开始计数。
- `rx:number`:签名X轴坐标/页宽,0-1。
- `ry:number`:签名Y轴坐标/页高,0-1。
- `rw:number`:签名宽度/页宽,0-1。
- `ry:number`:签名高度/页高,0-1。
```
// 不传参数时会把笔迹插入到签字界面中央。
ctx.showSignboard()
// 传参数时会插入到指定页,指定位置。
ctx.showSignboard(1, 0.1, 0.1, 0.3, 0.2)
```
### 2.文本
#### insertIText
描述:插入文本到文件
```javascript
ctx.insertIText()
```
#### 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`。
(**pageIdx、x、y改为非必传 参数,没有传值时,会将文本插入到签字界面中央**)
```
// 插入文本 hellow world!,颜色 #00a0ff,宋体,显示大小20px,第1页,页面中央。
ctx.addIText('hello world!', '#00a0ff', 1, 20, 0, 0.5, 0.5)
// 插入文本 hellow world!,颜色 #00a0ff,宋体,显示大小20px,签字界面中央。
ctx.addIText('hello world!', '#00a0ff', 1, 20)
```
### 4.图片
#### insertImage
描述:插入图片到文件
```javascript
ctx.insertImage()
```
### 5.圈批
#### enterStroke
描述:进入圈批
```javascript
await ctx.enterStroke()
```
#### quitStroke
描述:退出圈批
```javascript
await ctx.quitStroke()
```
#### isInStroke
描述:界面中的文件是否在圈批状态。**这是一个属性,不是一个方法。**
```javascript
const isInStroke:boolean = ctx.isInStroke
```
#### setStrokeSize
描述:设置圈批笔迹的粗细
参数:`size: number`笔迹的粗细,范围`1-8`
```javascript
await ctx.setStrokeSize(4)
```
#### setStrokeColor
描述:设置圈批笔迹的颜色
参数:`color: string`笔迹的颜色
```javascript
await ctx.setStrokeColor('#00a0ff')
```
#### clearStroke
描述:清除当前页上的圈批笔迹
```javascript
await ctx.clearStroke()
```
#### switchStrokeState
描述:切换圈批状态。如果签字界面不在圈批模式,会主动进入圈批模式。
参数:
- `shapeR` 矩形
- `shapeC` 圆形
- `shapeL` 直线
- `stroke` 笔迹书写
- `eraser` 橡皮擦
```javascript
await ctx.switchStrokeState('stroke')
```
### 6.验签
#### showVerifyModal
描述:显示验签弹窗
```javascript
ctx.showVerifyModal()
```
#### getVerifyArr
描述:获取验签数据
```
interface IVerify{
date: string, // 保存时间
id: string, // 唯一标识
isFromFile: boolean, // 是否是已固化笔迹。true:已固化,不支持删除、false:未固化,可删除
p: string, // 数据位置信息 x,y,width,height
page: number, // 页码,从0开始计数
ps: string, // 所在页的尺寸 width,height
sD: string, // 签署人描述
sI: string, // 签署人唯一标识
sN: string, // 签署人姓名
type: number // 验签数据类型。0:签名、1:图片、2:文本、3:批注
}
const verifyArr: IVerify[] = 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, data: { sequenceId: string, buildNo: number } }
```
#### saveAll
描述:多文件渲染时,保存所有文件的笔迹数据
```javascript
const resultArr = await ctx.saveAll()
// result: { success: boolean, msg: string, data: { sequenceId: string, buildNo: number } }[]
```
### 9.界面显示
#### scrollToPage
参数:`pageNumber: number`页码,从0计数
描述:滚动到指定页
```javascript
await ctx.scrollToPage(10)
```
#### resize
描述:当父容器大小变化时,调整签字界面尺寸
```javascript
ctx.resize()
```
### 10.切换文件
#### switchFile
参数: `sequenceId: string` signInfos中文件的sequenceId
描述:多文件渲染时,切换文件。
```javascript
ctx.switchFile('xxx')
```
### 11.销毁签字界面
#### destroy
```javascript
ctx.destroy()
ctx = undefined
```
### 12.签字板
#### signboard.setSize
描述:设置签字板笔迹尺寸
参数:`size: number`笔迹的粗细,范围`1-9`
```javascript
ctx.signboard.setSize(5)
```
#### signboard.setColor
描述:设置签字板笔迹颜色
参数:`color: string`笔迹的颜色
```javascript
ctx.signboard.setColor('#00a0ff')
```
#### signboard.clear
描述:清除签字板的笔迹
```javascript
ctx.signboard.clear()
```
#### signboard.setEraser
描述:设置签字板是否进入擦除状态
参数:
- `true`:进入擦除状态
- `false`:进入书写状态
```javascript
ctx.signboard.setEraser(true)
```
#### signboard.ok
描述:确认插入签字板上的笔迹
#### signboard.close
描述:关闭签字板
### 13.文本模板
#### insertTexttmpl
描述:插入文本模板到文件
```javascript
ctx.insertTexttmpl()
```
### 14.快签
#### 配置项
- `quickSign.backColor: string`:遮罩背景颜色。默认`rgba(0, 0, 0, 0.03)`
- `quickSign.signZoneBKColor: string`:签字区域背景颜色。默认`rgba(255, 255, 255, 0.8)`
- `quickSign.strokeSize: number`:签字笔迹粗细。默认`5`
- `quickSign.strokeColor: string`:签字笔迹颜色。默认`#000000`
- `quickSign.signZonePlacement: 'center' | 'rightTop' | 'rightBottom' | 'leftTop' | 'leftBottom'`:签字区域初始停靠位置。默认`center`中下方。
- `quickSign.signZoneWidth: number`:签字区域宽度。`>1`时宽度单位为`px`,`<=1`时宽度单位为界面宽度比例。默认`330`
- `quickSign.signZoneHeight: number`:签字区域高度。`>1`时高度单位为`px`,`<=1`时高度单位为界面高度比例。默认`220`
```javascript
new WSContext('#ctx', {
quickSign: {
backColor: 'rgba(0, 0, 0, 0.1)', // 遮罩颜色
signZoneBKColor: '#ffffff', // 签字区域颜色
strokeSize: 6, // 笔迹粗细
strokeColor: '#dd444c', // 笔迹颜色
signZonePlacement: 'rightBottom', // 签字区域停靠位置
signZoneWidth: 500, // 签字区域宽度 500px
signZoneHeight: 0.5 // 签字区域高度 界面高度的 50%
}
})
```
#### quickSign
描述:进入快签模式
```javascript
ctx.quickSign()
```
#### quitQuickSign
描述:退出快签模式
```javascript
ctx.quitQuickSign()
```
## 5.测试中的功能
### 1.印章
#### 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
})
```