❤
npm
Sign UpSign In

@bigbear713/nb-form
TypeScript icon, indicating that this package has built-in type declarations

17.0.0 • Public • Published

@bigbear713/nb-form

Angular common form lib by bigBear713.

OnlineDemo

Bug Report

Feature Request

Document


Changelog


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

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

bigBear713


License

MIT

Readme

Keywords

Package Sidebar

Install

npm i @bigbear713/nb-form

Repository

github.com/bigBear713/nb-form

Homepage

github.com/bigBear713/nb-form/blob/main/projects/nb-form/README.md

Weekly Downloads

123

Version

17.0.0

License

MIT

Unpacked Size

187 kB

Total Files

62

Last publish

Collaborators

  • big-bear-713
Try on RunKit
Report malware