types: add FIeldInstance type (#9166)

src/field/Field.tsx

@@ -8,6 +8,7 @@ import {
   PropType,
   onMounted,
   defineComponent,
+  ExtractPropTypes,
 } from 'vue';
 
 // Utils
@@ -45,28 +46,20 @@ import { Cell } from '../cell';
 import type {
   FieldRule,
   FieldType,
+  FieldExpose,
   FieldTextAlign,
   FieldClearTrigger,
   FieldFormatTrigger,
   FieldValidateError,
   FieldAutosizeConfig,
   FieldValidateTrigger,
+  FieldFormSharedProps,
 } from './types';
 
 const [name, bem] = createNamespace('field');
 
-// Shared props of Field and Form
-type SharedProps =
-  | 'colon'
-  | 'disabled'
-  | 'readonly'
-  | 'labelWidth'
-  | 'labelAlign'
-  | 'inputAlign'
-  | 'errorMessageAlign';
-
 // provide to Search component to inherit
-export const fieldProps = {
+export const fieldSharedProps = {
   formatter: Function as PropType<(value: string) => string>,
   leftIcon: String,
   rightIcon: String,
@@ -106,29 +99,33 @@ export const fieldProps = {
   },
 };
 
+const props = extend({}, cellProps, fieldSharedProps, {
+  rows: [Number, String],
+  name: String,
+  rules: Array as PropType<FieldRule[]>,
+  autosize: [Boolean, Object] as PropType<boolean | FieldAutosizeConfig>,
+  labelWidth: [Number, String],
+  labelClass: unknownProp,
+  labelAlign: String as PropType<FieldTextAlign>,
+  autocomplete: String,
+  showWordLimit: Boolean,
+  errorMessageAlign: String as PropType<FieldTextAlign>,
+  type: {
+    type: String as PropType<FieldType>,
+    default: 'text',
+  },
+  colon: {
+    type: Boolean,
+    default: null,
+  },
+});
+
+export type FieldProps = ExtractPropTypes<typeof props>;
+
 export default defineComponent({
   name,
 
-  props: extend({}, cellProps, fieldProps, {
-    rows: [Number, String],
-    name: String,
-    rules: Array as PropType<FieldRule[]>,
-    autosize: [Boolean, Object] as PropType<boolean | FieldAutosizeConfig>,
-    labelWidth: [Number, String],
-    labelClass: unknownProp,
-    labelAlign: String as PropType<FieldTextAlign>,
-    autocomplete: String,
-    showWordLimit: Boolean,
-    errorMessageAlign: String as PropType<FieldTextAlign>,
-    type: {
-      type: String as PropType<FieldType>,
-      default: 'text',
-    },
-    colon: {
-      type: Boolean,
-      default: null,
-    },
-  }),
+  props,
 
   emits: [
     'blur',
@@ -155,7 +152,7 @@ export default defineComponent({
 
     const getModelValue = () => String(props.modelValue ?? '');
 
-    const getProp = <T extends SharedProps>(key: T) => {
+    const getProp = <T extends FieldFormSharedProps>(key: T) => {
       if (isDef(props[key])) {
         return props[key];
       }
@@ -517,7 +514,7 @@ export default defineComponent({
       renderMessage(),
     ];
 
-    useExpose({
+    useExpose<FieldExpose>({
       blur,
       focus,
       validate,

src/field/README.md

@@ -309,6 +309,19 @@ Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get Field
 | focus | Trigger input focus | -         | -            |
 | blur  | Trigger input blur  | -         | -            |
 
+### Types
+
+Get the type definition of the Field instance through `FieldInstance`.
+
+```ts
+import { ref } from 'vue';
+import type { FieldInstance } from 'vant';
+
+const fieldRef = ref<FieldInstance>();
+
+fieldRef.value?.focus();
+```
+
 ### Slots
 
 | Name       | Description                 |

src/field/README.zh-CN.md

@@ -328,6 +328,19 @@ export default {
 | focus  | 获取输入框焦点 | -    | -      |
 | blur   | 取消输入框焦点 | -    | -      |
 
+### 类型定义
+
+通过 `FieldInstance` 获取 Field 实例的类型定义。
+
+```ts
+import { ref } from 'vue';
+import type { FieldInstance } from 'vant';
+
+const fieldRef = ref<FieldInstance>();
+
+fieldRef.value?.focus();
+```
+
 ### Slots
 
 | 名称 | 说明 |

src/field/types.ts

@@ -1,4 +1,5 @@
-import type { Ref } from 'vue';
+import type { ComponentPublicInstance, ComputedRef, Ref } from 'vue';
+import type { FieldProps } from './Field';
 
 export type FieldType =
   | 'tel'
@@ -45,6 +46,31 @@ export type FieldProvide = {
   validateWithTrigger: (trigger: FieldValidateTrigger) => void;
 };
 
+// Shared props of Field and Form
+export type FieldFormSharedProps =
+  | 'colon'
+  | 'disabled'
+  | 'readonly'
+  | 'labelWidth'
+  | 'labelAlign'
+  | 'inputAlign'
+  | 'errorMessageAlign';
+
+export type FieldExpose = {
+  blur: () => void | undefined;
+  focus: () => void | undefined;
+  validate: (
+    rules?: FieldRule[] | undefined
+  ) => Promise<void | FieldValidateError>;
+  resetValidation: () => void;
+  /**
+   * @private
+   */
+  formValue: ComputedRef<unknown>;
+};
+
+export type FieldInstance = ComponentPublicInstance<FieldProps, FieldExpose>;
+
 declare global {
   interface EventTarget {
     composing?: boolean;

src/search/Search.tsx

@@ -9,7 +9,7 @@ import {
   preventDefault,
   ComponentInstance,
 } from '../utils';
-import { fieldProps } from '../field/Field';
+import { fieldSharedProps } from '../field/Field';
 
 // Composables
 import { useExpose } from '../composables/use-expose';
@@ -24,7 +24,7 @@ export type SearchShape = 'square' | 'round';
 export default defineComponent({
   name,
 
-  props: extend({}, fieldProps, {
+  props: extend({}, fieldSharedProps, {
     label: String,
     clearable: truthProp,
     actionText: String,
@@ -89,8 +89,8 @@ export default defineComponent({
     const blur = () => filedRef.value?.blur();
     const focus = () => filedRef.value?.focus();
 
-    const fieldPropNames = Object.keys(fieldProps) as Array<
-      keyof typeof fieldProps
+    const fieldPropNames = Object.keys(fieldSharedProps) as Array<
+      keyof typeof fieldSharedProps
     >;
 
     const renderField = () => {