数组高级用法

本文介绍 Piying-View 中数组的高级特性：增删改操作、deletionMode、groupMode 等。

预览

定义

array-basic.definition.ts

import * as v from 'valibot';

export const schema = v.object({
  tags: v.array(v.string()),
});

export const model = { tags: ['angular', 'vue', 'react'] };

数组基本操作

Piying-View 的 FieldArray 提供以下操作方法：

set — 设置指定索引的值

直接调用 field.action.set(value, index)：

field.action.set('newValue', 0); // 将索引 0 的值设为 'newValue'

支持跳过前面的元素直接插入：

field.action.set('value', 5); // 在索引 5 处设置值

remove — 删除指定索引的元素

直接调用 field.action.remove(index)：

field.action.remove(0); // 删除索引 0 的元素

updateValue — 整体替换数组

直接调用 field.form.control.updateValue(value)：

field.form.control.updateValue(['a', 'b', 'c']); // 完全替换数组内容

clear — 清空数组

直接调用 field.form.control.clear()：

field.form.control.clear(); // 清空所有元素

reset — 重置到初始值

预览

定义

array-reset.definition.ts

import * as v from 'valibot';

export const schema = v.pipe(
  v.optional(v.array(v.string()), ['default1', 'default2']),
);

export const model = ['default1', 'default2'];

deletionMode — 删除模式

控制数组元素被删除后的处理方式。

shrink（默认）— 收缩模式

删除元素后，数组长度自动缩短：

预览

定义

array-shrink.definition.ts

import * as v from 'valibot';
import { formConfig } from '@piying/view-angular-core';

export const schema = v.pipe(
  v.array(v.string()),
  formConfig({ deletionMode: 'shrink' }),
);

export const model = ['a', 'b', 'c'];

mark — 标记模式

删除元素后，该位置的值设为 undefined，数组长度保持不变：

预览

定义

array-mark.definition.ts

import * as v from 'valibot';
import { formConfig } from '@piying/view-angular-core';

export const schema = v.pipe(
  v.tuple([v.number(), v.string()]),
  formConfig({ deletionMode: 'mark' }),
);

export const model = [1, 'v2'];

groupMode — 组验证模式

控制数组与元组的验证行为。groupMode 在解析 schema 时自动推导，无需手动赋值。

Schema 类型	自动解析的 groupMode	说明
v.tuple()	'default'	固定长度元组：超出长度部分自动截断
v.looseTuple()	'loose'	宽松元组：超出长度部分保留
v.strictTuple()	'strict'	严格元组：超出长度时验证失败
v.array() / v.tupleWithRest() 的 rest 部分	'reset'	数组/可变尾部：不做固定键/长度约束

对象组的 groupMode（v.object() / v.looseObject() / v.strictObject()）见 类型映射。

emptyValue — 空值

当数组为空时，返回 emptyValue 作为最终值：

预览

定义

array-empty-value.definition.ts

import * as v from 'valibot';
import { formConfig } from '@piying/view-angular-core';

export const schema = v.object({
  tags: v.pipe(v.array(v.string()), formConfig({ emptyValue: [] })),
});

export const model = { tags: [] };

Array 属性

FieldArray 的 length / controls / fixedControls$ / clear() 等属性，以及 Field 层面的 children / fixedChildren / restChildren，属于控件 API，统一见 AbstractControl — FieldArray 特有 API。

Tuple 与 TupleWithRest

Tuple — 固定长度元组

预览

定义

array-tuple.definition.ts

import * as v from 'valibot';

export const schema = v.tuple([v.string(), v.number()]);

export const model = ['v1', 2];

TupleWithRest — 元组 + 可变尾部

预览

定义

array-tuple-with-rest.definition.ts

import * as v from 'valibot';
import { setComponent } from '@piying/view-angular-core';

export const schema = v.pipe(
  v.tupleWithRest([v.string()], v.number()),
  setComponent('array'),
);

export const model = ['v1', 0, 1];

完整示例

预览

定义

array-complete.definition.ts

import * as v from 'valibot';
import { formConfig, setComponent } from '@piying/view-angular-core';

export const schema = v.object({
  tags: v.pipe(v.array(v.string()), formConfig({ deletionMode: 'mark' })),
  scores: v.pipe(v.optional(v.array(v.number()), [0, 0])),
  position: v.tuple([v.number(), v.number()]),
  coordinates: v.pipe(
    v.tupleWithRest([v.string()], v.number()),
    setComponent('array'),
  ),
  groups: v.pipe(v.array(v.looseObject({ name: v.string() }))),
});

export const model = {
  tags: ['a', 'b'],
  scores: [0, 0],
  position: [1, 2],
  coordinates: ['v1', 3],
  groups: [{ name: '张三' }],
};

下一步

• Record Schema 动态对象组 — 动态键值对表单
• formConfig — deletionMode / groupMode / emptyValue 配置详解