Getting Started

@delon/form is a dynamic build form based on the JSON Schema standard.

Features

  • Compliance with the JSON Schema standard

  • Based on the ng-zorro-antd library

  • Built on the design principles developed by Ant Design

  • Twenty different widgets

  • Customizable widgets

  • No third-party dependencies, so applicable to all antd projects

How to read document

This document uses the following conventions:

  • With schema. prefix is JSON Schema properties

  • With ui. prefix is UI properties

  • Some widget data sources are divided into static and realtime

    • Static refers to the schema.enum value, which is JSON Schema standard, and limited to the array format any[]

    • Real-time refers to the ui.asyncData value, which is not JSON Schema standard, the format (input?: any) => Observable<SFSchemaEnumType[]>

Usage

Install @delon/form from yarn.

yarn add @delon/form

Import DelonFormModule in to your root AppModule.

import { DelonFormModule } from '@delon/form';

@NgModule({
  imports: [
    DelonFormModule.forRoot()
  ]
})
export class AppModule { }

Although the default @delon/form validator is ajv, you can override SchemaValidatorFactory to use other validator libraries.

Global Configuration

Please refer to Global Configuration, the members are as follows:

PropertyDescriptionTypeDefault
[ajv]ajv optionsAjv.Options-
[ingoreKeywords]Whether to ignore data type validator (all types)string[][ 'type', 'enum' ]
[liveValidate]Whether to live validatebooleantrue
[autocomplete]autocomplete value of this formon,offnull
[firstVisual]Whether to show visual error immediatelybooleanfalse
[onlyVisual]Whether only show visual error not include text, and cancel the error text spacingbooleanfalse
[errors]Customize error messages{ [ key: string ]: string }ERRORSDEFAULT
[ui]Default global ui propertySFUISchemaItem-
[size]Size of the all angular elementdefault,large,small-
[button]Submit button of the formSFButton{submit:'提交',submit_type:'primary',reset:'重置',reset_type:'default'}
[uiDateStringFormat]Date widget default formatstringyyyy-MM-dd HH:mm:ss
[uiDateNumberFormat]Date widget default formatstringT
[uiTimeStringFormat]Time widget default formatstringHH:mm:ss
[uiTimeNumberFormat]Time widget default formatstringT
[uiEmailSuffixes]Specify the default Email suffix for format: 'email'string[]['qq.com', '163.com', 'gmail.com', '126.com', 'aliyun.com']
[delay]Whether to delay rendering, should be manually call refreshSchema()booleanfalse

For example, Build a email and name form:

@Component({
    selector: 'app-home',
    template: `
    <sf [schema]="schema" (formSubmit)="submit($event)"></sf>
    `
})
export class HomeComponent {
  schema: SFSchema = {
    properties: {
      email: {
        type: 'string',
        title: 'Email',
        format: 'email',
        maxLength: 20
      },
      name: {
        type: 'string',
        title: 'Name',
        minLength: 3
      }
    }
  };

  submit(value: any) { }
}

API

sf

PropertyDescriptionTypeDefault
[layout]layout of the formhorizontal,vertical,inlinehorizontal
[schema]Required JSON SchemaSFSchema-
[ui]UI SchemaSFUISchema-
[formData]Default form valuesany-
[mode]Form type modedefault,search,editdefault
[button]Submit button of the formSFButton, 'none'{}
[firstVisual]Whether to show visual error immediatelybooleantrue
[liveValidate]Whether to live validatebooleantrue
[autocomplete]autocomplete value of this formon,offnull
[disabled]Whether to disabled statusbooleanfalse
[loading]Whether to load status,when true reset button is disabled status, submit button is loading statusbooleanfalse
[noColon]Whether to not display : after label text.booleanfalse
[compact]Whether compact stylebooleanfalse
[cleanValue]Whether to clean up data for undefined Schemabooleanfalse
[delay]Whether to delay rendering, should be manually call refreshSchema()booleanfalse
(formChange)Callback when data changesEventEmitter<{}>-
(formValueChange)Callback when value changesEventEmitter<SFValueChange>-
(formSubmit)Callback when submitting the formEventEmitter<{}>-
(formReset)Callback when resetting the formEventEmitter<{}>-
(formError)Callback when form checkEventEmitter<ErrorData[]>-

SFButton

PropertyDescriptionTypeDefault
[submit]Submit text of buttonstring提交
[submit_type]Submit type of buttonstringprimary
[submit_icon]Submit icon of buttonSFButtonIcon-
[reset]Reset text of buttonstring重置
[reset_type]Reset type of buttonstringdefault
[reset_icon]Reset icon of buttonSFButtonIcon-
[search]Search text of buttonstring搜索
[edit]Edit text of buttonstring保存
[render]Button layoutSFRenderButton-

SFValueChange

PropertyDescriptionTypeDefault
[value]Always return complete dataSFValue-
[path]Current triggered pathstring, nullnull
[pathValue]Current path valueSFValue-

Methods

Method NameDescriptionReturn Value
validForm is validboolean
valueThe current value of the formany
refreshSchemaRefresh JSON Schemavoid
resetResets the formvoid
validatorManually verify a formvoid
getPropertyGet a form property via pathFormProperty
getValueGet value via pathany
setValueSet value via path, should be throw error when invalid paththis
updateFeedbackSet feedback status via paththis

Note: All paths are separated by /, for example: /user/name, /arr/0/name.

Button

Notice

  • Manually add button when value is null or undefined, but keeping container element.

  • Manually add button when value is none, but removed container element.

  • When using fixed label width. Default is center when render.class is not spacifid.

Custom Button

NOTICE: Must be setting button value is null.

<sf #sf [button]="null">
    <button type="submit" nz-button [disabled]="!sf.valid">Save</button>
    <button (click)="sf.reset()" type="button" nz-button>Reset</button>
</sf>

FAQ

What is mode

mode is just a quick action, which has the highest priority, rules:

  • default default mode, do nothing

  • search search mode, automatically set layout: inlinefirstVisual: falseliveValidate: falsebutton.submit: 'Search'

  • edit edit mode, automatically set layout: horizontalfirstVisual: falseliveValidate: truebutton.submit: 'Save'

Schema Internationalization

sf doesn't support any Schema internationalization, this is because Schema itself is a group of JSON values, you can just provide different versions of languages to support internationalization.