Widget

集成控件相关数据和方法

控件生成方式

拖拽生成控件

场景： 制作模板时设置控件、合同发起前设置控件、签署时拖拽加盖签章等场景，拖拽页面元素到合同页面上生成控件。
方法： 使用 Widget.setWidgetTransfer 方法来设置拖拽的控件数据。FaContract 会在合同页面的 drop 事件中解析数据，并关联文档页面和坐标信息，进而生成 widget，并 push 到 FaContract 参数的 widgets 数组中。

示例 1：制作模板或发起时设置控件

<div @drag="dragInput">单行文本</div>

import { Widget, WidgetType, WidgetMode, ActorData } from 'fdd-contract'

/** 控件指定的参与方 */
const actor: ActorData = {
  id: '2342342',
  name: '深圳市xxx公司',
  index: 0
}

/** 制作模板或发起前：拖拽单行文本控件 */
function dragInput(e: DragEvent) {
  Widget.setWidgetTransfer(e, {
    type: WidgetType.INPUT,
    // 指定参与方
    actor
  })
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

示例 2：拖拽并加盖印章

<div @drag="dragSeal">
  <img :src="seal.img" />
</div>

1
2
3

import { Widget, WidgetType, WidgetMode, ActorData, SignData } from 'fdd-contract'

/** 当前签署方 */
const actor: ActorData = {
  id: '2342342',
  name: '深圳市xxx公司',
  index: 0
}

/** 印章数据 */
const seal: SignData = {
  /** 签章 id */
  id: '345345345',
  /** 签章名称 */
  name: '财务章',
  /** 图片地址 */
  img: 'https://fadada.com/pic/seal/345345345.png'
}

/** 不指定位置签署：拖拽并加盖印章 */
function dragSeal(e: DragEvent) {
  Widget.setWidgetTransfer(e, {
    type: WidgetType.SEAL,
    // 拖拽加盖印章需要使用模式
    mode: WidgetMode.USE,
    // 指定参与方
    actor,
    // 签章数据
    sign: seal
  })
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

JSON 原始控件

场景： 目前后端是 JSON 方式存储控件数据的，我们需要将 JSON 原始数据快速还原生成控件。
方法： 使用 Widget.createRawWidget 方法来转换后端控件数据。
示例：

import { Widget, WidgetMode, ActorData } from 'fdd-contract'

/** 控件绑定的参与方 */
const actor: ActorData = {
  id: '2342342',
  name: '深圳市xxx公司',
  index: 0
}

/** 后端取到的控件数据 */
const rawField =
  '{"h": 60, "p": 0, "w": 200, "x": 466.7999877929687, "y": 220, "id": "ff0msq6lcco", "name": "参与方2", "type": 4, "align": "center", "label": "多行文本控件", "fontSize": 18, "fontType": 3, "signStyle": 3, "isRequired": true, "widgetName": "多行文本控件", "widgetValue": ""}'

const widget = Widget.createRawWidget(JSON.parse(rawField), {
  // 填写阶段为使用模式
  // 如果是制作模板或发起前设置控件，应当设置为 WidgetMode.SET
  mode: WidgetMode.USE,
  actor,
  docId: '345345345'
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import { Widget, WidgetMode, ActorData } from 'fdd-contract'

/** 控件绑定的参与方 */
const actor: ActorData = {
  id: '2342342',
  name: '深圳市xxx公司',
  index: 0
}

// 签署控件
const sealWidget = new Widget({
  name: '骑缝控件1',
  type: WidgetType.SEAL,
  mode: WidgetMode.USE,
  // 骑缝控件
  kind: WidgetKind.RIDING,
  actor,
  docId: '345345345',
  x: 200,
  y: 150
})

// 填写控件
const textareaWidget = new Widget({
  name: '多行文本控件1',
  type: WidgetType.TEXTAREA,
  mode: WidgetMode.USE,
  actor,
  docId: '345345345',
  p: 1,
  w: 170,
  h: 60,
  x: 200,
  y: 150,
  // 非必填
  required: false,
  // 默认值
  value: '这是很长的一段文本'
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

属性

基本信息

属性	说明	类型	默认值
id	控件 id，如果未设置则自动生成	string	—
name	控件名称	string	—
displayName readonly	控件展示名称，如未设置控件名称则显示控件选项的名称	string	—
className	控件元素类名，用于自定义控件类名	string	—
type	控件类型	WidgetType	`WidgetType.UNKNOWN`
isFill readonly	是否填写控件	boolean	—
isSign readonly	是否签署控件	boolean	—
option readonly	控件配置选项	WidgetOption	—
component readonly	控件组件	vueComponent	—
mode	控件模式，用于区分控件的状态	WidgetMode	`WidgetMode.USE`
isSet readonly	是否设置模式，如指定控件位置和设置控件信息	boolean	—
isUse readonly	是否使用模式，如填写和签署	boolean	—
isView readonly	是否查看模式，如控件预览	boolean	—
isDone readonly	是否完成模式，如预览已填写定稿的控件	boolean	—
kind	控件种类，用于区分控件是否骑缝、批量等	WidgetKind
actor	参与方，引用值，应该直接赋值而非修改子属性	ActorData	`{ id: '', name: '', index: -1 }`
actorColor readonly	参与方颜色	string	—
label readonly	控件 label 展示	string	—
labelUsing readonly	控件使用中 label 文案，用于快捷填写	string	—
labelTips readonly	控件 label 次级提示	string	—
tips	控件提示信息	string	—
extra	额外数据，用于扩展额外的字段	object	`{}`

尺寸和定位

属性	说明	类型	默认值
docId	控件所在文档 id	string
doc readonly	控件所在文档	DocData \| undefined	`undefined`
p	控件所在页码，从 0 开始	number	`0`
page readonly	控件所在页面骑缝控件关联第一页数据	PageData	—
applyPage	应用的页面，用于批量和骑缝控件	undefined: 全部页 'ODD': 奇数页 'EVEN': 偶数页 '1, 2, 5-8': 指定页（仅批量控件，从 1 开始）	`undefined`
pages readonly	所在页面列表谨慎使用，避免超多页面文档性能问题	number[]	—
linkId	控件关联 id	string	—
w	宽度	number	`0`
h	高度	number	`0`
x	水平位置	number	`0`
y	纵向位置	number	`0`
ox	控件中心定位 x，后端通常使用中心定位	number	—
oy	控件中心定位 y	number	—
aspectRatio readonly	宽高比例，0 则不约束	number	`0`
range readonly	定位范围	object	—

操作控制

属性	说明	类型	默认值
fixed	是否指定位置用于指定位置签署的控件	boolean	`false`
deletable	是否可以删除控件是可拖动的，此字段才生效	boolean	`true`
isFixed readonly	是否固定控件不允许删除、移动、调整尺寸	boolean	—
resizable readonly	是否允许调整大小	boolean	—
removable readonly	是否允许删除	boolean	—

错误信息

属性	说明	类型	默认值
error readonly	校验错误信息	boolean	—
errorSetting readonly	设置错误	boolean	—
errorUsing readonly	使用错误	boolean	—
customError	自定义错误消息	string	—

签署控件

属性	说明	类型	默认值
isRiding readonly	是否骑缝控件	boolean	`false`
sign	签章数据，设置模式用来展示签章	SignData \| DateSign	`{ id: '', img: '' }`
followSignSize	签章控件是否跟随签章图片规格尺寸	boolean	`true`
keepSignAspect	签章控件自定义规格时是否保持比例 `followSignSize` 为 `false` 时生效	boolean	`false`
assignedSignId	指定印章 ID	string	—
assignedSignName	指定印章名称	string	—
signTag	签章控件标签	string \| TagProps	undefined

填写控件

属性	说明	类型	默认值
value	填写控件值	string	`''`
hasFillValue readonly	检测控件是否有填写值	boolean	—
required	填写控件是否必填	boolean	true
source	控件数据来源	WidgetSource \| string	—
sources readonly	可用来源列表	WidgetSourceItem[]	[]
sourceItem readonly	匹配到的控件数据来源项	WidgetSourceItem \| undefined	—
text	文本控件文本信息，例如字体、字号、居中等	TextData	`FddContract.config.textDefault`
fontSizeValue readonly	文本控件字号大小值	string	—
fontFamilyValue readonly	文本控件字体样式值	string	—
numberFixedLimit	数字控件是否限制数字小数点位数	boolean	false
numberFixed	数字控件保留小数点位数，0 ~ 10	number	2
thousands	数字控件是否显示千分位	boolean	false
dateFormat	日期填写控件日期格式	DateFormat	`DateFormat.LOCAL`
checkOptions	单选框、复选框选项	CheckOption[]	[]
activeOption readonly	单、复选框当前选项	CheckOption \| undefined	undefined
selectOptions	下拉选择选项	string[]	[]
attachment	附件数据	AttachmentData	`{ fileName: '', loading: false, progress: 0 }`
image	图片数据	ImageData	—
tableOptions	表格控件选项	TableOptions	TableDefault
tableFields	表格控件字段	TableField[]	—
tableData	表格数据	TableItem[]	—
tableColWidths	表格列宽	number[]	—

方法

方法名	说明	参数	返回类型
constructor	Widget 构造	data: WidgetData	—
init	初始化数据	raw: WidgetData	—
clear	清除控件数据	—	—
getRawField	生成原始控件数据（提供给后端）	—	RawField
getBatchField	生成批量控件的原始数据将单个批量控件按页码生成多份（提供给后端）	—	RawField[]
isInPage	控件是否在指定页	p: number, docId = this.docId	boolean
move	控件按距离移动	x: number = 0, y: number = 0, adjust = true	—
moveTo	控件移动到指定位置	x: number = this.x, y: number = this.y, adjust = true	—
adjust	适应位置以免超出边界	—	—
fixDropLocation	修复跨页移动后的坐标和页码	—	—
clone	克隆控件生成的新控件会丢弃 extra 数据	—	Widget

静态方法

方法名	说明	参数	返回类型
defineWidget	定义控件选项用以更改控件选项，或者自定义新的控件	type: WidgetType \| number, option: Partial<WidgetOption> \| WidgetOption	—
getWidgetOption	获取控件配置选项	type: WidgetType	WidgetOption
getWidgetOptions	获取控件配置选项列表	—	WidgetOption[]
createRawWidget	根据后端记录的 JSON 原始控件数据创建控件	data: RawField, extra?: Partial<WidgetData>	Widget
setWidgetTransfer	设置拖拽的控件数据（拖拽开始 @drag）	e: DragEvent, data: WidgetData
getWidgetTransfer	获取拖拽的控件数据（拖入）	e: DragEvent, area: Element, zoom: number	WidgetData
getActorColor	获取参与方颜色	index: number	string

# Widget

# 控件生成方式

# 拖拽生成控件

# JSON 原始控件

# 生成 Widget 实例

# 属性

# 基本信息

# 尺寸和定位

# 操作控制

# 错误信息

# 签署控件

# 填写控件

# 方法

# 静态方法