From 51b7a669139270c5cdab807ecb3f7a3eb35885e2 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan@youzan.com>
Date: Wed, 28 Jul 2021 17:20:11 +0800
Subject: [PATCH] types(Form): add FormInstance type (#9139)

* types(Form): add FormInstance type

* types: useExpose type
---
 src/composables/use-expose.ts |  2 +-
 src/form/Form.tsx             | 25 ++++++++++++++++++++++---
 src/form/README.md            | 13 +++++++++++++
 src/form/README.zh-CN.md      | 13 +++++++++++++
 src/form/index.ts             |  1 +
 5 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/src/composables/use-expose.ts b/src/composables/use-expose.ts
index e42909145..dd20feda1 100644
--- a/src/composables/use-expose.ts
+++ b/src/composables/use-expose.ts
@@ -2,7 +2,7 @@ import { getCurrentInstance } from 'vue';
 import { extend } from '../utils';
 
 // expose public api
-export function useExpose(apis: Record<string, any>) {
+export function useExpose<T = Record<string, any>>(apis: T) {
   const instance = getCurrentInstance();
   if (instance) {
     extend(instance.proxy, apis);
diff --git a/src/form/Form.tsx b/src/form/Form.tsx
index 8156f5d62..63e9f1e96 100644
--- a/src/form/Form.tsx
+++ b/src/form/Form.tsx
@@ -1,4 +1,9 @@
-import { PropType, defineComponent, ExtractPropTypes } from 'vue';
+import {
+  PropType,
+  defineComponent,
+  ExtractPropTypes,
+  ComponentPublicInstance,
+} from 'vue';
 
 // Utils
 import { truthProp, createNamespace } from '../utils';
@@ -36,8 +41,22 @@ const props = {
   },
 };
 
+type FormProps = ExtractPropTypes<typeof props>;
+
+type FormExpose = {
+  submit: () => void;
+  validate: (name?: string | string[] | undefined) => Promise<void>;
+  scrollToField: (
+    name: string,
+    options?: boolean | ScrollIntoViewOptions | undefined
+  ) => void;
+  resetValidation: (name?: string | string[] | undefined) => void;
+};
+
+export type FormInstance = ComponentPublicInstance<FormProps, FormExpose>;
+
 export type FormProvide = {
-  props: ExtractPropTypes<typeof props>;
+  props: FormProps;
 };
 
 export default defineComponent({
@@ -174,7 +193,7 @@ export default defineComponent({
     };
 
     linkChildren({ props });
-    useExpose({
+    useExpose<FormExpose>({
       submit,
       validate,
       scrollToField,
diff --git a/src/form/README.md b/src/form/README.md
index 6268c855a..5e8a2674c 100644
--- a/src/form/README.md
+++ b/src/form/README.md
@@ -543,6 +543,19 @@ Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get Form i
 | resetValidation | Reset validation | _name?: string \| string[]_ | - |
 | scrollToField | Scroll to field | _name: string, alignToTop: boolean_ | - |
 
+### Types
+
+Get the type definition of the Form instance through `FormInstance`.
+
+```ts
+import { ref } from 'vue';
+import type { FormInstance } from 'vant';
+
+const formRef = ref<FormInstance>();
+
+formRef.value?.submit();
+```
+
 ### Slots
 
 | Name    | Description  |
diff --git a/src/form/README.zh-CN.md b/src/form/README.zh-CN.md
index 10af58119..f0b444275 100644
--- a/src/form/README.zh-CN.md
+++ b/src/form/README.zh-CN.md
@@ -582,6 +582,19 @@ export default {
 | resetValidation | 重置表单项的验证提示，支持传入 `name` 来重置单个或部分表单项 | _name?: string \| string[]_ | - |
 | scrollToField | 滚动到对应表单项的位置，默认滚动到顶部，第二个参数传 false 可滚动至底部 | _name: string, alignToTop: boolean_ | - |
 
+### 类型定义
+
+通过 `FormInstance` 获取 Form 实例的类型定义。
+
+```ts
+import { ref } from 'vue';
+import type { FormInstance } from 'vant';
+
+const formRef = ref<FormInstance>();
+
+formRef.value?.submit();
+```
+
 ### Slots
 
 | 名称    | 说明     |
diff --git a/src/form/index.ts b/src/form/index.ts
index 7aeffc426..21a86d2d6 100644
--- a/src/form/index.ts
+++ b/src/form/index.ts
@@ -5,3 +5,4 @@ const Form = withInstall<typeof _Form>(_Form);
 
 export default Form;
 export { Form };
+export type { FormInstance } from './Form';