Skip to content

Latest commit

 

History

History
394 lines (244 loc) · 8.09 KB

README.md

File metadata and controls

394 lines (244 loc) · 8.09 KB
Raw

vue-reactive-form

A reactive form library, which can help manage form data.

It can be used in all kinds of Form UI.

Besides, It uses TypeScript generics to manage the types of data.

Warning

This is only supported in Vue3 with composition API.

Install

npm i vue-reactive-form
yarn add vue-reactive-form

Usage

<template>
  <div class="container">
    <form>
      <div class="mb-3">
        <label for="email" class="form-label">Email address</label>
        <input id="email" v-model="email" type="input" class="form-control" />
        has error: {{ formGroup.controls.email.errors.value ? 'Yes': 'No' }}
      </div>
      <div class="mb-3">
        <label for="password" class="form-label">Password</label>
        <input
          id="password"
          v-model="password"
          type="password"
          class="form-control"
        />
      </div>
      <div class="mb-3 form-check">
        <input
          id="check"
          v-model="readMe"
          type="checkbox"
          class="form-check-input"
        />
        <label class="form-check-label" for="check">remember me</label>
      </div>
      <div class="mb-3">
        <label for="child" class="form-label">child test</label>
        <input id="child" v-model="child1" type="input" class="form-control" />
      </div>

      <button class="btn btn-primary me-3" @click.prevent="formGroup.reset()">
        Reset
      </button>

      <button
        type="submit"
        class="btn btn-primary"
        :disabled="!formGroup.valid"
        @click.prevent="handleClick()"
      >
        Submit
      </button>
    </form>
  </div>
</template>
import { defineComponent } from 'vue'
import FormGroup, {
  emailValidator,
  requiredValidator,
} from 'build/vue-reactive-form'

export default defineComponent({
  name: 'App',

  setup() {
    const formGroup = new FormGroup<{
      email: string
      password: string
      readMe?: boolean
      children: { child1: string }
    }>({
      email: {
        defaultValue: '[email protected]',
        validators: [requiredValidator(), emailValidator()],
      },

      password: null,
      readMe: null,
      children: { child1: null },
    })

    const {
      email,
      password,
      readMe,
      children: { child1 },
    } = formGroup.refs

    function handleClick() {
      console.log({ formGroup, values: formGroup.values.value })
    }

    return { email, password, readMe, child1, formGroup, handleClick }
  },
})

The following is the demo of this code.

Demo

Demo

PS. I use Bootstrap CDN for this demo page. However, It's not required to use with this "vue-reactive-form" package.

API

Builder

InputBuilder

This is used to define the input reference, which will be used in the following FormGroup.

Property type required default description
defaultValue AvailableType false null default value
validators Validator[] false [] Validators for the input, there are details in the fallowing 
type AvailableType =
  | boolean
  | number
  | string
  | Date
  | boolean[]
  | number[]
  | string[]
  | Date[]

AvailableType can also use as InputBuilder, which will stand for the defaultValue without validators.

FormBuilder

It's an Object with keys and values, and value could be the Following types.

This will create a FormControl as the control of created FormGroup.

This will create a FormGroup as the control of created FormGroup.

This will use this FormGroup as the control of created FormGroup.

Controls

The Classes, which are used to control the form.

FormControl

The Class used to control input.

  • ref

    type: Ref (Vue api)

    Vue refs API, which can be used in V-model.

  • validators

type: Validator

The validator set in the InputBuilder, used to check the input validity.

  • dirty

type: Ref<boolean> (Vue api)

It's false by default. After changing the value of the ref, it would be true.

  • errors

    type: ComputedRef<ValidationErrors> (Vue api)

    Errors generated by failing validation, or null if there are no errors.

  • valid

    type: ComputedRef<boolean> (Vue api)

    It's false by default. If it's dirty and the error is null, it would be true.

  • aware

    type: ComputedRef<boolean> (Vue api)

    It's false by default. If it's dirty and not valid, it would be true.

  • markAsDirty()

    return: void

    Mark the property dirty as true.

  • markAsPristine()

    return: void

    Mark the property dirty as false.

  • appendValidators(validator)

    args: Validator

    return: void

    Append the validator to the validators.

  • setValidators(validators)

    args: Validator | Validator[]

    return: void

    Set the validators.

  • clearValidators()

    return: void

    Clear the validators.

  • reset()

    return: void

    Reset the value, dirty, and the errors.

FormGroup

The main Class of this package. It's used to create a form group with not only inputs but also other form groups.

It's also the default export of this package.

To create a form group, you can use FormBuilder object.

TypeScript type support for the form controls.

The generic Type variable "T" is the type of the FormBuilder used to create the form group.

  • dirty

    type: Ref<boolean> (Vue api)

    It's false by default. After changing any form control value it would be marked as true.

  • errors

    type: ComputedRef<FormErrors<T>>

    It's an assembly of all the errors of the form controls. If there is no error, it would be null.

  • valid

    type: ComputedRef<boolean> (Vue api)

    It's false by default, if it's dirty and the error is null, it would be marked as true.

  • markAsDirty()

    return: void

    Mark the properties dirty in all the form controls as true.

  • markAsPristine()

    return: void

    Mark the properties dirty in all the form controls as false.

  • reset()

    return: void

    Reset the value, dirty and the errors of all the form controls.

  • controls

    type: FormControls<T>

    It's an assembly of all the form controls or form groups.

  • refs

    type: FormRefs<T>

    It's an assembly of all the refs of the form controls or form groups.

    It can be used in the V-model.

    • appendFormControl(formBuilder)

    args: FormBuilder

    return: void

    Append a group of form controls to the form group.

  • removeFormControl(key)

    args: string | string[]

    return: void

    Remove one or more form controls from the form group by the key of the property.

Validator

The function is used to check the validity of the input.

The type of the validator is defined as the following.

You can also use ValidatorFactory

export type ValidationErrors = {
  [key: string]: any
}

export type Validator = (value: AvailableType) => ValidationErrors | null

This package also provides some validator factories to create validator as the following, but you can also use your validators or validator factories.

  • requiredValidator()

    error type: {required: true}

    To check if the input has a value.

  • emailValidator()

    error type: {email: 'email'}

    It's to check if the value is an email.

  • patternValidator(regex)

    args: RegExp | string

    error type: {pattern: 'pattern'}

    It's to check if the value matches the regex.

  • maxLengthValidator(maxLength)

    args: number

    error type: {maxLength: number}

    It's to check if the value is less than the maxLength.

  • maxLengthValidator(minLength)

    args: number

    error type: {minLength: number}

    It's to check if the value is greater than the minLength.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT © ronny1020