feat(DropdownMenu): add close method (#11921)

* feat(DropdownMenu): add close method

* chore: update

packages/vant/src/dropdown-menu/DropdownMenu.tsx

@@ -22,6 +22,7 @@ import {
 
 // Composables
 import { useId } from '../composables/use-id';
+import { useExpose } from '../composables/use-expose';
 import {
   useRect,
   useChildren,
@@ -75,11 +76,15 @@ export default defineComponent({
       }
     });
 
+    const close = () => {
+      children.forEach((item) => {
+        item.toggle(false);
+      });
+    };
+
     const onClickAway = () => {
       if (props.closeOnClickOutside) {
-        children.forEach((item) => {
-          item.toggle(false);
-        });
+        close();
       }
     };
 
@@ -142,6 +147,7 @@ export default defineComponent({
       );
     };
 
+    useExpose({ close });
     linkChildren({ id, props, offset, updateOffset });
     useClickAway(root, onClickAway);
     useEventListener('scroll', onScroll, {

packages/vant/src/dropdown-menu/README.md

@@ -59,7 +59,7 @@ export default {
 ### Custom Content
 
 ```html
-<van-dropdown-menu>
+<van-dropdown-menu ref="menuRef">
   <van-dropdown-item v-model="value" :options="options" />
   <van-dropdown-item title="Title" ref="item">
     <van-cell center title="Title">
@@ -86,7 +86,8 @@ import { ref } from 'vue';
 
 export default {
   setup() {
-    const item = ref(null);
+    const menuRef = ref(null);
+    const itemRef = ref(null);
     const value = ref(0);
     const switch1 = ref(false);
     const switch2 = ref(false);
@@ -97,10 +98,13 @@ export default {
     ];
     const onConfirm = () => {
       item.value.toggle();
+      // or
+      // menuRef.value.close();
     };
 
     return {
-      item,
+      menuRef,
+      itemRef,
       value,
       switch1,
       switch2,
@@ -183,6 +187,14 @@ Use `active-color` prop to custom active color of the title and options.
 | default | Content      |
 | title   | Custom title |
 
+### DropdownMenu Methods
+
+Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get DropdownMenu instance and call instance methods.
+
+| Name  | Description              | Attribute | Return value |
+| ----- | ------------------------ | --------- | ------------ |
+| close | Close all dropdown items | -         | -            |
+
 ### DropdownItem Methods
 
 Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get DropdownItem instance and call instance methods.
@@ -201,18 +213,21 @@ import type {
   DropdownItemProps,
   DropdownItemOption,
   DropdownItemInstance,
+  DropdownMenuInstance,
   DropdownMenuDirection,
 } from 'vant';
 ```
 
-`DropdownItemInstance` is the type of component instance:
+`DropdownMenuInstance` and `DropdownItemInstance` are the types of component instances:
 
 ```ts
 import { ref } from 'vue';
-import type { DropdownItemInstance } from 'vant';
+import type { DropdownMenuInstance, DropdownItemInstance } from 'vant';
 
+const dropdownMenuRef = ref<DropdownMenuInstance>();
 const dropdownItemRef = ref<DropdownItemInstance>();
 
+dropdownMenuRef.value?.close();
 dropdownItemRef.value?.toggle();
 ```
 

packages/vant/src/dropdown-menu/README.zh-CN.md

@@ -58,12 +58,12 @@ export default {
 
 ### 自定义菜单内容
 
-通过插槽可以自定义 `DropdownItem` 的内容，此时需要使用实例上的 `toggle` 方法手动控制菜单的显示。
+通过插槽可以自定义 `DropdownItem` 的内容，此时需要使用 `DropdownMenu` 实例上的 `close` 或指定 `DropdownItem` 的 `toggle` 方法手动控制菜单的显示。
 
 ```html
-<van-dropdown-menu>
+<van-dropdown-menu ref="menuRef">
   <van-dropdown-item v-model="value" :options="options" />
-  <van-dropdown-item title="筛选" ref="item">
+  <van-dropdown-item title="筛选" ref="itemRef">
     <van-cell center title="包邮">
       <template #right-icon>
         <van-switch v-model="switch1" />
@@ -88,7 +88,8 @@ import { ref } from 'vue';
 
 export default {
   setup() {
-    const item = ref(null);
+    const menuRef = ref(null);
+    const itemRef = ref(null);
     const value = ref(0);
     const switch1 = ref(false);
     const switch2 = ref(false);
@@ -98,11 +99,14 @@ export default {
       { text: '活动商品', value: 2 },
     ];
     const onConfirm = () => {
-      item.value.toggle();
+      itemRef.value.toggle();
+      // 或者
+      // menuRef.value.close();
     };
 
     return {
-      item,
+      menuRef,
+      itemRef,
       value,
       switch1,
       switch2,
@@ -187,6 +191,14 @@ export default {
 | default | 菜单内容         |
 | title   | 自定义菜单项标题 |
 
+### DropdownMenu 方法
+
+通过 ref 可以获取到 DropdownMenu 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
+
+| 方法名 | 说明                   | 参数 | 返回值 |
+| ------ | ---------------------- | ---- | ------ |
+| close  | 关闭所有菜单的展示状态 | -    | -      |
+
 ### DropdownItem 方法
 
 通过 ref 可以获取到 DropdownItem 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
@@ -205,18 +217,21 @@ import type {
   DropdownItemProps,
   DropdownItemOption,
   DropdownItemInstance,
+  DropdownMenuInstance,
   DropdownMenuDirection,
 } from 'vant';
 ```
 
-`DropdownItemInstance` 是组件实例的类型，用法如下：
+`DropdownMenuInstance` 和 `DropdownItemInstance` 是组件实例的类型，用法如下：
 
 ```ts
 import { ref } from 'vue';
-import type { DropdownItemInstance } from 'vant';
+import type { DropdownMenuInstance, DropdownItemInstance } from 'vant';
 
+const dropdownMenuRef = ref<DropdownMenuInstance>();
 const dropdownItemRef = ref<DropdownItemInstance>();
 
+dropdownMenuRef.value?.close();
 dropdownItemRef.value?.toggle();
 ```
 

packages/vant/src/dropdown-menu/types.ts

@@ -1,4 +1,4 @@
-import type { Ref } from 'vue';
+import type { ComponentPublicInstance, Ref } from 'vue';
 import type { DropdownMenuProps } from './DropdownMenu';
 
 export type DropdownMenuDirection = 'up' | 'down';
@@ -10,6 +10,15 @@ export type DropdownMenuProvide = {
   updateOffset: () => void;
 };
 
+export type DropdownMenuExpose = {
+  close: () => void;
+};
+
+export type DropdownMenuInstance = ComponentPublicInstance<
+  DropdownMenuProps,
+  DropdownMenuExpose
+>;
+
 export type DropdownMenuThemeVars = {
   dropdownMenuHeight?: string;
   dropdownMenuBackground?: string;