@bigbear713/nb-form v17.0.0

@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的大版本保持对应关系

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

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

NbFormValidators.equal

v12.0.0

值是否相等校验器。当两个控件的值不相等时，当前控件会带有相关的错误信息。如果想两个控件都带有错误信息，可参考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

文件大小校验器

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

文件类型校验器

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

必填校验器

Params

Return

Usage

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

NbFormValidators.whitespace

v12.0.0

是否允许都为空格校验器

Params

Return

Usage

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

Services

NbFormService

v12.0.0

提供常用表单功能的service

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};
// 通过返回值取消订阅
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

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

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

控件配置

INbControlErrInfo

v12.0.0

控件错误信息

INbFormConfigs

v12.0.0

表单的控件配置

Enums

NbControlErrType

v15.0.0

NbControlErrTypeEnum

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

常用表单错误枚举

贡献

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

License

MIT