@sinoform/form-data-api

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

查询表单数据

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

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

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() 方法设置为查询无流程表单数据：

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

设置查询条件

可以通过 @sinoform/helper-condition-api 模块创建查询条件，并通过 QueryWrapper 的 where 方法设置查询条件。

简单示例：

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();

或者：

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();

设置查询字段

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

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

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}`);
}

可以指定字段别名：

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}`);
}

可以指定字段值去重：

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

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

可以指定统计函数：

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

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

设置分组字段

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');

设置排序规则

升序排序：

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

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

降序排序：

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

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

带上默认的数据权限条件

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

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

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

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

分页设置

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

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

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

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

查询所有数据

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

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() 方法查询第一条数据：

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 对应大的表单数据：

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

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

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

表单数据增删改

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）。
• 方法内部已经分区了无流程表单和流程表单，放心使用。

更新表单部分字段值

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。

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

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);

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

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);