---
order: 11
navTitle: 组件属性和方法
---
# 组件属性和方法

`SuccApp`允许用户通过设置组件属性和调用组件方法交互改变属性状态或触发组件行为。

## 设置组件属性{#set-component-property}

设置组件属性可以改变组件的数据状态，当组件数据状态变化后，页面会触发组件渲染，将组件刷新到最新状态。
![设置组件属性原理图](../../images/viz-set-componnet-property.png)

在组件的[package.json](./package-json.md#accessable-properties)中配置`accessableProperties`后，用户可以在`设置组件属性`交互中选择组件，并在属性对话框中设置属性。

```json
{
 	"accessableProperties":[
        {
            name:"param"
        }
    ]
}
```

```typescript
export class MyVisualComponent implements IVisualComponent {

    public render(args: VisualComponentRenderArgs): void {
        let componentData = args.componentData;
        let paramValue = componentData.getProperty('param');
        //do with paramValue
    }
}
```

## 调用组件方法{#invoke-component-method}

在组件的[package.json](./package-json.md#accessable-methods)中配置`accessableMethods`后，用户可以在`调用组件方法`交互中选择组件和方法，并在参数对话框中设置方法参数。

组件方法可以返回`void`或`Promise`。当返回`Promise`时，`调用组件方法`交互会等待`Promise`结束才会继续执行后续交互。

*VisualComponentInvokeMethodArgs*

| 名称                     | 类型                               | 描述                                                   |
| ------------------------ | ---------------------------------- | ------------------------------------------------------ |
| `visualObject`           | [`IVisualObject`](TODO:)           | 页面对象。                                             |
| `visualComponent`        | [`IVisualComponent`](TODO:)        | 组件对象。对于全局函数的实现，组件隐藏时该参数为null。 |
| `visualComponentBuilder` | [`IVisualComponentBuilder`](TODO:) | 组件构造器对象。                                       |
| `params`                 | `JSON`                             | 方法参数。用户在`调用组件方法`交互中配置的参数。       |

实现组件方法可有两种方式：

1. `IVisualComponent`的成员方法。改变组件UI状态的方法在此处实现，如弹出对话框、聚焦到某个地点等。这类方法需要组件处于显示状态。
2. 全局函数。和组件UI无关的方法在此处实现，如导出组件数据。这类方法不需要组件处于显示状态，直接基于组件的数据执行。

调用组件方法会先从`IVisualComponent`的成员方法中查找，如果没有找到，则从[main](./package-json.md#main)指定的`JS`模块中`export`出来的全局函数中查找。

### **成员方法**{#component-method}

在`IVisualComponent`上增加成员方法，可以访问到组件的`DOM`元素。

```json
{
    "name":"myvisualcomponent",
	"accessableMethods":[
       {
           "name":"addBlankRow",
           "params":[
               {
                   "name":"target",
                   "defaultValue":"current",
                   "items":[{"value":"current"},{"value":"children"}]
               },
  			   {
                   "name":"caption"
               }
           ]
       },
	   ...
    ],
    ...
}
```

```typescript
export class MyVisualComponent implements IVisualComponent {

    private tree: Tree;

    public render(args: VisualComponentRenderArgs): void {
        
    }

    public addBlankRow(args: VisualComponentInvokeMethodArgs): void {
       	let visualObject: IVisualObject = args.visualObject;
        let visualComponent: IVisualComponent = args.visualComponent
		...
        //根据visualObject、visualComponent的状态判断是否能在树上新加一行
        if(canAddBlankRow) {
            ...
        	this.tree.addBlankRow(args.params);
            ...
        }
        ...
    }
}
```

### **全局函数**{#global-function}

在[main](./package-json.md#main)指定的JS文件模块中实现函数并`export`，这种实现方式通常被用于和`UI`无关的组件方法。

*嵌入报表*

```json
{
    "name":"emebedReport",
    "accessableMethods":[
        {
            "function":"exportTableData",
            "params":[
       			{"name":"embedReportPath"}
            ]
        }
    ]
}
```

```typescript
/**
 * 嵌入报表导出数据方法实现。
 */
export function exportTableData(args:VisualComponentInvokeMethodArgs) {
    let visualObject = args.visualObject;
	//ui无关的组件方法，参数中visualComponent参数为null。
    let visualComponentBuilder = args.visualComponent;
    ...
    //嵌入报表路径，如："/DEMO/ana/报表/分组报表/单向分组.rpt"
    let path =args.params.embedReportPath;
    if(checkPathExist(path)){
        ...
        exportReport(args.params);
        ...
    }
    ...
}
```

## 通用属性{#common-properties}

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `visible` | `boolean` | 组件可见性。 |

## 通用方法{#common-methods}

## **树**{#tree}

### **属性**{#tree-properties}

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | string|string\[]|number|number\[] | 树的高亮或勾选值。可以用于提交、过滤。设置此属性会同步设置树的勾选或高亮，如果`value`为空`（null、[]）`代表清空勾选或高亮。设置此属性后，可以通过表达式属性[树.值](#)访问。 |

### **方法**{#tree-methods}

#### **addBlankNode**(){#tree-method-addBlankNode}

为树上增加一个空白节点。

**描述**

树上同时只能存在一个空白节点。当树上已经存在空白节点时，重复调用此函数不会继续添加。

选中的是多个节点，以最后一个选中的节点为准。

空白节点添加成功后会选中空白节点。

如果空白节点未被保存时切换选中，会删除空白节点。

如果添加后空白节点不可见，会将其滚动到可见区域。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| appendChild | boolean | 可选，默认为`false`。是否插入到选中节点的子节点。 |
| insertBefore | boolean | 可选，默认我`false`。是否插入到选中节点的前面。 |
| targetNode | number|string | 可选。插入到指定节点的同级或下级。 |
| value | number|string | 可选。节点值。 |
| caption | string | 可选，默认为`未命名`。节点标题，国际化key为`bo.tree.blankrow.caption`。 |
| data | Json | 可选。插入的字段数据。如`{field1: value, field2: value}`。 |

**返回值**

无。

#### **remove**BlankNode(){#tree-method-removeBlankNode}

删除树上空白节点。

**描述**

如果空白节点未被保存时切换选中，会删除空白节点。

删除后会自动选中树的其他节点的规则规则如下：

- 如果选中节点有同级节点，会选中最近的同级节点，优先选择选中节点的下一个节点。
- 如果选中节点没有同级节点，则选中父节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| autoSelect | boolean | 可选。默认为true。删除时是否自动选中其他节点。 |

**返回值**

无。

#### **find()**{#tree-method-find}

对树进行搜索。

**描述**

##### **方法参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `keyword` | `string` | 搜索关键字，为空是退出搜索。 |
| `mode` | `listSearch`|`treeSearch`|`treeLocate` |搜索模式，默认值为`listSearch`。搜索模式为`listSearch`（**列表搜索**）时，以列表的形式展示匹配的结果。搜索模式为`treeSearch`（**树搜索**）时，显示所有包含匹配结果的父节点，会层层展开第一个匹配结果的节点并选中。搜索模式为`treeLocate`（**树定位**）时，显示所有节点（不隐藏不匹配的节点），会层层展开第一个匹配的节点并选中。此时可以通过`locateNextFoundItem`定位所有搜索到的节点。 |

#### **locateFoundItem()**{#tree-method-locateNextFoundItem}

树处于搜索状态时，定位搜索结果。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| forward | boolean | 是否后定位。默认为`true`。 |
| cycle | boolean | 是否循环定位，默认为`true`。 |

#### **locate()**{#tree-method-locate}

定位指定节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 定位节点的值。 |

#### **select()**{#tree-method-select}

选中指定节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |

#### **unselect()**{#tree-method-unselect}

取消选中指定节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |

#### **selectAll()**{#tree-method-selectAll}

选中所有节点。

#### **unselectAll()**{#tree-method-unselectAll}

取消选中所有节点。

#### **check()**{#tree-method-check}

勾选指定节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |

#### **uncheck()**{#tree-method-uncheck}

取消勾选指定节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |

#### **checkAll()**{#tree-method-checkAll}

勾选所有节点。

#### **uncheckAll()**{#tree-method-uncheckAll}

取消勾选所有节点。

#### **expand**(){#tree-method-expand}

展开指定节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |

#### **expandAll**(){#tree-method-expandAll}

展开树所有节点。

**描述**

- 如果树有多级，会按层级依次展开树的节点。

#### **collapse**(){#tree-method-collapse}

折叠指定节点。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| value | number|string | 节点的值。 |

#### **collapseAll**(){#tree-method-collapseAll}

折叠树所有节点。

**描述**

- 如果树有多级，会按层级依次折叠树的节点。

## **富文本**{#richtext-input}

## **嵌入报表**{#embedreport}

### **方法**{#embedreport-methods}

#### **export**(){#embedreport-method-export}

导出报表。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| fileType | excel|pdf | 文件类型。 |
| allPage | boolean | 是否导出所有页，默认为`false`。|
| exportSheetType | current|all|select | `current`表示导出当前工作表；`all`表示导出所有工作表；`select`表示导出选择的工作表，默认为`current`。 |
| exportSheets | string | 当`exportSheetType`为`select`时，指定导出的sheet ID，多个时用逗号分割。|

#### **print**(){#embedreport-method-print}

打印报表。

**参数**

无

#### **refresh**(){#embedreport-method-refresh}

刷新报表。

报表的参数栏和表体都重置为初始状态，清空数据缓存，计算时重新查询数据。

**参数**

无

## **嵌入仪表板**{#embeddashboard}

### **方法**{#embeddashboard-methods}

#### **export**(){#embeddashboard-method-export}

导出仪表板。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| fileType | image||ppt|pdf | 文件类型。 |

#### **print**(){#embeddashboard-method-print}

打印仪表板。

**参数**

无

#### **refresh**(){#embeddashboard-method-refresh}

刷新仪表板。

仪表板重置为初始状态，清空数据缓存，计算时重新查询数据。

**参数**

无

## **嵌入SuperPage**{#embedsuperpage}

### **方法**{#embedsuperpage-methods}

#### **export**(){#embedsuperpage-method-export}

导出SuperPage。

**参数**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| fileType | image||ppt|pdf | 文件类型。 |

#### **print**(){#embedsuperpage-method-print}

打印SuperPage。

**参数**

无

#### **refresh**(){#embedsuperpage-method-refresh}

刷新SuperPage。

SuperPage重置为初始状态，清空数据缓存，计算时重新查询数据。

**参数**

无

## **嵌入报表填报应用**{#embedfapp}

### **方法**{#embedfapp-methods}

#### **addRow**(){#embedfapp-method-addRow}

浮动区域增加一个浮动行。

**描述**

选中浮动区域的单元格时，在焦点单元格下方增加一个浮动行。

如果没有选中单元格，并且只有一个浮动区域，会在浮动区域最下面增加一行

**参数**

无。

#### **deleteRow**(){#embedfapp-method-deleteRow}

删除选中的浮动行。

**描述**

选中浮动区域的单元格时，会删除这些单元格所在的浮动行。

**参数**

无。

#### **validateForm**(){#embedfapp-method-validateForm}

校验当前填写的数据。

**描述**

对当前填写的数据做校验，如果校验不通过，会显示校验面板，查看和定位校验不通过组件。

校验不通过，数据会无法保存或提交。

**参数**

无。

#### **saveDraft**(){#embedfapp-method-saveDraft}

保存数据。

**描述**

数据会保存到服务器，并且会设置为草稿状态。

保存时会对必须填写的数据做校验，如果校验不通过，会无法保存。如模型主键不能为空，保存时必须有数据。

**参数**

无。

#### **submitData**(){#embedfapp-method-submitData}

提交数据。

**描述**

数据会保存到服务器，并且会设置为已提交。

提交时会对对数据做校验，如果校验不通过，会提交失败，并显示校验面板，可以按校验面板提示解决校验错误。

**参数**

无。

#### **importData**(){#embedfapp-method-importData}

导入数据。

**描述**

可以将excel文件中的数据导入到表单中，导入后，点击保存或提交，才会保存到服务器。

**参数**

无。

#### **exportData**(){#embedfapp-method-exportData}

导出Excel。

**描述**

将Excel表单和嵌入报表导出为Excel文件。

Web表单和嵌入的SuperPage不会导出。

**参数**

无。

#### **lockData**(){#embedfapp-method-lockData}

锁定数据。

**描述**

将已提交的数据锁定，锁定后，数据将不能再修改。

如果需要再次修改数据，需要先解锁。

**参数**

无。

#### **unlockData**(){#embedfapp-method-unlockData}

解锁数据。

**描述**

已锁定的数据是不能修改的，只有解锁后，才能再次修改。

**参数**

无。

#### **deleteData**(){#embedfapp-method-deleteFAppData}

删除数据。

**描述**

删除当前期，当前单位的已保存或提交数据。

**参数**

无。

## **嵌入表单**{#embedform}

### **方法**{#embedform-mthods}

#### **addRow**(){#embedform-method-addRow}

浮动区域增加一个浮动行。

**描述**

选中浮动区域的单元格时，在焦点单元格下方增加一个浮动行。

如果没有选中单元格，并且只有一个浮动区域，会在浮动区域最下面增加一行

**参数**

无。

#### **deleteRow**(){#embedform-method-deleteRow}

删除选中的浮动行。

**描述**

选中浮动区域的单元格时，会删除这些单元格所在的浮动行。

**参数**

无。

#### **importData**(){#embedform-method-importData}

导入数据。

**描述**

可以将excel文件中的数据导入到表单中，导入后，点击保存或提交，才会保存到服务器。

**参数**

无。

#### **exportData**(){#embedform-method-exportData}

导出Excel。

**描述**

将Excel表单和嵌入报表导出为Excel文件。

Web表单和嵌入的SuperPage不会导出。

**参数**

无。