zin

Appearance

字段 ​

介绍 ​

字段为 zin 中用于定义数据属性，它可以定义数据库中的表属性，也可以定义任何其他需要定义的数据结构，通过命名字段列表可以非常方便地集中的管理一组字段，也可以通过名称引用来自不同位置的字段创建新的字段列表。 通过定义好的字段列表可以方便的创建表单、数据定义详情、列表等界面。

字段 ​

创建字段 field() ​

在 zin 中通过 field() 方法来创建字段，该方法定义如下：

php
/** 创建一个空的字段。 */
field(): field

/** 创建一个特定名称的字段。 */
field(string $name): field

/** 创建字段并用关联数组或对象来初始化属性。 */
field(array|object $props): field

该方法返回 field 类实例，该示例上提供了大量实用方法用于对字段进行属性设置或其他操作。

注意

字段名称不能包含 / 和 ,，因为 / 用于分隔字段列表名称和字段名称，而 , 用于分隔字段名称。

示例：

php
/* 创建空的字段，通常需要调用实例上的其他方法来设置属性。 */
$emptyField = field();

/* 创建名称为 title 的字段。 */
$field = field('title');

/* 创建名称为 title 的字段，并设置属性 required。 */
$field = field(array('name' => 'title', 'required' => true));

/* 定义 $props 对象用于设置属性。 */
$props = new stdClass();
$props->name     = 'title';
$props->required = true;
/* 创建字段并通过对象来设置属性。 */
$field = field($props);

字段属性 ​

字段属性用于定义字段的各种属性，例如字段名称、控件类型、标签、默认值等，在 field 实例上提供了如下方法来设置常用属性：

属性说明实例方法
name名称name(string $name): field
idIDid(string $id): field
className组类名id(string ...$classList): field
control表单控件id(string｜array｜object｜false｜null $control): field
label标签label(string $label): field
labelFor标签 for 属性labelFor(string $for): field
labelClass标签 class 属性labelClass(string ...$classList): field
labelProps标签元素自定义属性labelProps(array $props): field
labelWidth标签宽度labelWidth(string $width): field
labelHint标签上的提示文本labelHint(string $hint): field
labelHintClass标签提示 class 属性labelHintClass(string ...$classList): field
labelHintProps标签提示自定义属性labelHintProps(array $props): field
labelActions标签上的操作按钮labelActions(string $Actions): field
labelActionsClass标签操作按钮 class 属性labelActionsClass(string ...$classList): field
labelActionsProps标签操作按钮自定义属性labelActionsProps(array $props): field
type类型type(string $type): field
value值value(string $value): field
required是否必填required(bool $required = true): field
readonly是否只读readonly(bool $readonly = true): field
disabled是否禁用disabled(bool $disabled = true): field
placeholder占位符placeholder(string $placeholder): field
items表单选项或输入组内容列表items(array｜false｜null $items): field
text文本信息text(string $text): field
tip提示信息tip(string $tip): field
tipClass提示 class 属性tipClass(string ...$classList): field
tipProps提示元素自定义属性tipProps(array $props): field
multiple提示元素自定义属性multiple(bool $multiple = true): field
foldable是否允许在表单中折叠foldable(bool $foldable = true): field
pinned是否允许在表单中固定pinned(bool $pinned = true): field
checkbox是否显示额外的选择框或指定属性checkbox(array $checkbox): field
wrapBefore是否确保开始独占一行wrapBefore(bool $wrapBefore = true): field
wrapAfter是否确保结尾独占一行wrapAfter(bool $wrapAfter = true): field

除了以上列举的字段，字段也可以根据实际需要自定义其他属性。

字段属性设置 ​

字段属性可以通过多种方法进行设置，下面分别进行介绍：

通过 set() 方法设置 ​

该方法定义如下：

php
/** 设置字段特定属性的值。 */
set(string $prop, mixed $value): field

/** 通过对象或数组一次性设置多个属性的值。 */
set(array|object $props): field

示例：

php
/* 创建 title 字段。 */
$field = field('title');

/* 设置 required 属性。 */
$field->set('required', true);

/* 通过数组同时设置 required 和 placeholder 属性。 */
$field->set(array('required' => true, 'placeholder' => '请输入标题'));

通过实例方法设置 ​

针对常用属性，field 类上提供了一些实用方法来设置属性，例如：

php
field('title')           // 创建 title 字段。
    ->label('标题')       // 设置标文本。
    ->width('full')      // 设置表单控件宽度。
    ->required()         // 设置 required 为 true。
    ->foldable(false)    // 设置 foldable 为 false。
    ->set('custom', 123) // 设置自定义属性 custom 为 123。
    ->custom(321);       // 通过魔术方法 custom 直接重新设置 custom 属性为 321.

提示：链式调用

大部分实例方法都返回自身，这样可以非常方便的通过链式设置多个属性。

设置字段表单控件 ​

通过字段上的 control 属性来设置表单控件，该属性可以通过 field 实例上的如下方法进行设置：

php
/** 设置表单控件类型。 */
control(string $controlName): field

/** 设置表单控件类型和属性。 */
control(string $controlName, array|object $controlProps): field

/** 设置表单控件属性。 */
control(array|object $controlProps): field

/** 开始设置指定类型的控件属性。 */
controlBegin(string $controlName): field

/** 结束设置控件属性。 */
controlEnd(): field

/** 直接设置控件渲染内容。 */
control(wg $wg): field

/** 设置为一个回调函数来生成控件渲染内容。 */
control(callable $renderCallback): field

字段控件渲染为普通输入框示例：

php
field('title')->control('input');

/* 等同于： */
field('title')->control(array('control' => 'input'));

/* 省略 control 设置。 */
field('title');

提示

当控件类型为普通文本输入框时，可以省略控件设置。

字段控件渲染为下拉选择器示例：

php
field('type')->control('picker', array('multiple' => true, 'items' => $items));

提示

当控件类型为下拉选择器（picker），且已经设置了 items 属性的情况下可以省略控件设置。

通过 controlBegin 和 controlEnd 链式设置控件属性：

php
field('title')
    ->controlBegin('picker')
    ->multiple()
    ->items($items)
    ->controlEnd();

直接设置渲染的内容：

php
field('title')->control(div('hello world')); // 渲染为 div。

通过回调函数来设置渲染的内容，该回调函数第一个参数为当前字段上的所有属性：

php
$buildTitleField = function(array $props): wg
{
    return div
    (
        'hello world',
        data('lang.zentaoPMS'),
        json_encode($props)
    );
};

field('title')->control($buildTitleField);

操作列表属性 ​

当某个属性的值被定义为列表时，可以通过如下方法来操作属性的值：

php
/** 将一个值添加到指定名称的属性值列表中。 */
addToList(string $prop, mixed $item): field

/** 将一个值添加到指定名称的属性值列表中，同时指定要添加到列表时使用的键值。 */
addToList(string $prop, mixed $item, ?string $key): field

/** 通过数组合并值到列表中。 */
mergeToList(string $prop, array $items): field

/** 获取指定名称的属性的值作为列表返回。 */
getList(string $prop): array;

示例：

php
/* 创建 title 字段。 */
$field = field('title');

/* 获取 options 属性作为数组返回。 */
$options = $field->getList('options'); // array()

/* 添加项目到 options 属性数组中。 */
$field->addToList('options', 'a');

/* 继续添加项目到 options 属性数组中。 */
$field->addToList('options', array(123), 'list');

/* 通过数组合并值到列表中。 */
$field->mergeToList('options', array('b', 'test' => 'ok'));

/* 获取 options 属性作为数组返回。 */
$options = $field->getList('options'); // array('a', 'list' => array(123), 'b', 'test' => 'ok')

操作对象属性 ​

当某个属性的值被定义为对象时，可以通过如下方法来操作属性的值：

php
/** 通过数组或对象设置对象属性。 */
addToMap(string $prop, object|array $map): field

/** 获取指定名称的属性的值作为对象返回。 */
getMap(string $prop): array

/** 通过键名获取对象属性的值。 */
removeFromMap(string $prop, string ...$keys): field

示例：

php
/* 创建 title 字段。 */
$field = field('title');

/* 获取 style 属性作为对象返回。 */
$style = $field->getMap('style'); // array()

/* 添加属性到 style 属性对象中。 */
$field->addToMap('style', array('color' => 'red', 'width' => '100px', 'height' => '32px'));

/* 继续设置属性到 style 属性对象中。 */
$field->addToMap('style', array('height' => 'auto'));

/* 获取 style 属性作为对象返回。 */
$map = $field->getMap('style'); // array('color' => 'red', 'width' => 100px, 'height' => 'auto')

设置 CSS 类属性 ​

字段上提供了如下方法来设置 CSS 类属性：

php
setClass(string $prop, string|array|object ...$classList): field

示例：

php
/* 创建 title 字段。 */
$field = field('title');

/* 设置 className 属性值作为 CSS 类。 */
$field->setClass('className', 'btn primary', 'size-lg');

/* 继续设置 CSS 类到 className 属性中。 */
$field->setClass('className', array('disabled' => true, 'text-primary' => false));

/* 获取 className 属性作为 CSS 类返回。 */
$className = $field->get('className'); // 'btn primary size-lg disabled'

设置条目列表 ​

字段上提供了如下方法来设置条目列表，条目列表通常用于设置表单字段选项列表或者控件 inputGroup 的内部控件列表：

php
/** 设置 items 属性值作为条目列表。 */
items(?array $items): field

/** 移除列表的所有值。 */
items(false): field

/** 将一个值添加到 items 属性值列表中。 */
item(object $item): field

/** 将一个值添加到 items 属性值列表中，并指定值在列表上对应的键值。 */
item(object $item, string $key): field

/** 开始设置一个新的条目属性。 */
itemBegin(?string $itemName): field

/** 结束设置条目的属性值。 */
itemEnd(): field

示例：

php
/* 创建 title 字段。 */
$field = field('title');

/* 设置 items 属性值作为条目列表。 */
$field->items(array(
    array('value' => 'a', 'text' => '选项 A'),
    array('value' => 'b', 'text' => '选项 B'),
    array('value' => 'c', 'text' => '选项 C'),
));

/* 继续添加条目到 items 属性值列表中。 */
$field->item(array('value' => 'd', 'text' => '选项 D'));

/* 开始设置一个新的条目属性。 */
$field->itemBegin()->value('e')->text('选项 E')->itemEnd();

/* 获取 items 属性作为条目列表返回。 */
$items = $field->get('items');
// array(
//     array('value' => 'a', 'text' => '选项 A'),
//     array('value' => 'b', 'text' => '选项 B'),
//     array('value' => 'c', 'text' => '选项 C'),
//     array('value' => 'd', 'text' => '选项 D'),
//     array('value' => 'e', 'text' => '选项 E'),
// )

字段实用方法 ​

在 field 上还提供了一些实用方法，下面进行介绍。

获取字段名称 ​

通过 getName() 获取字段 name 属性，例如：

php
$field = field('title');

$name = $field->getName(); // 'title'

清空字段所有属性 ​

通过 clear() 方法可以清空字段所有属性，例如：

php
$field = field('title');
$field->clear();           // 清空所有属性
$name = $field->getName(); // null

判断是否有特定属性值 ​

通过 has(string $prop): bool 方法可以判断字段是否有特定属性值且值不为 null，例如：

php
$field = field('title');

$field->has('name'); // true
$field->has('id');   // false

移除指定属性的值 ​

通过 remove(string $prop): field 方法可以移除指定属性的值，例如：

php
$field = field('title');

$field->remove('name'); // 移除 name 属性

获取字段属性个数 ​

通过 getCount(): int 方法可以获取字段属性个数，例如：

php
$field = field('title');

$field->getCount(); // 1

将字段转换为数组 ​

通过 toArray(): array 方法可以将字段转换为数组，例如：

php
$field = field('title');

$field->toArray(); // array('name' => 'title')

复制字段 ​

通过 copy(): field 方法可以复制字段，例如：

php
$field = field('title');

$field->copy(); // field('title')

在所属字段列表中操作 ​

当字段已被添加到字段列表时，可以通过 field 实例上的方法来操作所属字段列表。

从所属字段列表中移除 ​

通过 detach(): field 方法可以从所属字段列表中移除，例如：

php
$field = field('title');

$field->detach(); // field('title')

移到所属字段列表的指定字段后面 ​

通过 moveAfter(string $name): field 方法可以移动到所属字段列表的指定字段后面，例如：

php
$field = field('title');

$field->moveAfter('product'); // field('title')

移到所属字段列表的指定字段前面 ​

通过 moveBefore(string $name): field 方法可以移动到所属字段列表的指定字段前面，例如：

php
$field = field('title');

$field->moveBefore('color'); // field('title')

字段列表 ​

字段列表用于管理特定数据上一组关联的字段，要定义字段，需要先定义字段列表。

定义字段列表 defineFieldList() ​

定义字段列表通过方法 defineFieldList()，该方法定义如下：

php
/** 定义一个特定名称的字段列表。 */
defineFieldList(string $name): fieldList

/** 定义一个特定名称的字段列表，并通过后续参数定义依赖的字段或字段列表。 */
defineFieldList(string $name, string|array|field|fieldList ...$args): fieldList

该方法参数定义如下：

  • $name：字段列表名称，例如 'bug'；
  • ...$args：指定该列表依赖的其他字段列表或直接给定包括的字段对象，该参数还可以追加需要从依赖的字段中移除的字段名称。

该方法返回 fieldList 类实例，fieldList 上面提供了大量方法可以对列表进行操作。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 定义名称为 `bug-create` 的字段列表，并从名称为 bug 的字段列表继承字段。 */
$createFields = defineFieldList('bug-create', 'bug');

通过在依赖列表中使用 !removeFieldName1,removeFieldName2 的形式来从依赖的字段中移除字段，例如：

php
/** 定义名称为 `bug-create` 的字段列表，并从字段列表中移除名称为 branch 和 color 的字段。 */
$createFields = defineFieldList('bug-create', 'bug', '!branch,color');

提示

字段列表名称必须是唯一的，当重复定义一个已经存在的字段列表时，只会返回之前定义的字段列表。

注意

字段列表名称不能包含 / 和 ,，因为 / 用于分隔字段列表名称和字段名称，而 , 用于分隔字段名称。

定义或修改字段 ​

要为字段列表定义或修改字段，有多种方法，下面分别进行介绍。

方式一：通过字段列表实例方法 fieldList->field() 定义字段 ​

通过字段列表实例方法 fieldList->field() 定义字段，该方法定义如下：

php
/** 定义一个特定名称的字段。 */
field(string $name): field

/** 定义一个特定名称的字段，同时指定初始属性。 */
field(string $name, array|object $fieldProps): field

提示

  • 该方法返回 field 类实例，可以继续通过链式调用定义字段其他属性。
  • 当字段列表中已经存在同名字段时，会返回之前定义的字段，这样方便为之前定义的字段设置新的属性或修改之前的属性。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义名称为 `title` 的字段。 */
$fields->field('title');

/** 在字段列表上定义名称为 `product` 的字段，并同时通过链式调用指定其他属性。 */
$fields->field('product')->label('产品')->required();

/** 继续为字段列表修改名称为 `product` 的字段。 */
$fields->field('product')->required(false)->control('picker');

方式二：通过 defineField() 方法定义字段 ​

在字段列表上定义或修改字段通过 defineField() 方法，该方法定义如下：

php
/** 定义一个特定名称的字段。 */
defineField(string $name): field

/** 定义一个特定名称的字段，并同时指定所属的字段列表。 */
defineField(string $name, string $listName): field

提示

  • 该方法返回 field 类实例，可以继续通过链式调用定义字段其他属性。
  • 当字段列表中已经存在同名字段时，会返回之前定义的字段，这样方便为之前定义的字段设置新的属性或修改之前的属性。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
defineFieldList('bug'); // 提前调用 defineFieldList，后续调用 defineField 会默认定义为当前字段列表。

/** 在字段列表 `bug` 上定义名称为 `title` 的字段。 */
defineField('title');

/** 在字段列表 `bug` 上定义名称为 `product` 的字段，并同时通过链式调用指定其他属性。 */
defineField('product')->label('产品')->required();

/** 在字段列表 `branch` 上定义名称为 `branch` 的字段，并同时指定所属的字段列表。 */
defineField('branch', 'branch')->label('分支');

/** 继续为字段列表 bug 修改名称为 `product` 的字段。 */
defineField('product')->required(false)->control('picker');

方式三：通过手动添加 ​

通过创建字段方法 field() 创建一个字段，然后通过字段列表实例上的 add() 方法来添加到字段列表中，该方法定义如下：

php
/** 将一个字段添加到字段列表中。 */
add(field $field): field

/** 直接通过属性数组创建字段并添加到字段列表中。 */
add(array $fieldProps): field

/** 直接通过属性对象创建字段并添加到字段列表中。 */
add(object $fieldObject): field

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 创建名称为 `title` 的字段。 */
$field = field('title')->label('标题');

/** 将字段添加到字段列表中。 */
$fields->add($field);

/** 直接通过属性数组创建字段并添加到字段列表中。 */
$fields->add(array('name' => 'product', 'label' => '产品'));

/** 直接通过属性对象创建字段并添加到字段列表中。 */
$branchInfo = new stdClass();
$branchInfo->name  = 'branch';
$branchInfo->label = '分支';
$fields->add($branchInfo);

设置字段属性 ​

通过 set() 方法可以设置字段属性，该方法定义如下：

php
/** 设置字段特定属性的值。 */
set(string|array $names, string $prop, mixed $value): field

/** 通过对象或数组一次性设置多个属性的值。 */
set(string|array $names, array|object $props): field

提示

  • 可以通过 , 分隔多个字段名称，也可以通过数组来指定多个字段名称。
  • 该方法返回 fieldList 类实例，可以继续通过链式调用定义字段其他属性。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品');

/** 设置字段属性。 */
$fields->set('title', 'required', true);
// 相当于：$fields->field('title')->required(true);

/** 设置多个字段属性。 */
$fields->set('title,product', array('required' => true, 'foldable' => true));

获取字段 ​

通过 get() 方法可以获取字段列表中的字段，该方法定义如下：

php
/** 获取字段列表中的给定名称的字段。 */
get(string $name): ?field

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义名称为 `title` 的字段。 */
$fields->field('title');

/** 获取名称为 `title` 的字段。 */
$field = $fields->get('title');

/** 获取名称为 `product` 的字段。 */
$field = $fields->get('product'); // null

移除字段 ​

通过 remove() 从字段列表中移除字段，该方法定义如下：

php
/** 从字段列表中移除一个或多个字段。 */
remove(string ...$names): fieldList

提示

可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();

/** 移除字段。 */
$fields->remove('title', 'product'); // 或 $fields->remove('title,product');

获取所有定义的字段名称 ​

通过 names() 方法可以获取字段列表中所有定义的字段名称，该方法定义如下：

php
/** 获取字段列表中所有定义的字段名称。 */
names(): array

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();

/** 获取字段列表中所有定义的字段名称。 */
$fields->names(); // array('title', 'product')

获取字段清单 ​

通过 toList() 方法获取列表中的字段并以数组的形式返回，该方法定义如下：

php
/** 获取字段列表中的所有字段。 */
toList(): array

/** 获取字段列表中指定名称的字段。 */
toList(string|array $names): array

提示

可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();
$fields->field('branch');

/** 获取字段列表中的所有字段。 */
$fields->toList(); // array('title' => field('title'), 'product' => field('product'), 'branch' => field('branch'))

/** 获取字段列表中的给定名称的字段。 */
$fields->toList('title,product'); // array('title' => field('title'), 'product' => field('product'))

获取字段数组 ​

通过 toArray() 方法获取列表中的字段并以数组的形式返回，相比较 toList() 该方法会将每个字段也转换为数组，而不是直接返回 field，该方法定义如下：

php
/** 获取字段列表中的所有字段。 */
toArray(): array

/** 获取字段列表中指定名称的字段数组。 */
toArray(string|array $names): array

提示

可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();
$fields->field('branch');

/** 获取字段列表中的所有字段。 */
$fields->toArray();
// array('title' => array('name' => 'title'), 'product' => array('name' => 'product', 'label' => '产品', 'required' => true), 'branch' => array('name' => 'branch'))

/** 获取字段列表中的给定名称的字段数组。 */
$fields->toArray('title,product');
// array('title' => array('name' => 'title'), 'product' => array('name' => 'product', 'label' => '产品', 'required' => true))

移动字段 ​

移动到指定字段的前方位置 ​

通过 moveBefore() 方法可以将字段移动到指定字段的前方位置，该方法定义如下：

php
/** 将字段移动到指定字段的前方位置。 */
moveBefore(string $names, string $beforeName): fieldList

提示

  • 可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。
  • beforeName 可以为 '$BEGIN' 和 '$END' 分别表示移动到字段列表的开始或结尾位置。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();
$fields->field('branch');

/** 将字段移动到指定字段的前方位置。 */
$fields->moveBefore('branch', 'product');

/** 获取字段列表中的所有字段。 */
$fields->toList(); // array('title' => field('title'), 'branch' => field('branch'), 'product' => field('product'))

移动到指定字段的后方位置 ​

通过 moveAfter() 方法可以将字段移动到指定字段的后方位置，该方法定义如下：

php
/** 将字段移动到指定字段的后方位置。 */
moveAfter(string $names, string $afterName): fieldList

提示

  • 可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。
  • beforeName 可以为 '$BEGIN' 和 '$END' 分别表示移动到字段列表的开始或结尾位置。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();
$fields->field('branch');

/** 将字段移动到最开始位置。 */
$fields->moveAfter('branch', '$BEGIN');

/** 将字段移动到指定字段的后方位置。 */
$fields->moveAfter('title', 'branch');

/** 获取字段列表中的所有字段。 */
$fields->toList(); // array('branch' => field('branch'), 'title' => field('title'), 'product' => field('product'))

移动到字段列表开头或末尾 ​

通过 moveToBegin() 和 moveToEnd() 方法可以将字段移动到字段列表的开头或末尾，方法定义如下：

php
/** 将字段移动到字段列表的开头。 */
moveToBegin(string $names): fieldList

/** 将字段移动到字段列表的末尾。 */
moveToEnd(string $names): fieldList

提示

可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();
$fields->field('branch');

/** 将字段移动到字段列表的开头。 */
$fields->moveToBegin('branch');

/** 将字段移动到字段列表的末尾。 */
$fields->moveToEnd('title');

/** 获取字段列表中的所有字段。 */
$fields->toList(); // array('branch' => field('branch'), 'product' => field('product'), 'title' => field('title'))

对字段进行排序 ​

通过 sort() 方法可以对字段列表中的字段进行排序，该方法可以在不改变相对顺序的情况下，安装给定的字段名称顺序进行微调。该方法定义如下：

php
/** 对字段列表中的字段进行排序。 */
sort(string|array ...$sortNames): fieldList

提示

  • 可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。
  • 其中排序字段可以以 '$BEGIN' 和 '$END' 分别表示移动到字段列表的开始或结尾位置。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();
$fields->field('branch');
$fields->field('bug');
$fields->field('color');

/** 对字段列表中的字段进行排序，确保 title 在 branch 后面。 */
$fields->sort('branch,title');

/** 对字段列表中的字段进行排序，将 title 移到 branch 后面，将 product 和 title 移到 color 后面。 */
$fields->sort('branch,title', '$BEGIN,color,product,title');

/**
 * 获取字段列表中的所有字段。
 * 原顺序：title, product, branch, bug, color
 * 排序后：color, product, title, branch, bug
 */
$fields->toList();

定义字段导出顺序 ​

默认情况下表单中的字段会安装字段列表中显示的顺序进行显示，但有时需要调整表单中字段的显示顺序，这时可以通过 fieldList 实例方法 orders() 来定义字段导出顺序，如果需要为完整模式定义字段导出顺序，则可以通过 fullModeOrders() 方法来定义。相关方法定义如下：

php
/** 定义字段导出顺序。 */
orders(string|array ...$names): fieldList

/** 定义完整模式字段导出顺序。 */
fullModeOrders(string|array ...$names): fieldList

提示

  • 可以通过 , 分隔多个字段名称，也可以通过多个参数来指定多个字段名称。
  • 其中排序字段可以以 '$BEGIN' 和 '$END' 分别表示移动到字段列表的开始或结尾位置。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
$fields = defineFieldList('bug');

/** 在字段列表上定义字段。 */
$fields->field('title');
$fields->field('product')->label('产品')->required();
$fields->field('branch');
$fields->field('bug');
$fields->field('color');

/** 定义字段导出顺序。 */
$fields->orders('branch,title', '$BEGIN,color,bug');

/** 定义完整模式字段导出顺序。 */
$fields->fullModeOrders('branch,title');

使用字段 ​

通过方法 useFields() 可以通过引用名称的方式来使用字段列表中的字段，该方法会创建一个临时的字段列表 fieldList 实例供使用，该方法定义如下：

php
useFields(string|array|field|fieldList|null ...$args): fieldList

该方法参数可以指定为一个或多个，允许为如下值：

  • 字段列表名称，例如 'bug'，这样会引用指定名称的字段列表中定义的所有字段；
  • 字段列表实例，例如 fieldList('bug')，这样会引用指定的字段列表实例中定义的所有字段；
  • 字段实例，例如 field('title')，这样会引用指定的字段实例；
  • null，会被忽略；
  • !field1,field2：要排除的字段名称列表，例如 '!title,product'，这样会引用指定名称的字段列表中定义的所有字段，但会排除名称为 title 和 product 的字段。
  • 以上类型组成的数组。

示例：

php
/** 定义名称为 `bug` 的字段列表。 */
defineFieldList('bug');

/** 在字段列表 bug 上定义字段。 */
field('title');
field('product')->label('产品')->required();
field('branch');
field('color');

/** 定义名称为 `bug.kanban` 的字段列表 */
defineFieldList('bug.kanban');

/** 在字段列表 bug.kanban 上定义字段。 */
field('lane');
field('region');

/** 使用字段。 */
$fields = useFields('bug', 'bug.kanban', '!color,region');

/** 获取字段列表中的所有字段。 */
$names = $fields->names(); // array('title', 'product', 'branch', 'lane')

在表单中使用 ​

在表单中使用字段列表可以通过 useFields() 方法获取要在表单使用的字段，然后通过表单相关部件的 fields 属性来设置字段，示例：

php
/** 使用字段（省略定义字段的代码）。 */
$fields = useFields('bug', $isKanban ? 'bug.kanban' : null, '!color,region');

/** 获取字段列表中的所有字段。 */
$names = $fields->names(); // array('title', 'product', 'branch', 'lane')

/** 修改 title 字段。 */
$fields->field('title')->label('标题')->required();

/** 根据条件移除 branch 字段。 */
if($noBranch)
{
    $fields->remove('branch');
}

/** 增加新的字段。 */
$fields->field('newField')->label('新字段');

/** 批量定义字段标签数据。 */
$labelData = array(
    'title'    => '标题',
    'product'  => '产品',
    'branch'   => '分支',
    'lane'     => '泳道',
    'newField' => '新字段',
);
$fields->setLabelData($labelData);

/** 批量定义字段默认值数据。 */
$valueData = array(
    'title'    => '测试',
    'product'  => '1',
    'branch'   => '2',
    'lane'     => '3',
    'newField' => '4',
);
$fields->setValueData($valueData);

/** 定义网格表单面板。 */
formGirdPanel
(
    /* 通过 fields 定义表单项。 */
    set::fields($fields) // 设置字段列表
);

提示

表单的用法参考 表单。

https://zentao.net

Copyright (C) 2023 cnezsoft.com