PC端JSAPI
## 1.快速接入
### 1.1引入JS、CSS文件
获取 [CSS最新资源](https://pub.wellsign.cn/sdko/h5/V2.3.0/ws.sdko.p.css) 到本地，并引入CSS文件
```javascript
<link rel="stylesheet" href="本地路径/ws.sdko.p.css" />
```
获取 [JS最新资源](https://pub.wellsign.cn/sdko/h5/V2.3.0/ws.sdko.p.js) 到本地，并引入js文件
```javascript
<script type="text/javascript" src="本地路径/ws.sdko.p.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接口请求地址
### renderViews
类型: `('topbar'|'signtemp'|'stamp'|'verify'|'thumb')[]`
描述：渲染的功能模块。
- `topbar`顶部工具栏
- `signtemp`左部签名模板
- `signtxt`左侧文本模板
- `verify`右部验签
- `thumb`右部缩略图
默认：`['topbar', 'signtemp', 'signtxt', 'verify', 'thumb']`
### isCustomStroke
类型: `boolean`
描述：是否自定义圈批工具栏，值为`true`时将不显示好签默认的圈批工具栏。默认`false`
### modalWrapId
类型：`string`
描述：好签弹出层挂载节点的ID，如果挂载在body下面，弹窗层`position`为`fixed`，否则为`absolute`
### isSeparate
类型：`boolean`
描述：是否启动手笔分离，默认`false`
### signtmplWidth
类型：`number`
描述：插入签名模板时的初始最值，即宽高的最大值，默认`150`。
- `>= 1`时，宽度单位为`px`,例：`100`时，显示宽度为`100px`。
- `< 1`时，宽度单位为**页宽**的比例，例：`0.3`时，宽度为页宽的`30%`。
### timestampWidth
****注意：原有参数`timestampFontsize`已删除，已被此参数替换。****
类型：`number`
描述：插入的时间戳的文本宽度，默认`150`
- `>= 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`
描述：定义签名的时间戳格式
```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`验签签字人读写模式，可以查看所有验签、删除自己的验签信息
### isExportOfdInfo
类型：`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 Context('#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.文本
#### insertIText
描述：插入文本到文件
```javascript
ctx.insertIText()
```
#### closeInsertIText
描述：关闭插入文本模态窗口
```javascript
ctx.closeInsertIText()
```
#### 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)
```
### 2.图片
#### insertImage
描述：插入图片到文件
```javascript
ctx.insertImage()
```
### 3.圈批
#### enterStroke
描述：进入圈批
```javascript
await ctx.enterStroke()
```
#### quitStroke
描述：退出圈批
```javascript
await ctx.quitStroke()
```
#### toggleStroke
描述：进入/退出圈批模式。如果签字界面开启了圈批，则会退出圈批。如果签字界面未开启圈批，则会打开圈批。
```
ctx.toggleStroke()
```
#### 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')
```
#### strokePrev
描述：圈批笔迹回退
```javascript
await ctx.strokePrev()
```
#### strokeNext
描述：圈批笔迹前进
```javascript
await ctx.strokeNext()
```
#### isStrokePrev
描述：是否圈批笔迹可以回退
```javascript
const isStrokePrev: boolean = ctx.isStrokePrev
```
#### isStrokeNext
描述：是否圈批笔迹可以回退
```javascript
const isStrokeNext: boolean = ctx.isStrokeNext
```
### 4.保存
#### 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: { fileId: string } }
```
#### saveAll
描述：多文件渲染时，保存所有文件的笔迹数据
```javascript
const resultArr = await ctx.saveAll()
// resultArr : { success: boolean, msg: string, data: { fileId: string } }[]
```
### 5.界面相关
#### scrollToPage
参数：`pageNumber: number`页码，从0计数
描述：滚动到指定页
```javascript
ctx.scrollToPage(10)
```
#### zoom
参数：`rate: 0.5 | 0.75 | 1 | 2 | 3 | 4 (number)`缩放比例
描述：缩放文件
```javascript
ctx.zoom(2)
```
#### toggleSignTools
描述：左侧签名功能区域显示隐藏
```javascript
ctx.toggleSignTools
```
#### isSignToolsShow
描述：左侧签名功能区域是否显示。（这是一个属性）
```javascript
const isShow = ctx.isSignToolsShow
```
#### toggleNoteTools
描述：右侧签名功能区域显示隐藏
```javascript
ctx.toggleNoteTools（）
```
#### isNoteToolsShow
描述：右侧缩略图验签功能区域是否显示。（这是一个属性）
```javascript
const isShow = ctx.isNoteToolsShow
```
#### getThumb
描述：获取文件缩略图
参数：
- `startIdx`：起始页序号（从0计数，包括此页）
- `endIdx`：结束页序号（从0计数，不包括此页）
```javascript
const arr: string[] = await ctx.getThumb(0, 10)
// 获取从0 - 9 页的缩略图
```
#### getPageTotal
描述：获取文件总页数
```javascript
const pageTotal: number = ctx.getPageTotal()
```
#### rotatePage
描述：顺时针旋转页
参数：旋转页的页码，从0计数。
```javascript
await ctx.rotatePage(0)
```
#### corePageIdx
描述：签字界面当前显示页
```javascript
const pageIdx = ctx.corePageIdx
```
### 6.切换文件
#### switchFile
参数： `fileId: string` fileIds中文件的fileId
描述：多文件渲染时，切换文件。
```javascript
ctx.switchFile('xxx')
```
### 7.销毁签字界面
#### destroy
```javascript
ctx.destroy()
ctx = undefined
```
### 8.签名
#### 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)
```
#### 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
描述：关闭签字板
### 9.验签
#### 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]) // 删除第一个验签
```
### 10.下载 打印
#### fileDownload
描述：文件下载。如果当前界面有未保存的笔迹，会先执行保存再进行下载。
```
await ctx.fileDownload()
```
#### filePrint
描述：文件打印。如果当前界面有未保存的笔迹，会先执行保存再进行打印。
```
await ctx.filePrint()
```
#### pagePrintConfig
描述：配置打印文件的页码。默认第一页。
```javascript
// 打印第一页，页码下标从0计数
new WSContext('#ctx', {
pagePrintConfig: (pageTotal: number) => { // pageTotal 文件总页数
return [0]
}
})
// 打印所有页
new WSContext('#ctx', {
pagePrintConfig: (pageTotal: number) => {
return [] // 返回值为 空数组 时，将打印所有页
}
})
// 打印第一页、最后一页
new WSContext('#ctx', {
pagePrintConfig: (pageTotal: number) => { // pageTotal 文件总页数
return [0, pageTotal - 1]
}
})
```
## 5.测试中的功能
### 1.注释
#### renderViews
描述：新增参数`anno`，将会显示注释详情区域。
```
const ctx = new WSContext({
renderViews: ['topbar', 'signtemp', 'signtxt', 'verify', 'thumb', 'anno']
})
```
#### enterAnno
描述：进入注释模式
```
ctx.enterAnno()
```
#### quitAnno
描述：退出注释模式
```
ctx.quitAnno()
```
#### toggleAnno
描述：进入/退出注释模式。如果签字界面开启了注释，则会退出注释。如果签字界面未开启注释，则会打开注释。
```
ctx.toggleAnno()
```
#### isInAnno
描述：是否在注释模式
```
const isInAnno: boolean = ctx.isInAnno
```
#### switchAnnoState
描述：切换注释状态
参数：
- `anno`:普通注释
- `annoR`:矩形注释
- `annoC`:椭圆注释
```
ctx.switchAnnoState('annoR')
```
### 2.印章
#### 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
})
```