Ez FormForm Instance API
useForm()
Create a form instance, which contains all form's logic.
export function useForm(settings?: FormSettings): FormInstance;First argument is a form settings. Return a form instance.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
</script>form.meta
An object take all form data and states.
Type
export interface FormMeta<Values = any> {
name: string;
values: Values;
errors: ValidateError[];
dirty: boolean;
}
export interface FormInstance {
meta: FormMeta;
}form.meta.values
Contains all form's data. You can use it to access form's data from outside of EzForm.
Example
<script lang="ts" setup>
import { watch } from "vue";
import { useForm } from "@niku/ez-form";
const form = useForm();
watch(
() => form.values.foo.bar,
() => {
// Do things
}
);
</script>form.meta.errors
Contains all form's errors. This is useful when you need to show form's errors outside of form.
Example
<script lang="ts" setup>
import { watch } from "vue";
import { useForm } from "@niku/ez-form";
const form = useForm();
watch(
() => form.errors,
() => {
if (form.errors) {
alert("There are some errors with the form!!");
}
}
);
</script>form.meta.dirty
Determine if form is dirty, changed data. Useful when you need to do things only when the form is dirty.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
if (form.dirty) {
alert("The form is changed");
}
};
</script>form.meta.name
Name of form, use to generate form input id.
form.getFieldValue()
Get value of form's field.
Type:
interface FormInstance {
getFieldValue(name: NamePath): any;
}Have only one argument, is a NamePath that point to the field.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
const itemValue = form.getFieldValue("path.to.field");
};
</script>form.setFieldValue()
Set value of form's field.
Type:
interface FormInstance {
setFieldValue(name: NamePath, value: any): void;
}First argument is a NamePath that point to the field. Second argument is value will be set to the field.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
form.setFieldValue("path.to.field", bar);
};
</script>form.validate()
Validate form's data.
Type:
interface FormInstance {
validate(name?: string | NamePath[], options?: ValidateOption): Promise<any>;
}First argument is a NamePath that point to the field. Take ValiadteOption as second argument.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
form.validate("path.to.field", { trigger: "blur" });
};
</script>form.clearValidate()
Validate form's data.
Type:
interface FormInstance {
clearValidate(name?: NamePath): void;
}Take only one argument, is a NamePath that point to the field.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
// Clear form validate
form.clearValidate();
// Clear field's validate
form.clearValidate("path.to.field");
};
</script>form.submit()
Submit form's data.
Type:
interface FormInstance {
submit: <
S extends FormSubmitCallback<Values> | undefined = undefined,
E extends FormErrorCallback | undefined = undefined
>(
onSuccess?: FormSubmitCallback<Values> | S,
onError?: FormErrorCallback | E
) => S extends FormSubmitCallback<Values>
? void
: E extends FormErrorCallback
? void
: Promise<{ values?: Values; errors?: ValidateError[] }>;
}First argument, is a onSuccess callback, which will be called after form's data validate success. Second one is onError, will be called after form's data validate failed.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
// Submit with callbacks
form.submit(
(values) => {
console.log("Form submit", values);
},
(errors) => {
console.log("Form errors", errors);
}
);
// Submit with promise
form.submit().then(({ values, errors }) => {
if (errors) {
console.log("Form errors", errors);
} else {
console.log("Form submit", values);
}
});
};
</script>form.reset()
Reset form's data, state, validate.
Type:
interface FormInstance {
reset: (values?: Values) => void;
}There is only one argument, which is new data of form. If it is not provided, form will be reset to initialValues.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
form.reset();
};
</script>form.isDirty()
Check if form's field is dirty.
Type:
interface FormInstance {
isDirty: (name?: NamePath) => boolean;
}There is only one argument, which is field's NamePath. If it is not provided, form dirty will be returned.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
form.isDirty(["path", "to", "field"]);
};
</script>form.updateSettings()
Change form settings. Useful when you want to update form settings, like validateMessages.
Type:
interface FormInstance {
updateSettings(settings: Partial<FormSettings>): void;
}There is only one argument, which is FormSettings.
Example
<script lang="ts" setup>
import { useForm } from "@niku/ez-form";
const form = useForm();
const foo = () => {
form.updateSettings({
validateMessages: {
...
}
});
};
</script>form.addField()
Register a form item as a field of form. Don't use this to register form item, use useFormItem().registerFormField() instead.
Type:
interface FormInstance {
addField(field: FormField): void;
}form.removeField()
Un-register a form item from form. Will be used inside useFormItem.
Type:
interface FormInstance {
removeField(name: NamePath): void;
}