vue-final-form
Introduction
Install
yarn add final-form vue-final-form
Usage
This library exports two components:
import { FinalForm, FinalField } from 'vue-final-form'
The first component you'll need is the FinalForm
component:
<FinalForm :submit="submit"> <!-- ignore the children for now --> </FinalForm>
The only required prop is submit
, it defines how to submit the form data, maybe simply log it:
function submit(values) { console.log(values) }
The rendered output is:
<div></div>
As you can see it does nothing for now, you need to feed it a <form>
:
<FinalForm :submit="submit"> <form slot-scope="props" @submit="props.handleSubmit"> <!-- ignore the children for now --> </form> </FinalForm>
Now it renders:
<div><form></form></div>
Here it uses the scoped slots
feature from Vue.js (>=2.1.0), props.handleSubmit
is the actual method it will run to submit data.
Next let's define a form field with <FinalField>
component:
<FinalForm :submit="submit"> <form slot-scope="props" @submit="props.handleSubmit"> <FinalField name="username" :validate="v => v ? null : 'this is required'"> <div slot-scope="props"> <input v-on="props.events" :name="props.name"> <span v-if="props.meta.error && props.meta.touched"> {{ props.meta.error }} </span> </div> </FinalField> </form> </FinalForm>
Things got a bit more complex, but it's easy if you try to understand:
The only prop that is required by FinalField
is name
, it tells the field where to store the field data in the form state, here we stores it as state.username
.
The validate
prop is used to validate the field data, it could be a function that returns an error message or null
, undefined
when it's considered valid.
The data that FinalField
passed to its children contains props.events
which is required to be bound with the input
element in order to properly track events. And props.name
is the name
you gave FinalField
, props.meta
is some infomation about this field.
API
<FinalForm>
Props
submit
Type: function
Default: () => {}
Here we allow submit
to be optional since you may not need it when you just use vue-final-form
as a form validation tool.
See onSubmit.
validate
Type: function
Array<function>
A whole-record validation function that takes all the values of the form and returns any validation errors.
See validate.
initialValues
Type: object
See initialValues.
subscription
Type: FormSubscription
Default: All
See FormSubscription.
Events
change
Params:
Scoped slot props
It basically exposes everything in FormState plus follwoings:
handleSubmit
Type: function
The function that you will invoke to submit the form data, you may use it as the :submit
event handler on your <form>
.
reset
Type: function
See FormApi.reset.
mutators
Type: ?{ [string]: Function }
See FormApi.mutators.
batch
Type: function
See FormApi.batch.
blur
Type: function
See FormApi.blur.
change
Type: function
See FormApi.change.
focus
Type: function
See FormApi.focus
initialize
Type: function
See FormApi.initialize.
<FinalField>
Props
name
Type: string
Required: true
The name of this field.
See name.
validate
Type: function
Array<function>
A field-level validation function to validate a single field value. Returns an error if the value is not valid, or undefined if the value is valid.
See validate.
subscription
Type: FieldSubscription
Default: All
See FieldSubcription.
Events
change
Params:
Scoped slot props
It basically exposes FieldState.
name
Type: string
The name of this field.
See FieldState.name
change
Type: function
value
Type: any
.
The current value of this field. You should probably bind it to :value
of input
or textarea
if you have set initial value for the field.
events
Type: { input: Function, focus: Function, blur: Function }
Bind these event handlers to your input
textarea
element.
See FieldState.change, FieldState.focus, FieldState.blur.
meta
Type: object
Everything in FieldState except for blur
change
focus
name
Contributing
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature
- Commit your changes:
git commit -am 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request :D
Author
vue-final-form © EGOIST, Released under the MIT License.
Authored and maintained by EGOIST with help from contributors (list).
egoist.moe · GitHub @EGOIST · Twitter @_egoistlily