npm package: @sinoform/form-data-api
Description: 提供操作表单数据方法的模块。
Latest version: 1.18.14

# @sinoform/form-data-api

提供操作表单数据方法的模块。

## 查询表单数据

`@sinoform/form-data-api` 提供了 `QueryWrapper`，用于查询表单数据。

例如查询表单设计 id（用于指定获取哪个表单的数据）为 `form-123` 的前 20 条数据：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';

const { content, number } = await new QueryWrapper('form-123')
  .page(0, 20)
  .fetch();

console.log(`总条数：${number}`);
for (const item of content) {
  console.log(`数据 id=${item.id}`);
}
```

### 无流程表单 vs 流程表单

`QueryWrapper` 默认查询**流程表单**数据，可以通过 `noFlowForm()` 方法设置为查询**无流程表单**数据：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';
const result = await new QueryWrapper('form-123').noFlowForm().fetch();
```

### 设置查询条件

可以通过 [@sinoform/helper-condition-api](https://www.npmjs.com/package/@sinoform/helper-condition-api) 模块创建查询条件，并通过 `QueryWrapper` 的 `where` 方法设置查询条件。

简单示例：

```typescript
import { build$ } from '@sinoform/helper-condition-api';
import { QueryWrapper } from '@sinoform/form-data-api';

cosnt $ = build$();
const queryWrapper = new QueryWrapper('form-123').where(
  // 构建 field_1 = '张三' and field_2 >= 18 的查询条件
  $.and($('field_1').equal('张三'), $('field_2').gte(18)),
);
const result = await queryWrapper.fetch();
```

或者：

```typescript
import { sql } from '@sinoform/helper-condition-api';
import { QueryWrapper } from '@sinoform/form-data-api';

const queryWrapper = new QueryWrapper('form-123').where(
  // 构建 field_1 = '张三' and field_2 >= 18 的查询条件
  sql`field_1 = '张三' and field_2 >= 18`,
);
const result = await queryWrapper.fetch();
```

### 设置查询字段

> 限制：无流程表单不支持设置查询字段。

默认返回表单所有字段的值，可以指定查询字段，返回指定查询字段的值。例如：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';

const queryWrapper = new QueryWrapper()
  .select('field_1', 'field_2')
  .from('form-123');

const result = await queryWrapper.fetch();

for (const item of result.content) {
  console.log(`field_1 = ${item.field_1}, field_2 = ${item.field_2}`);
}
```

可以指定字段别名：

```typescript
import { QueryWrapper, column } from '@sinoform/form-data-api';

const queryWrapper = new QueryWrapper()
  .select(column('field_1').as('userName'), column('field_2').as('age'))
  .from('form-123');

const result = await queryWrapper.fetch();

for (const item of result.content) {
  console.log(`userName = ${item.userName}, age = ${item.age}`);
}
```

可以指定字段值去重：

```typescript
import { QueryWrapper, column } from '@sinoform/form-data-api';

const queryWrapper = new QueryWrapper()
  .select(column('field_1').distinct())
  .from('form-123');
```

可以指定统计函数：

```typescript
import { QueryWrapper, column } from '@sinoform/form-data-api';

const queryWrapper = new QueryWrapper()
  .select(
    // 求平均值
    column('field_1').avg().as('avgSalary'),
  )
  .from('form-123');
```

### 设置分组字段

```typescript
import { QueryWrapper, column } from '@sinoform/form-data-api';

// 按照 field_1 和 field_2 两个字段分组查询平均工资（field_3）
const queryWrapper = new QueryWrapper('form-123')
  .select('field_1', 'field_2', column('field_3').avg().as('avgSalary'))
  .groupBy('field_1', 'field_2');
```

### 设置排序规则

升序排序：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';

const queryWrapper = new QueryWrapper('form-123')
  // 按照 field_1 字段升序排序
  .orderBy('field_1');
```

降序排序：

```typescript
import { QueryWrapper, desc } from '@sinoform/form-data-api';

const queryWrapper = new QueryWrapper('form-123')
  // 按照 field_1 字段降序排序
  .orderBy(desc('field_1'));
```

### 带上默认的数据权限条件

默认情况下，`QueryWrapper` 查询与当前用户无关的表单数据。如果仅在自己可见的数据中查询表单数据，则需要使用 `withDefaultAuthConditions()` 方法。如下所示：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';

// 当前用户信息
const currentUser = getCurrentUser(); // 获取到当前用户

const queryWrapper = new QueryWrapper('form-123').withDefaultAuthConditions(
  currentUser,
);
```

### 分页设置

`QueryWrapper` 默认查询前 100 条数据，通过 `page(pageNo, pageSize)` 可以设置分页参数：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';

// 查询第二页，每页20条数据，即查询第 21 到 40 条数据
const queryWrapper = new QueryWrapper('form-123').page(1, 20);
```

注意：`pageNo` 是从 `0` 开始计数的。

### 查询所有数据

`fetch()` 方法查询分页数据，而 `fetchAll()` 方法查询所有数据。

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';

// 当前用户信息
const currentUser = getCurrentUser(); // 获取到当前用户

const dataList = await new QueryWrapper('form-123')
  .withDefaultAuthConditions(currentUser)
  .fetchAll();

for (const item of dataList) {
  console.log(`数据 id = ${item.id}`);
}
```

### 查询第一条数据

`fetchOne()` 方法查询第一条数据：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';
import { build$ } from '@sinoform/helper-condition-api';

const $ = build$();

const formData = await new QueryWrapper('form-123')
  .where($('field_1').equal('张三'))
  .fetchOne();

console.log(`数据 id = ${formData.id}`);
```

### 查询指定 id 对应的表单数据

`selectById(id)` 方法可以查询指定 id 对应大的表单数据：

```typescript
import { QueryWrapper } from '@sinoform/form-data-api';

const formData = await new QueryWrapper('form-123').selectById('data-1');

console.log(`数据 id = ${formData.id}`);
```

## 表单数据增删改

```typescript
import { save, update, remove } from '@sinoform/fomr-data-api';

const formDesign = deitalPage.formData.formDesign;
const formValues = formState.values;

// 保存表单数据
const savedFormValues = await save(formDesign, formValues);

// 更新表单数据
const updatedFormValues = await update(formDesign, formValues);

// 删除表单数据
await remove(formDesign, formValues.id);
```

**注意**：

- 表单数据增删改方法的第一个参数可以指定表单设计配置（`formDesign`），也可以指定表单设计 id（`formDesignId`）。
- 方法内部已经分区了无流程表单和流程表单，放心使用。

## 更新表单部分字段值

```typescript
import { patch } from '@sinoform/form-data-api';

const formDesign = deitalPage.formData.formDesign;
const formValues = formState.values;

// 更新 field_1 和 field_2 两个字段的值
await patch(formDesign, formValues.id, {
  field_1: '新的值',
  field_2: '另一个新的值',
});
```

`patch` 方法的第一个参数也可以指定表单设计 id。

## 流程表单数据增删改（弃用）

```typescript
import { flowForm } from '@sinoform/fomr-data-api';

const formDesign = deitalPage.formData.formDesign;
const formValues = formState.values;

// 保存流程表单数据
const savedFormValues = await flowForm.save(formDesign, formValues);

// 更新流程表单数据
const updatedFormValues = await flowForm.update(formDesign, formValues);

// 删除流程表单数据
await flowForm.remove(formDesign.id, formValues.id);
```

## 无流程表单数据增删改（弃用）

```typescript
import { noFlowForm } from '@sinoform/fomr-data-api';

const formDesign = deitalPage.formData.formDesign;
const formValues = formState.values;

// 保存无流程表单数据
const savedFormValues = await noFlowForm.save(formDesign, formValues);

// 更新无流程表单数据
const updatedFormValues = await noFlowForm.update(formDesign, formValues);

// 删除无流程表单数据
await noFlowForm.remove(formDesign.id, formValues.id);
```