npm package: @reskin/zorro-formly
Description: 基于 `ngx-formly 5.x` 和 `ng-zorro-antd` 的表单驱动组件库，提供声明式的表单配置方式。
Latest version: 0.0.6

# @reskin/zorro-formly

基于 `ngx-formly 5.x` 和 `ng-zorro-antd` 的表单驱动组件库，提供声明式的表单配置方式。

## 功能特性

- 🎯 基于配置的表单构建，无需手动编写模板
- 🎨 完整的 ng-zorro-antd 主题支持
- 📦 内置 10+ 常用表单类型
- 🔌 支持字段方案和界面方案自动构建
- ✅ 完善的验证机制和错误提示
- 🔄 支持字段联动和动态配置
- 📝 TypeScript 类型支持

## 安装

```bash
npm install @ngx-formly/core@5
npm install @reskin/zorro-formly
```

## 快速开始

### 1. 导入模块

```typescript
import { FormlyModule } from '@ngx-formly/core';
import { FormlyZorroUIModule } from '@reskin/zorro-formly';

@NgModule({
    imports: [
        FormlyModule.forChild(),
        FormlyZorroUIModule,
    ],
})
export class AppModule {}
```

### 2. 基础用法

```typescript
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` |

## 高级功能

### 字段方案指令

通过字段方案标识符自动构建表单：

```html
<formly-form fieldScheme="19e3u4p0w7q" [form]="form" [model]="model"></formly-form>
```

### 界面方案指令

通过界面方案和指标集构建表单：

```html
<formly-form scheme="coparsobsa" tableId="DATA_1002_PERSON_A01" [form]="form" [model]="model"></formly-form>
```

### 自定义验证

```typescript
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: '请输入有效的邮箱地址',
            },
        },
    },
];
```

### 字段联动

```typescript
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);
                });
            },
        },
    },
];
```

### 条件显示

```typescript
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 配置的转换服务。

```typescript
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;
});
```

## 自定义表单类型

```typescript
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