@bigbear713/nb-form

Angular common form lib by bigBear713.

OnlineDemo

Bug Report

Feature Request

Document

• 中文
• English

Changelog

• 中文
• English

Feature

• Provide the common validators: arrLength, equal, fileSize, fileType, required, whitespace. You can see the definition below;
• Support to use DI to set common error info;
• Support the changeDetection of components as ChangeDetectionStrategy.OnPush;
• Support to used in standalone component;
• Support to be imported as a standalone component;

Version

The nb-form's major version will keep up with the Angular's major version

| @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 | | ^18.0.0 | ^18.0.0 |

Installation

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

API

Module

NbFormModule

Form module. After importing the module, you can use the component. The service and validators also can be used if you don't import the module.

NbFormTestingModule

Form testing module, used fo unit test.

Validators

NbFormValidators.arrLength

v12.0.0

Array length validator

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | arrLength | { max?: number; min?: number } | true | The limit about array length. You can set max/min value alone | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.ARR_MAX_LENGTH]?: true;[NbControlErrType.ARR_MIN_LENGTH]?: true; }｜null | The result. If it is null, the condition is met or the value of control is not a array value. If the result is { [NbControlErrType.ARR_MAX_LENGTH]: true }, the control array value's length is greater than max limit value. If the result is { [NbControlErrType.ARR_MIN_LENGTH]: true }, the control array value's length is less than the min limit value. |

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(minC  ontrol.errors); // { [NbControlErrType.ARR_MIN_LENGTH]: true }

NbFormValidators.equal

v12.0.0

Values are equal validator. When the values of the controls are not equal, only the target control will have the no equal error info. If you want to make the target and compared control all have the error info, can refer to the demo

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | compared | AbstractControl | true | The control which will be compared with the current control | v12.0.0 | | immediately | boolean | false | Verify immediately. If set it as false, it will verify the value until the compared control is dirty. The default is true | v12.1.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.NOT_EQUAL]: true; }｜null | The result. If the two control's values are equal, the result is null. If the valus are not equal, the result is { [NbControlErrType.NOT_EQUAL]: true }. When the values are not equal, the compared control will has the no equal error info. |

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

File size validator

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | fileSize | { max?: number; min?: number } | true | The limit of file size. You can set the max/min limit alone. The limit value's unit is B. | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.FILE_MAX_SIZE]?: true;[NbControlErrType.FILE_MIN_SIZE]?: true; }｜null | The result. If is is null, the condition is met or the control's value is not a File type value. If the result is { [NbControlErrType.FILE_MAX_SIZE]: true }, the file size is greater than the max limit value. If the result is { [NbControlErrType.FILE_MIN_SIZE]: true }, the file size is less than the min limit value. |

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

File type validator

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | types | string[] | true | The file types you want to support. The types value should be MIME Type value. | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.FILE_TYPE]: true; }｜null | The result. If it is null, the condition is met or the value of control is not a Filevalue. If the result is { [NbControlErrType.FILE_TYPE]: true }, the control's file type is among the types to be supported |

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

Required validator

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | required | boolean | false | Is the control required. The default is true. If the param is true, it will call the Validators.required, otherwise it will not do the check | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.REQUIRED]: true; }｜null | The result. If it is null, the condition is met. If the result is { [NbControlErrType.REQUIRED]: true }, the control's value shoule be required. |

Usage

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

NbFormValidators.whitespace

v12.0.0

Can all be whitespace validator

Params

| Name | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | canWhitespace | boolean | false | Can the control's value all be whitespace? The default is true. If the param is true, user can only enter whitespaces. | v12.0.0 |

Return

| Type | Description | | ------------ | ------------ | | { [NbControlErrType.WHITESPACE]: true; }｜null | The result. If it is null, the condition is met. If the result is { [NbControlErrType.WHITESPACE]: true }, the condition is not met. |

Usage

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

Services

NbFormService

v12.0.0

A service which provide some common function about form

Methods

| Name | Return | Description | Scenes | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | getValidatorsFromControlConfig(config: INbControlConfig) | ValidatorFn[] | Get the validator list based on the config param. The config you can set inlcude required,max,min,maxLength,minLength,arrMaxLength,arrMinLength,maxFileSize,minFileSize,fileType,pattern,whitespace. And max,min,maxLength,minLength,pattern will return the validators from Validators, others is from NbFormValidators | When you need to quickly set the validator list based on configuration information | v12.0.0 | | markAllAsDirty(control: NbAbstractControl, opts?: { onlySelf?: boolean; emitEvent?: boolean; }) | void | Mark the control and its sub-controls as dirty. The control is the target which you want to mark, opts param will be set to the control and its sub-controls | If you want to mark a control and its sub-controls as dirty | v12.0.0 | | showAllErrInfo(control: NbAbstractControl, opts?: { onlySelf?: boolean; emitEvent?: boolean; }) | void | Show the control and its sub-controls all error information. It will call the control.markAllAsTouched,markAllAsDirty,updateAllValueAndValidity functions to make the error info be displayed on UI. The control is the target you want to do. The opts param will be set to the control and its sub-controls when calling the markAllAsDirty,updateAllValueAndValidity functions | When you want to show the error info of control and its sub-controls to user, like submitting the form | v12.0.0 | | updateAllValueAndValidity(control: NbAbstractControl, opts?: { onlySelf?: boolean; emitEvent?: boolean; }) | void | Update the control and its sub-controls vaules and validities. The control param is the target you want to do, opts param will be set to the control and its sub-controls | When you want to update the control and its sub-controls vaules and validities | v12.0.0 | | updateEqualControlsValidities(controls: { target: AbstractControl; compared: AbstractControl }, destroy$?: Subject) | Subscription | Update the validities of the controls which want to be equal. The event will be done until one of the tow controls' status has been changed. This is a subscribe event and the return value of the function is the subscribe event index. So you can unsubribe it via the return value. Also you can input a destroy$ param and next a value via the destroy$ param to unsubscribe the event. | You can use it with NbFormValidators.equal validator, so the two controls' equal status can be updated in time, e.g. when change password, verify the new password and repeat new password are 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};
// unsubscribe it via return value
const subscription = this.updateEqualControlsValidities(controls);
subscription.unsubscribe();
// unsubscribe it via destroy$
const destroy$ = new Subject<void>();
this.updateEqualControlsValidities(controls,destroy$);
destroy$.next();
destroy$.complete();

Components

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

v12.0.0

Be a standalone component from v15.1.0

The component is used to show error info of the control. The error info support string and Observable<string> type, so you can use it in i18n. You can set common error info in providers, it will combined with error info which is inputed from the component.

Input

| Name | Type | Mandatory | Default | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | | control | AbstractControl | true | - | The control which the error info belong. The prop is required start from v16.0.0. | v12.0.0 | | errInfo | INbControlErrInfo | false | {} | Error information which only belong the control. It will combined with the common error infos which are set in providers. | v12.0.0 |

Usage

<!-- control = new FormControl() -->
<!-- errInfo = {required:'This field is required!'} -->
<nb-control-err [control]="control" [errInfo]="errInfo" />

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

// New in the v15.1.0
// imported in NgModule
@NgModule({
  imports:[NbControlErrComponent],
  // ...
})
export class XXXModule{}

// imported in standalone component
@Component({
  standalone:true,
  imports:[NbControlErrComponent],
  // ...
})
export class XXXComponent{}

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

v12.0.0

Be a standalone component from v15.1.0

The file item component, is used in form in common. It has common layout and can show error info

[field-label]

The file item's label

Input

| Name | Type | Mandatory | Default | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | | control | AbstractControl ｜ undefined | false | - | The control which error info belong. | v12.0.0 | | errInfo | INbControlErrInfo | false | {} | The error information. If it is undefined, the final error info is only the common error info from providers | v12.0.0 | | required | boolean | false | false | Is the field required? If is is true, there will display "*". The default is false | v12.0.0 |

Usage

<!-- set the field's label and field content. If there does not have control params, the error info will not be displayed -->
<nb-field-item>
  <ng-container field-label>field 1</ng-container>
  <input>
</nb-field-item>

<!-- Set the filed is required, and will display the error info -->
<nb-field-item [required]="true" [control]="control" [errInfo]="errInfo">
  <ng-container field-label>field 2</ng-container>
  <input>
</nb-field-item>

// New in the v15.1.0
// imported in NgModule
@NgModule({
  imports:[NbFieldItemComponent],
  // ...
})
export class XXXModule{}

// imported in 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, @deprecated from v15.0.0

Used to set common error info, so you don't need to set the common error info every where. If you set the common error info, it will auto be combined with the error info of <nb-control-err></nb-control-err> to be final error info.

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

Abstract control, include AbstractControl, null, undefined

INbControlConfig

v12.0.0

The config of control

| Property | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | required | boolean | false | Is required limit | v12.0.0 | | max | number | false | Max limit | v12.0.0 | | min | number | false | Min limit | v12.0.0 | | maxLength | number | false | Max length limit | v12.0.0 | | minLength | number | false | Min length limit | v12.0.0 | | arrMaxLength | number | false | Max length limit of array | v12.0.0 | | arrMinLength | number | false | Min length limit of array | v12.0.0 | | maxFileSize | number | false | Max size limit of file | v12.0.0 | | minFileSize | number | false | Min size limit of file | v12.0.0 | | fileType | string[] | false | The types limit of file | v12.0.0 | | pattern | string ｜ RegExp | false | The pattern limit | v12.0.0 | | whitespace | boolean | false | Can all be whitespace | v12.0.0 | | initValue | any | false | Initial value | v12.0.0 | | placeholder | string | false | placeholder | v12.0.0 | | [key: string] | any | false | more configs | v12.0.0 |

INbControlErrInfo

v12.0.0

Error informations. The key is the type of error, the value is error information

| Property | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | [key: string] | string｜Observable<string> | false | The key is string type, and the value is string or Observable type, so you can use it in i18n | v12.0.0 |

INbFormConfigs

v12.0.0

The configs of form control

| Property | Type | Mandatory | Description | Version | | ------------ | ------------ | ------------ | ------------ | ------------ | | [key: string] | INbControlConfig | false | The key is the control's name, the value is control's configs | v12.0.0 |

Enums

NbControlErrType

v15.0.0

NbControlErrTypeEnum

v12.0.0, @deprecated from v15.0.0

Common error enum

| Key | Value | Description | Version | | ------------ | ------------ | ------------ | ------------ |
| REQUIRED | required | Required error | v12.0.0 | | FILE_MAX_SIZE | fileMaxSize | File max size error | v12.0.0 | | FILE_MIN_SIZE | fileMinSize | File min size error | v12.0.0 | | FILE_TYPE | fileType | File type error | v12.0.0 | | EQUAL | equal | Equal error | v12.0.0 | | MAX_LENGTH | maxlength | Max length error | v12.0.0 | | MIN_LENGTH | minlength | Min length error | v12.0.0 | | ARR_MAX_LENGTH | arrMaxLength | Max length of array error | v12.0.0 | | ARR_MIN_LENGTH | arrMinLength | Min length of array error | v12.0.0 | | WHITESPACE | whitespace | whitespace error | v12.0.0 |

Contribution

Feature and PR are welcome to make this project better together

License

MIT