---
navTitle: fappComponent
---
# fappComponent - 报表填报应用组件扩展

报表填报应用内置了大量常用的组件，如文本输入、日期、密码输入组件等，能满足大部分的数据填报需求。在一些场景中也存在一些个性化的数据填报需求是内置组件无法满足的，此时就可以通过扩展一个新的表单输入组件来实现。

表单扩展组件可以做到和产品内置的组件一样的复用，由扩展开发者开发好组件扩展后，使用者可以像使用内置组件一样使用扩展组件。

本文讲述如何开发一个报表填报应用组件扩展。

## 扩展文件结构

1. [package.json](#package.json)定义扩展的配置信息
2. [main.ts](#main.ts)定义扩展组件
3. [api](#api)
4. [properties](#properties)

### package.json

示例如下：

<!-- 5.0dev代码中没有package.json文件，导致编译文档报错，先进行注释处理 -->

<!-- <<< @/../../bi/com.succez.bi/web/static-file/extension/extensions/succ-fappComponent-resourceSelector/package.json -->

#### 详细说明

属性 | 类型 | 必需 | 描述 |
| --- |---|---|---|
|id|string|是|组件类型id。|
|caption|string|是|组件标题，通过过国际化fapp.component.caption.xxxx.caption获得显示文字。|
|category|string|否|组件的分类。|
|group|string|否|分组，layout, input, other 通过国际化fapp.component.group.xxxx.caption 获得显示文字。|
|themeCategory|string|否|组件的主题分类。|
|icon|string|否|class或图片的url，icon-开头表示class，其他情况表示图片的url；当不传icon时，系统默认根据id传递图标。|
|depends|string|是|依赖的模块。|
|definitionClassName|string|是|组件定义的类名，来自公共依赖中。|
|implClass|string|是|实现类的名称或类本身。|
|storeEnabled|boolean|是|组件默认是否存储数据。|
|properties|JSON|是|属性栏配置。见][属性栏配置](#属性栏配置)。|

##### id

类型id，所有组件定义的类型id不能重复，比如edit表示文本输入组件，number表示数字输入，他们的category都是input。
如：`"id": "resselector"`,

##### caption

组件标题，通过过国际化fapp.component.caption.xxxx.caption获得显示文字。默认不配置，可以国际化信息中配置。

##### category

组件的分类。
如：`"category": "text"`

##### group

分组，layout, input, other 通过国际化fapp.component.group.xxxx.caption 获得显示文字。
如：`"group": "input"`

##### themeCategory

组件的主题分类。

##### icon

class或图片的url，icon-开头表示class，其他情况表示图片的url；当不传icon时，系统默认根据id传递图标。
如：`"icon": "resselector.svg"`

##### depends

依赖的模块。
如：`"depends": "main"`

##### definitionClassName

组件定义的类名，来自公共依赖中。
如：`"definitionClassName": "FAppResSelectorComponentBuilder"`

##### implClass

实现类的名称或类本身。
如：`"implClass": "FAppResSelectorComponent"`

##### storeEnabled

是否存储数据。
如：`"storeEnabled": true`

##### properties

组件属性栏的配置。
如：

```json
"properties": {
	"formData": {
		"propertyName": "formData",
		"propertyType": "container",
		"items": [
			{
				"propertyName": "type",
				"propertyType": "combobox",
				"layoutTheme": "formcombobox",
				"itemIconVisible": true,
				"captionIconVisible": true,
				"captionTextField": "caption",
				"multipleSelect": false,
				"checkboxVisible": true
			},
			{
				"propertyName": "titleSetting",
				"expandVisible": false,
				"propertyType": "group",
				"items": [
					{
						"propertyName": "title",
						"propertyType": "richTextEdit",
						"saveTheme": true
					},
					{
						"propertyName": "desc",
						"propertyType": "textArea",
						"layoutTheme": "formtextarea"
					},
					{
						"propertyName": "visibleEnabled",
						"propertyType": "checkbox"
					},
					{
						"propertyName": "visibleCondition",
						"propertyType": "expEdit",
						"visibleCondition": "!!visibleEnabled",
						"fieldPanelImpl": {
							"depends": "commons/tree",
							"implClass": "Tree",
							"iconVisible": true,
							"dragable": true,
							"dragMoveable": false
						},
						"showCaption": false
					},
					{
						"propertyName": "editEnabled",
						"propertyType": "checkbox"
					},
					{
						"propertyName": "editCondition",
						"propertyType": "expEdit",
						"fieldPanelImpl": {
							"depends": "commons/tree",
							"implClass": "Tree",
							"iconVisible": true,
							"dragable": true,
							"dragMoveable": false
						},
						"showCaption": false,
						"visibleCondition": "!!editEnabled"
					},
					{
						"propertyName": "placeholder",
						"propertyType": "edit"
					}
				]
			},
			{
				"propertyName": "contentSetting",
				"propertyType": "group",
				"expand": false,
				"inlineItem": {
					"propertyName": "value",
					"propertyType": "expEdit",
					"fieldPanelImpl": {
						"depends": "commons/tree",
						"implClass": "Tree",
						"iconVisible": true,
						"dragable": true,
						"dragMoveable": false
					}
				},
				"items": [
					"defaultValue",
					{
						"propertyName": "calcCondition",
						"propertyType": "expEdit",
						"captionPosition": "top",
						"fieldPanelImpl": {
							"depends": "commons/tree",
							"implClass": "Tree",
							"iconVisible": true,
							"dragable": true,
							"dragMoveable": false
						}
					}
				]
			},
			{
				"propertyName": "checkSetting",
				"propertyType": "group",
				"items": [
					{
						"propertyName": "notNull",
						"propertyType": "checkbox"
					},
					{
						"propertyName": "validEnabled",
						"propertyType": "checkbox"
					},
					{
						"propertyName": "validExp",
						"propertyType": "expEdit",
						"fieldPanelImpl": {
							"depends": "commons/tree",
							"implClass": "Tree",
							"iconVisible": true,
							"dragable": true,
							"dragMoveable": false
						},
						"visibleCondition": "!!validEnabled"
					},
					{
						"propertyName": "validMessage",
						"propertyType": "expEdit",
						"contentType": "macro",
						"fieldPanelImpl": {
							"depends": "commons/tree",
							"implClass": "Tree",
							"iconVisible": true,
							"dragable": true,
							"dragMoveable": false
						},
						"visibleCondition": "!!validEnabled"
					},
					{
						"propertyName": "setValidExp",
						"propertyType": "link",
						"showCaption": "false",
						"enabled": true,
						"visibleCondition": "!!validEnabled"
					}
				]
			},
			{
				"propertyName": "advancedSetting",
				"propertyType": "group",
				"expand": false,
				"items": [
					{
						"propertyName": "storeEnabled",
						"propertyType": "checkbox"
					},
					{
						"propertyName": "dbtable",
						"propertyType": "combobox",
						"itemIconVisible": true,
						"captionIconVisible": false,
						"visibleCondition": "!!storeEnabled"
					},
					{
						"propertyName": "dbfield",
						"propertyType": "combobox",
						"itemIconVisible": true,
						"captionIconVisible": false,
						"arbitraryInputEnabled": true,
						"type": "tree",
						"visibleCondition": "!!storeEnabled"
					},
					{
						"propertyName": "dbfieldConditionEnabled",
						"propertyType": "checkbox",
						"visibleCondition": "!!storeEnabled"
					},
					{
						"propertyName": "dbfieldCondition",
						"propertyType": "edit",
						"visibleCondition": "!!dbfieldConditionEnabled"
					},
					{
						"propertyName": "rememberLastValue",
						"propertyType": "checkbox",
						"visibleCondition": "!!storeEnabled"
					},
					{
						"propertyName": "rootPath",
						"propertyType": "edit"
					},
					{
						"propertyName": "resourceType",
						"propertyType": "combobox",
						"multipleSelect": true,
						"items": [
							"all",
							"tbl",
							"fold"
						]
					}
				]
			}
		]
	},
	"style": {
		"propertyName": "style",
		"propertyType": "container",
		"items": [
			"compStyle",
			{
				"propertyName": "inputTitleSetting",
				"propertyType": "group",
				"expand": true,
				"items": [
					{
						"propertyName": "showTitle",
						"propertyType": "checkbox",
						"defaultValue": true,
						"saveTheme": true
					},
					{
						"propertyName": "titlePosition",
						"propertyType": "combobox",
						"items": [
							"left",
							"top"
						],
						"keyPrefix": "ppteditor.title.position",
						"visibleCondition": "!!showTitle",
						"saveTheme": true
					},
					{
						"propertyName": "titleWidth",
						"propertyType": "spinner",
						"visibleCondition": "!!showTitle",
						"suffix": "%",
						"max": 50,
						"min": 10,
						"defaultValue": 30,
						"saveTheme": true
					}
				]
			},
			{
				"propertyName": "fontSetting",
				"propertyType": "group",
				"expand": false,
				"items": [
					{
						"propertyName": "font",
						"propertyType": "fontEditor",
						"saveTheme": true,
						"expand": false
					}
				]
			},
			{
				"propertyName": "fill",
				"propertyType": "fill",
				"saveTheme": true
			},
			{
				"propertyName": "border",
				"propertyType": "border",
				"saveTheme": true
			},
			{
				"propertyName": "width",
				"propertyType": "slider",
				"saveTheme": true,
				"visibleCondition": "widthVisible == true",
				"max": 360,
				"min": 70
			},
			{
				"propertyName": "layoutSetting",
				"propertyType": "group",
				"expand": false,
				"visibleCondition": "layoutVisible == true",
				"inlineItem": {
					"propertyName": "layout",
					"propertyType": "combobox",
					"saveTheme": true,
					"items": [
						"default",
						"oneQuarter",
						"oneThird",
						"half",
						"twoThirds",
						"threeQuarters"
					],
					"defaultValue": "default",
					"cleanIconVisible": true
				},
				"items": [
					{
						"propertyName": "inputBoxSize",
						"propertyType": "selectPanel",
						"captionPosition": "top",
						"items": [
							"small",
							"middle",
							"large"
						],
						"defaultValue": "middle",
						"saveTheme": true
					}
				]
			},
			{
				"propertyName": "padding",
				"propertyType": "padding",
				"saveTheme": true
			},
			{
				"propertyName": "margin",
				"propertyType": "padding",
				"saveTheme": true
			},
			{
				"propertyName": "conditionSetting",
				"propertyType": "group",
				"items": [
					{
						"propertyName": "conditionStyle",
						"propertyType": "valueDecoratedButton"
					}
				]
			}
		]
	}
}
```

### main.ts

示例如下：

<!-- 5.0dev代码中没有main.ts文件，导致编译文档报错，先进行注释处理 -->

<!-- <<< @/../../bi/com.succez.bi/web/static-file/extension/extensions/succ-fappComponent-resourceSelector/main.ts -->

#### 详细说明

一个组件包括数据对象Builder和UI对象Component。二者缺一不可。

##### 数据对象Builder

###### 数据对象Constructor

```typescript
constructor(args: FAppComponentBuilderArgs)
```

###### FAppComponentBuilderArgs

|属性名 | 类型 | 描述|
|--- | ---| ---|
|form|FAppFormBuilder|组件所属的表单。|

###### 组件编译Compile

```typescript
/**
 * 分析组件中填报需要的属性。并且分析出模型字段信息。有可能一个组件需要对应多个字段。
 */
public compile(context: FAppExpContext): void;
```

##### UI对象Component

###### UI对象Constructor

```typescript
constructor(args: FAppComponentArgs)
```

当组件初始化时会通过构造函数初始化组件。

###### FAppComponentArgs

|属性名 | 类型 | 描述|
|--- | ---| ---|
|type|FAppComponentType|组件类型。扩展组件可自定义类型|
|builder|FAppComponentBuilder|组件的数据对象。|
|compiledInfo|FAppComponentCompiledInfo|组件编译信息，预览和填报界面需要传此参数。|
|viewMode|FAppViewMode|显示模式。包括编辑模式、预览模式和填报模式。|
|deviceType|DeviceType|设备类型。|
|dataManager|FAppFormsDataMgr|填写数据的管理对象。|

##### 加载数据

```typescript
/**
 * 加载组件数据
 */
public loadData(data?: FAppComponentData): Promise<void>;
/**
 * 根据数据刷新状态和样式
 */
public doRefresh(compData: FAppComponentData, property?: string): void;
/**
 * 值变化的事件,一般此时需要同步修改数据层数据。
 */
protected doChange(event: SZEvent, component?: Component, item?: any): void;
/**
 * 增量刷新组件数据或属性
 */
public refreshData(data: FAppComponentData, property?: string): Promise<void>;
/**
 * 增量刷新组件内的浮动行。只有表格、列表、子表单等填报多行数据的组件才需要实现此方法。
 * @param rows 发生修改的浮动行
 */
public refreshRows?(rows: Array<{
	/** 浮动行数据 */
	row: FAppFloatAreaDataRow,
	/** 操作类型：`+`代表是新增的行，`-`代表是删除的行，无此属性代表是修改的行 */
	op: '+' | '-'
}>): Promise<void>
```

所有表单扩展组件都需要实现以上函数。

##### dispose

销毁组件，如清理组件DOM上绑定的事件。

#### 示例参考

示例 | 描述
| --- |---|
[resourceSelector](https://gitlab.succez.com/product/bi/tree/master/com.succez.bi/web/static-file/extension/extensions/succ-fappComponent-resourceSelector) | 资源选择组件。

### api

报表填报应用扩展开发接口中包括，`IFAppComponent`(组件扩展开发接口)。

场景一：如果想开发一个个性化输入组件，那么你需要实现`IFAppComponent`开发个性化组件。并实现该接口中一些方法。

### properties

#### 属性栏配置

表单扩展组件的属性栏配置定义在`fappComponent`下面的`properties`中，用于配置组件的属性名以及属性设置方式。

属性栏配置分为三个部分：

1. `data`,描述组件的数据。需要参与计算的属性应该放到分组下设置。
2. `style`,描述组件的样式。将组件存为一种组件风格时，会将该分组下的属性保存。
3. `action`,描述组件支持的交互行为，不配置时会提供全部的交互行为配置。系统默认提供了一系列的交互行为，这里设置组件支持哪些交互行为。

##### 基本结构

#### 国际化配置

国际化配置定义在`contributes`下面的`i18n`中。
如：

```json
"i18n": {
	"zh_CN": {
		"fapp.component.resselector.caption": "资源选择",
		"fapp.component.resselector.defaultTitle": "资源选择",
		"ppteditor.rootPath": "资源根目录",
		"ppteditor.resourceType": "资源选择类型",
		"ppteditor.resourceType.all":"全部",
		"ppteditor.resourceType.tbl":"模型",
		"ppteditor.resourceType.fold":"文件夹"
	},
	"en": {
		"fapp.component.resselector.caption": "资源选择",
		"fapp.component.resselector.defaultTitle": "资源选择",
		"ppteditor.rootPath": "资源根目录",
		"ppteditor.resourceType": "资源选择类型",
		"ppteditor.resourceType.all":"全部",
		"ppteditor.resourceType.tbl":"模型",
		"ppteditor.resourceType.fold":"文件夹"
	}
}
```