@bigbear713/nb-form v18.0.0

@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

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

Return

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

Return

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

Return

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

Return

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

Return

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

Return

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

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

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

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

INbControlErrInfo

v12.0.0

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

INbFormConfigs

v12.0.0

The configs of form control

Enums

NbControlErrType

v15.0.0

NbControlErrTypeEnum

v12.0.0, @deprecated from v15.0.0

Common error enum

Contribution

Feature and PR are welcome to make this project better together

License

MIT