@reskin/zorro-formly

基于 ngx-formly 5.x 和 ng-zorro-antd 的表单驱动组件库，提供声明式的表单配置方式。

功能特性

• 🎯 基于配置的表单构建，无需手动编写模板
• 🎨 完整的 ng-zorro-antd 主题支持
• 📦 内置 10+ 常用表单类型
• 🔌 支持字段方案和界面方案自动构建
• ✅ 完善的验证机制和错误提示
• 🔄 支持字段联动和动态配置
• 📝 TypeScript 类型支持

安装

npm install @ngx-formly/core@5
npm install @reskin/zorro-formly

快速开始

1. 导入模块

import { FormlyModule } from '@ngx-formly/core';
import { FormlyZorroUIModule } from '@reskin/zorro-formly';

@NgModule({
    imports: [
        FormlyModule.forChild(),
        FormlyZorroUIModule,
    ],
})
export class AppModule {}

2. 基础用法

import { Component } from '@angular/core';
import { FormGroup } from '@angular/forms';
import { FormlyFieldConfig } from '@ngx-formly/core';

@Component({
    selector: 'app-form',
    template: `
        <form nz-form nzLayout="vertical" [formGroup]="form" (ngSubmit)="onSubmit()">
            <formly-form [form]="form" [fields]="fields" [model]="model"></formly-form>
            <button nz-button nzType="primary">提交</button>
        </form>
    `,
})
export class FormComponent {
    form = new FormGroup({});
    model: any = {};
    fields: FormlyFieldConfig[] = [
        {
            key: 'name',
            type: 'input',
            templateOptions: {
                label: '姓名',
                placeholder: '请输入姓名',
                required: true,
            },
        },
        {
            key: 'age',
            type: 'number',
            templateOptions: {
                label: '年龄',
                placeholder: '请输入年龄',
                min: 0,
                max: 150,
            },
        },
    ];

    onSubmit() {
        if (this.form.valid) {
            console.log(this.model);
        }
    }
}

支持的表单类型

| 类型 | 说明 | 对应组件 | |------|------|----------| | input | 文本输入框 | nz-input | | number | 数字输入框 | nz-input-number | | textarea | 多行文本框 | textarea[nz-input] | | date-picker | 日期选择器 | rk-date-picker | | select | 下拉选择框 | nz-select | | radio | 单选框组 | nz-radio-group | | upload | 文件上传 | rk-upload | | dictionary-input | 字典输入框 | rk-dictionary-input | | dictionary-select | 字典下拉框 | rk-dictionary-select | | dictionary-unit | 组织单位选择 | rk-dictionary-unit |

高级功能

字段方案指令

通过字段方案标识符自动构建表单：

<formly-form fieldScheme="19e3u4p0w7q" [form]="form" [model]="model"></formly-form>

界面方案指令

通过界面方案和指标集构建表单：

<formly-form scheme="coparsobsa" tableId="DATA_1002_PERSON_A01" [form]="form" [model]="model"></formly-form>

自定义验证

fields: FormlyFieldConfig[] = [
    {
        key: 'email',
        type: 'input',
        templateOptions: {
            label: '邮箱',
            required: true,
        },
        validators: {
            validation: [
                {
                    name: 'email',
                    validator: (control: AbstractControl) => {
                        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(control.value) 
                            ? null 
                            : { email: true };
                    },
                },
            ],
        },
        validation: {
            messages: {
                email: '请输入有效的邮箱地址',
            },
        },
    },
];

字段联动

fields: FormlyFieldConfig[] = [
    {
        key: 'country',
        type: 'select',
        templateOptions: {
            label: '国家',
            options: [
                { label: '中国', value: 'CN' },
                { label: '美国', value: 'US' },
            ],
        },
    },
    {
        key: 'city',
        type: 'select',
        templateOptions: {
            label: '城市',
            options: [],
        },
        hooks: {
            onInit: (field) => {
                const countryField = field.parent?.fieldGroup?.find(f => f.key === 'country');
                countryField?.formControl?.valueChanges.subscribe(country => {
                    // 根据国家更新城市选项
                    field.templateOptions!.options = getCitiesByCountry(country);
                });
            },
        },
    },
];

条件显示

fields: FormlyFieldConfig[] = [
    {
        key: 'hasEmail',
        type: 'radio',
        templateOptions: {
            label: '是否有邮箱',
            options: [
                { label: '是', value: true },
                { label: '否', value: false },
            ],
        },
    },
    {
        key: 'email',
        type: 'input',
        templateOptions: {
            label: '邮箱地址',
        },
        hideExpression: '!model.hasEmail',
    },
];

Wrapper 配置

每个字段支持以下 wrapper 配置：

| 属性 | 类型 | 说明 | |------|------|------| | wrapperStyle | Record<string, any> | 表单项容器样式 | | labelStyle | Record<string, any> | 标签样式 | | controlStyle | Record<string, any> | 控件容器样式 | | labelTooltip | string \| TemplateRef<void> | 标签提示信息 | | description | string \| TemplateRef<void> | 字段描述信息 | | required | boolean | 是否必填（显示红色星号） |

API 服务

RkFormlyService

提供字段方案和界面方案到 Formly 配置的转换服务。

import { RkFormlyService } from '@reskin/zorro-formly';

constructor(private formlyService: RkFormlyService) {}

// 获取字段方案配置
this.formlyService.getFieldsForFieldScheme('permission').subscribe(fields => {
    this.fields = fields;
});

// 获取界面方案配置
this.formlyService.getFieldsForScheme('permission', 'tableCode').subscribe(fields => {
    this.fields = fields;
});

自定义表单类型

import { Component } from '@angular/core';
import { FieldType, FormlyFieldConfig } from '@ngx-formly/core';
import { FormControl } from '@angular/forms';

@Component({
    selector: 'custom-input',
    template: `<input nz-input [formControl]="formControl" [formlyAttributes]="field" />`,
})
export class CustomInputType extends FieldType<FormlyFieldConfig> {
    formControl!: FormControl;
}

// 注册自定义类型
@NgModule({
    imports: [
        FormlyModule.forChild({
            types: [
                {
                    name: 'custom-input',
                    component: CustomInputType,
                    wrappers: ['formly-wrapper'],
                },
            ],
        }),
    ],
})
export class CustomFormlyModule {}

注意事项

1. 确保已安装并导入 @ngx-formly/core 和 ng-zorro-antd
2. 使用字段方案和界面方案时，需要确保后端服务可用
3. 动态脚本执行（triggerScript、checkScript）需谨慎使用，注意安全性
4. 表单验证失败时会自动显示错误提示

更多文档

详细使用文档请参考：web/src/assets/doc/zorro-ui/表单驱动.md

License

MIT