@bigbear713/nb-form

Angular common form lib by bigBear713.

OnlineDemo

Bug Report

Feature Request

Document

• 中文
• English

Changelog

• 中文
• English

Feature

• 提供常用的表单控件校验器：arrLength, equal, fileSize, fileType, required, whitespace。具体见下方校验器的定义；
• 支持通过DI设置common error info；
• 支持组件的更新策略为ChangeDetectionStrategy.OnPush；
• 支持在standalone component中使用；
• 支持以standalone component的方式引入；

Version

nb-form的大版本和Angular的大版本保持对应关系

| @bigbear713/nb-form | @angular/core | | --- | --- | | ^12.0.0 | ^12.0.0 | | ^13.0.0 | ^13.0.0 | | ^14.0.0 | ^14.0.0 | | ^15.0.0 | ^15.0.0 | | ^16.0.0 | ^16.0.0 | | ^17.0.0 | ^17.0.0 |

Installation

$ npm i @bigbear713/nb-form
// or
$ yarn add @bigbear713/nb-form

API

Module

NbFormModule

表单模块。引入该模块后，可使用component。service和validators不需要引入该模块也可使用。

NbFormTestingModule

表单测试模块。用于Unit Test。

Validators

NbFormValidators.arrLength

v12.0.0

数组长度校验器

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | arrLength | { max?: number; min?: number } | true | 数组长度限制。可单独设置最大或者最小长度。 | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.ARR_MAX_LENGTH]?: true;[NbControlErrType.ARR_MIN_LENGTH]?: true; }｜null | 返回null表示符合条件，或者要校验的内容不是一个数组。返回{ [NbControlErrType.ARR_MAX_LENGTH]: true }表示数组长度超出最大长度限制。返回{ [NbControlErrType.ARR_MIN_LENGTH]: true }表示数组长度小于最小长度限制。 |

Usage

const maxControl = new FormArray([1,2,3,4,5,6],[NbFormValidators.arrLength({max:5,min:3})]);
console.log(maxControl.errors); // { [NbControlErrType.ARR_MAX_LENGTH]: true }

const minControl = new FormArray([1,2],[NbFormValidators.arrLength({max:5,min:3})]);
console.log(minControl.errors); // { [NbControlErrType.ARR_MIN_LENGTH]: true }

NbFormValidators.equal

v12.0.0

值是否相等校验器。当两个控件的值不相等时，当前控件会带有相关的错误信息。如果想两个控件都带有错误信息，可参考demo

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | compared | AbstractControl | true | 要对比的表单控件. | v12.0.0 | | immediately | boolean | false | 是否立即校验。如果设置为false，则会在compared控件为dirty状态时才会校验。默认为true | v12.1.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.NOT_EQUAL]: true; }｜null | 校验结果。返回null表示两个表单控件的值相等。返回{ [NbControlErrType.NOT_EQUAL]: true }表示两个表单控件值不相等。 |

Usage

const targetControl = new FormControl('');
const compareControl = new FormControl(null);
targetControl.setValidators([NbFormValidators.equal(compareControl)]);
console.log(targetControl.errors); // { [NbControlErrType.NOT_EQUAL]: true; }


const targetControl = new FormControl('');
const compareControl = new FormControl(null);
targetControl.setValidators([NbFormValidators.equal(compareControl,false)]);
console.log(targetControl.errors); // null

compareControl.markAsDirty();
targetControl.updateValueAndValidity();
console.log(targetControl.errors); // { [NbControlErrType.NOT_EQUAL]: true; }

NbFormValidators.fileSize

v12.0.0

文件大小校验器

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | fileSize | { max?: number; min?: number } | true | 文件大小限制。可单独设置最大值或者最小值。最大最小值的单位是B. | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.FILE_MAX_SIZE]?: true;[NbControlErrType.FILE_MIN_SIZE]?: true; }｜null | 校验结果。返回null表示符合条件，或者要校验的内容不是一个File类型。返回{ [NbControlErrType.FILE_MAX_SIZE]: true }表示文件大小超出最大值限制。返回{ [NbControlErrType.FILE_MIN_SIZE]: true }表示文件大小小于最小值限制。 |

Usage

const control = new FormControl(new File(),[NbFormValidators.fileSize({max:5,min:3})]);
console.log(control.errors); // { [NbControlErrType.FILE_MAX_SIZE]: true; } / { [NbControlErrType.FILE_MIN_SIZE]?: true; }

NbFormValidators.fileType

v12.0.0

文件类型校验器

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | types | string[] | true | 要支持的文件类型，值应该为MIME Type. | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.FILE_TYPE]: true; }｜null | 校验结果。返回null表示符合条件，或者要校验的内容不是一个File类型。返回{ [NbControlErrType.FILE_TYPE]: true }表示文件类型不在要支持的类型中。 |

Usage

const control = new FormControl(new File(),[NbFormValidators.fileType(['image/jpeg','image/png'])]);
console.log(control.errors); // { [NbControlErrType.FILE_TYPE]: true; }

NbFormValidators.required

v12.0.0

必填校验器

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | required | boolean | false | 表单控件是否必填。默认为true. 如果为true,则会调用Validators.required, 否则不会对表单控件内容做必填校验 | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.REQUIRED]: true; }｜null | 校验结果。返回null表示符合条件。返回{ [NbControlErrType.REQUIRED]: true }表示表单控件不符合必填校验 |

Usage

const control = new FormControl('',[NbFormValidators.required(true)])
console.log(control.errors); // { [NbControlErrType.REQUIRED]: true; }

NbFormValidators.whitespace

v12.0.0

是否允许都为空格校验器

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | canWhitespace | boolean | false | 表单控件可以都是空格内容。默认为true. 如果为true, 则允许控件值都是空格. | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.WHITESPACE]: true; }｜null | 校验结果。返回null表示符合条件。返回{ [NbControlErrType.WHITESPACE]: true }表示不允许都是空格的情况下，表单控件值都是空格 |

Usage

const control =new FormControl('    ',[NbFormValidators.whitespace(false)])
console.log(control.errors); // { [NbControlErrType.WHITESPACE]: true; }

Services

NbFormService

v12.0.0

提供常用表单功能的service

Methods

| Name | Return | Description | Scenes | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | getValidatorsFromControlConfig(config: INbControlConfig) | ValidatorFn[] | 根据配置信息，获取校验器数组。可配置的条件有：required,max,min,maxLength,minLength,arrMaxLength,arrMinLength,maxFileSize,minFileSize,fileType,pattern,whitespace。其中max,min,maxLength,minLength,pattern等返回的是Validators提供的校验器。剩下的则为NbFormValidators提供的校验器 | 需要根据配置信息快速设置校验器数组时 | v12.0.0 | | markAllAsDirty(control: NbAbstractControl, opts?: { onlySelf?: boolean; emitEvent?: boolean; }) | void | 将表单控件以及子控件都标记为dirty。control为要标记的控件，opts会在标记时，传给控件以及每个子控件 | 适合想将一个控件以及自控件都标记为dirty的场景 | v12.0.0 | | showAllErrInfo(control: NbAbstractControl, opts?: { onlySelf?: boolean; emitEvent?: boolean; }) | void | 展示控件以及子控件的所有错误信息。通过调用control.markAllAsTouched,markAllAsDirty,updateAllValueAndValidity等常用方法，让错误信息在UI上展示出来。control为要操作的控件，opts会在调用markAllAsDirty,updateAllValueAndValidity时，传给控件以及每个子控件 | 适合想将控件以及子控件的错误信息都展示给用户的场景，比如表单提交时。 | v12.0.0 | | updateAllValueAndValidity(control: NbAbstractControl, opts?: { onlySelf?: boolean; emitEvent?: boolean; }) | void | 将表单控件以及子控件都更新值和值的有效性。control为要操作的控件，opts会在操作时，传给控件以及每个子控件 | 适合想让控件和子控件都更新值和值的有效性的场景 | v12.0.0 | | updateEqualControlsValidities(controls: { target: AbstractControl; compared: AbstractControl }, destroy$?: Subject) | Subscription | 更新两个想相等的控件的有效性。只有当前后两次某个控件的状态改变时才会触发。这是一个订阅事件，返回值为订阅事件的索引。可通过它来取消事件的订阅。或者传入一个destroy$参数，在需要的时候通过destroy$发送值来取消订阅 | 适合结合NbFormValidators.equal校验器，及时更新两个控件是否相等的状态，比如更改密码时的新密码和重复密码的验证 | v12.1.0 |

Usage

constructor(private formService: NbFormService) {}

const config:INbControlConfig={required:true,whitespace:false};
const validators = this.formService.getValidatorsFromControlConfig(config);
new FormControl('',validators);


const form = new FormGroup({
  // ...
});
this.markAllAsDirty(form,{onlySelf:true});


const form = new FormGroup({
  // ...
});
this.showAllErrInfo(form,{onlySelf:true});


const form = new FormGroup({
  // ...
});
this.updateAllValueAndValidity(form,{onlySelf:true});

const passwordControl = new FormControl();
const repeatPasswordControl = new FormControl();
passwordControl.setValidators([NbFormValidators.equal(repeatPasswordControl,false)]);
repeatPasswordControl.setValidators([NbFormValidators.equal(passwordControl,false)]);
const controls = {target:passwordControl,compared:repeatPasswordControl};
// 通过返回值取消订阅
const subscription = this.updateEqualControlsValidities(controls);
subscription.unsubscribe();
// 通过destroy$取消订阅
const destroy$ = new Subject<void>();
this.updateEqualControlsValidities(controls,destroy$);
destroy$.next();
destroy$.complete();

Components

<nb-control-err></nb-control-err>

v12.0.0

从v15.1.0开始为standalone component

显示控件错误信息时使用的组件。错误信息支持string和Observable<string>, 以便适合多语言场景。可在providers中设置常用的错误信息，和单独传入该组件的错误信息将合并成最终使用的错误信息

Input

| Name | Type | Mandatory | Default | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | | control | AbstractControl | true | - | 要显示的错误信息所属的控件。从v16.0.0开始，为必需属性 | v12.0.0 | | errInfo | INbControlErrInfo | false | {} | 当前控件的错误信息，会和providers中设置常用的错误信息一起组合成最终使用的错误信息。如果不传，则只会显示providers中设置常用的错误信息 | v12.0.0 |

Usage

<!-- control = new FormControl() -->
<!-- errInfo = {required:'这个字段必填！'} -->
<nb-control-err [control]="control" [errInfo]="errInfo" />

<!-- If the control is missing, an error will be reported -->
<nb-control-err [errInfo]="errInfo" />

// v15.1.0新增
// 在NgModule中引入
@NgModule({
  imports:[NbControlErrComponent],
  // ...
})
export class XXXModule{}

// 在standalone component中引入
@Component({
  standalone:true,
  imports:[NbControlErrComponent],
  // ...
})
export class XXXComponent{}

<nb-field-item></nb-field-item>

v12.0.0

从v15.1.0开始为standalone component

字段项组件，常用于表单中。提供常见的字段布局，以及错误信息的展示

[field-label]

字段标签

Input

| Name | Type | Mandatory | Default | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | | control | AbstractControl ｜ undefined | false | - | 要显示错误信息的控件。 | v12.0.0 | | errInfo | INbControlErrInfo | false | {} | 要显示的错误信息。如果不传，则只会显示providers中设置常用的错误信息 | v12.0.0 | | required | boolean | false | false | 该字段是否必填。如果必填，字段标签左侧会出现一个"*"。默认为false | v12.0.0 |

Usage

<!-- 设置字段标签和字段内容，非必填，不显示错误信息 -->
<nb-field-item>
  <ng-container field-label>field 1</ng-container>
  <input>
</nb-field-item>

<!-- 必填，显示错误信息 -->
<nb-field-item [required]="true" [control]="control" [errInfo]="errInfo">
  <ng-container field-label>field 2</ng-container>
  <input>
</nb-field-item>

// v15.1.0新增
// 在NgModule中引入
@NgModule({
  imports:[NbFieldItemComponent],
  // ...
})
export class XXXModule{}

// 在standalone component中引入
@Component({
  standalone:true,
  imports:[NbFieldItemComponent],
  // ...
})
export class XXXComponent{}

Tokens

NB_CONTROL_COMMON_ERR_INFO

INbControlErrInfo

v15.0.0

NB_CONTROL_COMMON_ERR_INFO_TOKEN

INbControlErrInfo

v12.0.0, 从v15.0.0开始为@deprecated

用于设置常见的错误信息，避免每个地方都需要设置一遍。设置后，会和每个<nb-control-err></nb-control-err>组件中传入的错误信息组合成最终的错误信息。

Usage

  providers: [
    // ...
    {
      provide: NB_CONTROL_COMMON_ERR_INFO,
      useFactory: (transService: NbTransService) => ({
        [NbControlErrType.FILE_TYPE]: transService.translationAsync('fileType'),
        [NbControlErrType.FILE_MIN_SIZE]: 'The file min file is 50KB!',
      }),
      deps: [NbTransService]
    },
    // ...
  ]

Interfaces

NbAbstractControl

v12.0.0

抽象控件类型，包含AbstractControl, null, undefined 等3种类型

INbControlConfig

v12.0.0

控件配置

| Property | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | required | boolean | false | 是否必填 | v12.0.0 | | max | number | false | 最大值 | v12.0.0 | | min | number | false | 最小值 | v12.0.0 | | maxLength | number | false | 最大长度 | v12.0.0 | | minLength | number | false | 最小长度 | v12.0.0 | | arrMaxLength | number | false | 数组最大长度 | v12.0.0 | | arrMinLength | number | false | 数组最小长度 | v12.0.0 | | maxFileSize | number | false | 最大文件大小 | v12.0.0 | | minFileSize | number | false | 最小文件大小 | v12.0.0 | | fileType | string[] | false | 支持的文件类型 | v12.0.0 | | pattern | string ｜ RegExp | false | 正则表达匹配 | v12.0.0 | | whitespace | boolean | false | 是否可以都是空格 | v12.0.0 | | initValue | any | false | 初始值 | v12.0.0 | | placeholder | string | false | placeholder | v12.0.0 | | [key: string] | any | false | 拓展配置 | v12.0.0 |

INbControlErrInfo

v12.0.0

控件错误信息

| Property | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | [key: string] | string｜Observable<string> | false | key值为字符串类型，value值为字符串类型或者可观察者对象。key表示错误类型，value为显示到UI上的错误信息。支持直接显示和订阅显示，以便在多语言场景下使用 | v12.0.0 |

INbFormConfigs

v12.0.0

表单的控件配置

| Property | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | [key: string] | INbControlConfig | false | key值为表单的控件的名称，value为控件的配置信息 | v12.0.0 |

Enums

NbControlErrType

v15.0.0

NbControlErrTypeEnum

v12.0.0, 从v15.0.0开始为@deprecated

常用表单错误枚举

| Key | Value | Description | Version | | ------------ | ------------ | ------------ | ------------ |
| REQUIRED | required | 必填错误 | v12.0.0 | | FILE_MAX_SIZE | fileMaxSize | 最大文件大小错误 | v12.0.0 | | FILE_MIN_SIZE | fileMinSize | 最小文件大小错误 | v12.0.0 | | FILE_TYPE | fileType | 文件类型 | v12.0.0 | | EQUAL | equal | 相等错误 | v12.0.0 | | MAX_LENGTH | maxlength | 最大长度错误 | v12.0.0 | | MIN_LENGTH | minlength | 最小长度错误 | v12.0.0 | | ARR_MAX_LENGTH | arrMaxLength | 数组最大长度错误 | v12.0.0 | | ARR_MIN_LENGTH | arrMinLength | 数组最小长度错误 | v12.0.0 | | WHITESPACE | whitespace | 空格错误 | v12.0.0 |

贡献

欢迎提feature和PR，一起使该项目更好

License

MIT