docs(Popup): add events demo (#11444)

packages/vant/src/popup/README.md

@@ -22,7 +22,7 @@ app.use(Popup);
 
 ```html
 <van-cell is-link @click="showPopup">Show Popup</van-cell>
-<van-popup v-model:show="show">Content</van-popup>
+<van-popup v-model:show="show" :style="{ padding: '64px' }">Content</van-popup>
 ```
 
 ```js
@@ -106,15 +106,100 @@ The default position is `center`, it can be set to `top`, `bottom`, `left`, `rig
 
 ### Round Corner
 
+After setting the `round` prop, the Popup will add different rounded corner styles according to the position.
+
 ```html
+<!-- Round Popup (center) -->
+<van-popup v-model:show="showCenter" round :style="{ padding: '64px' }" />
+
+<!-- Round Popup (bottom) -->
 <van-popup
-  v-model:show="show"
+  v-model:show="showBottom"
   round
   position="bottom"
   :style="{ height: '30%' }"
 />
 ```
 
+### Listen To Click Events
+
+Popup supports following events:
+
+- `click`: Emitted when Popup is clicked.
+- `click-overlay`: Emitted when overlay is clicked.
+- `click-close-icon`: Emitted when close icon is clicked.
+
+```html
+<van-cell title="Listen Click Events" is-link @click="show = true" />
+<van-popup
+  v-model:show="show"
+  position="bottom"
+  :style="{ height: '30%' }"
+  closeable
+  @click-overlay="onClickOverlay"
+  @click-close-icon="onClickCloseIcon"
+/>
+```
+
+```js
+import { ref } from 'vue';
+import { showToast } from 'vant';
+
+export default {
+  setup() {
+    const show = ref(false);
+    const onClickOverlay = () => {
+      showToast('click-overlay');
+    };
+    const onClickCloseIcon = () => {
+      showToast('click-close-icon');
+    };
+    return {
+      show,
+      onClickOverlay,
+      onClickCloseIcon,
+    };
+  },
+};
+```
+
+### Listen to Display Events
+
+When the Popup is opened or closed, the following events will be emitted:
+
+- `open`: Emitted immediately when the Popup is opened.
+- `opened`: Emitted when the Popup is opened and the animation ends.
+- `close`: Emitted immediately when the Popup is closed.
+- `closed`: Emitted when the Popup is closed and the animation ends.
+
+```html
+<van-cell title="Listen to display events" is-link @click="show = true" />
+<van-popup
+  v-model:show="show"
+  position="bottom"
+  :style="{ height: '30%' }"
+  @open="showToast('open')"
+  @opened="showToast('opened')"
+  @close="showToast('close')"
+  @closed="showToast('closed')"
+/>
+```
+
+```js
+import { ref } from 'vue';
+import { showToast } from 'vant';
+
+export default {
+  setup() {
+    const show = ref(false);
+    return {
+      show,
+      showToast,
+    };
+  },
+};
+```
+
 ### Get Container
 
 Use `teleport` prop to specify mount location.
@@ -159,14 +244,14 @@ Use `teleport` prop to specify mount location.
 ### Events
 
 | Event | Description | Arguments |
-| ---------------- | ---------------------------------- | ------------------- |
+| --- | --- | --- |
 | click | Emitted when Popup is clicked | _event: MouseEvent_ |
 | click-overlay | Emitted when overlay is clicked | _event: MouseEvent_ |
 | click-close-icon | Emitted when close icon is clicked | _event: MouseEvent_ |
-| open             | Emitted when opening Popup         | -                   |
+| open | Emitted immediately when Popup is opened | - |
-| close            | Emitted when closing Popup         | -                   |
+| close | Emitted immediately when Popup is closed | - |
-| opened           | Emitted when Popup is opened       | -                   |
+| opened | Emitted when Popup is opened and the animation ends | - |
-| closed           | Emitted when Popup is closed       | -                   |
+| closed | Emitted when Popup is closed and the animation ends | - |
 
 ### Slots
 

packages/vant/src/popup/README.zh-CN.md

@@ -24,7 +24,7 @@ app.use(Popup);
 
 ```html
 <van-cell is-link @click="showPopup">展示弹出层</van-cell>
-<van-popup v-model:show="show">内容</van-popup>
+<van-popup v-model:show="show" :style="{ padding: '64px' }">内容</van-popup>
 ```
 
 ```js
@@ -111,14 +111,97 @@ export default {
 设置 `round` 属性后，弹窗会根据弹出位置添加不同的圆角样式。
 
 ```html
+<!-- 圆角弹窗（居中） -->
+<van-popup v-model:show="showCenter" round :style="{ padding: '64px' }" />
+
+<!-- 圆角弹窗（底部） -->
 <van-popup
-  v-model:show="show"
+  v-model:show="showBottom"
   round
   position="bottom"
   :style="{ height: '30%' }"
 />
 ```
 
+### 监听点击事件
+
+Popup 支持以下点击事件：
+
+- `click`: 点击弹出层时触发。
+- `click-overlay`: 点击遮罩层时触发。
+- `click-close-icon`: 点击关闭图标时触发。
+
+```html
+<van-cell title="监听点击事件" is-link @click="show = true" />
+<van-popup
+  v-model:show="show"
+  position="bottom"
+  :style="{ height: '30%' }"
+  closeable
+  @click-overlay="onClickOverlay"
+  @click-close-icon="onClickCloseIcon"
+/>
+```
+
+```js
+import { ref } from 'vue';
+import { showToast } from 'vant';
+
+export default {
+  setup() {
+    const show = ref(false);
+    const onClickOverlay = () => {
+      showToast('click-overlay');
+    };
+    const onClickCloseIcon = () => {
+      showToast('click-close-icon');
+    };
+    return {
+      show,
+      onClickOverlay,
+      onClickCloseIcon,
+    };
+  },
+};
+```
+
+### 监听显示事件
+
+当 Popup 被打开或关闭时，会触发以下事件：
+
+- `open`: 打开弹出层时立即触发。
+- `opened`: 打开弹出层且动画结束后触发。
+- `close`: 关闭弹出层时立即触发。
+- `closed`: 关闭弹出层且动画结束后触发。
+
+```html
+<van-cell title="监听显示事件" is-link @click="show = true" />
+<van-popup
+  v-model:show="show"
+  position="bottom"
+  :style="{ height: '30%' }"
+  @open="showToast('open')"
+  @opened="showToast('opened')"
+  @close="showToast('close')"
+  @closed="showToast('closed')"
+/>
+```
+
+```js
+import { ref } from 'vue';
+import { showToast } from 'vant';
+
+export default {
+  setup() {
+    const show = ref(false);
+    return {
+      show,
+      showToast,
+    };
+  },
+};
+```
+
 ### 指定挂载位置
 
 弹出层默认挂载到组件标签所在位置，可以通过 `teleport` 属性指定挂载位置。
@@ -167,8 +250,8 @@ export default {
 | click            | 点击弹出层时触发           | _event: MouseEvent_ |
 | click-overlay    | 点击遮罩层时触发           | _event: MouseEvent_ |
 | click-close-icon | 点击关闭图标时触发         | _event: MouseEvent_ |
-| open             | 打开弹出层时触发           | -                   |
+| open             | 打开弹出层时立即触发       | -                   |
-| close            | 关闭弹出层时触发           | -                   |
+| close            | 关闭弹出层时立即触发       | -                   |
 | opened           | 打开弹出层且动画结束后触发 | -                   |
 | closed           | 关闭弹出层且动画结束后触发 | -                   |
 

packages/vant/src/popup/demo/index.vue

@@ -3,6 +3,7 @@ import VanCell from '../../cell';
 import VanPopup from '..';
 import VanGrid from '../../grid';
 import VanGridItem from '../../grid-item';
+import { showToast } from '../../toast';
 import { ref } from 'vue';
 import { useTranslate } from '../../../docs/site';
 
@@ -16,9 +17,14 @@ const t = useTranslate({
     buttonRight: '右侧弹出',
     teleport: '指定挂载节点',
     roundCorner: '圆角弹窗',
+    roundCornerBottom: '圆角弹窗（底部）',
+    roundCornerCenter: '圆角弹窗（居中）',
     closeIcon: '关闭图标',
     customCloseIcon: '自定义图标',
     customIconPosition: '图标位置',
+    listenEvents: '事件监听',
+    clickEvents: '监听点击事件',
+    displayEvents: '监听显示事件',
   },
   'en-US': {
     position: 'Position',
@@ -29,9 +35,14 @@ const t = useTranslate({
     buttonRight: 'From Right',
     teleport: 'Get Container',
     roundCorner: 'Round Corner',
+    roundCornerBottom: 'Round Corner (bottom)',
+    roundCornerCenter: 'Round Corner (center)',
     closeIcon: 'Close Icon',
     customCloseIcon: 'Custom Icon',
     customIconPosition: 'Icon Position',
+    listenEvents: 'Listen To Events',
+    clickEvents: 'Listen To Click Events',
+    displayEvents: 'Listen To Display Events',
   },
 });
 
@@ -41,16 +52,19 @@ const showBottom = ref(false);
 const showLeft = ref(false);
 const showRight = ref(false);
 const showCloseIcon = ref(false);
-const showRoundCorner = ref(false);
+const showRoundCornerBottom = ref(false);
+const showRoundCornerCenter = ref(false);
 const showGetContainer = ref(false);
 const showCustomCloseIcon = ref(false);
 const showCustomIconPosition = ref(false);
+const showClickEvents = ref(false);
+const showDisplayEvents = ref(false);
 </script>
 
 <template>
   <demo-block card :title="t('basicUsage')">
     <van-cell :title="t('buttonBasic')" is-link @click="showBasic = true" />
-    <van-popup v-model:show="showBasic" :style="{ padding: '30px 50px' }">
+    <van-popup v-model:show="showBasic" :style="{ padding: '64px' }">
       {{ t('content') }}
     </van-popup>
   </demo-block>
@@ -138,24 +152,69 @@ const showCustomIconPosition = ref(false);
 
   <demo-block card :title="t('roundCorner')">
     <van-cell
-      :title="t('roundCorner')"
+      :title="t('roundCornerCenter')"
       is-link
-      @click="showRoundCorner = true"
+      @click="showRoundCornerCenter = true"
     />
     <van-popup
-      v-model:show="showRoundCorner"
+      v-model:show="showRoundCornerCenter"
+      round
+      position="center"
+      :style="{ padding: '64px' }"
+    >
+      {{ t('content') }}
+    </van-popup>
+
+    <van-cell
+      :title="t('roundCornerBottom')"
+      is-link
+      @click="showRoundCornerBottom = true"
+    />
+    <van-popup
+      v-model:show="showRoundCornerBottom"
       round
       position="bottom"
       :style="{ height: '30%' }"
     />
   </demo-block>
 
+  <demo-block card :title="t('listenEvents')">
+    <van-cell
+      :title="t('clickEvents')"
+      is-link
+      @click="showClickEvents = true"
+    />
+    <van-popup
+      v-model:show="showClickEvents"
+      position="bottom"
+      :style="{ height: '30%' }"
+      closeable
+      @click-overlay="showToast('click-overlay')"
+      @click-close-icon="showToast('click-close-icon')"
+    />
+
+    <van-cell
+      :title="t('displayEvents')"
+      is-link
+      @click="showDisplayEvents = true"
+    />
+    <van-popup
+      v-model:show="showDisplayEvents"
+      position="bottom"
+      :style="{ height: '30%' }"
+      @open="showToast('open')"
+      @opened="showToast('opened')"
+      @close="showToast('close')"
+      @closed="showToast('closed')"
+    />
+  </demo-block>
+
   <demo-block card :title="t('teleport')">
     <van-cell :title="t('teleport')" is-link @click="showGetContainer = true" />
     <van-popup
       v-model:show="showGetContainer"
       teleport="body"
-      :style="{ padding: '30px 50px' }"
+      :style="{ padding: '64px' }"
     />
   </demo-block>
 </template>

packages/vant/src/popup/test/__snapshots__/demo.spec.ts.snap

@@ -232,7 +232,87 @@ exports[`should render demo and match snapshot 1`] = `
   >
     <div class="van-cell__title">
       <span>
-        Round Corner
+        Round Corner (center)
+      </span>
+    </div>
+    <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
+    </i>
+  </div>
+  <transition-stub name="van-fade"
+                   appear="true"
+                   persisted="false"
+                   css="true"
+                   role="button"
+                   tabindex="0"
+  >
+  </transition-stub>
+  <transition-stub name="van-fade"
+                   appear="false"
+                   persisted="false"
+                   css="true"
+  >
+  </transition-stub>
+  <div class="van-cell van-cell--clickable"
+       role="button"
+       tabindex="0"
+  >
+    <div class="van-cell__title">
+      <span>
+        Round Corner (bottom)
+      </span>
+    </div>
+    <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
+    </i>
+  </div>
+  <transition-stub name="van-fade"
+                   appear="true"
+                   persisted="false"
+                   css="true"
+                   role="button"
+                   tabindex="0"
+  >
+  </transition-stub>
+  <transition-stub name="van-popup-slide-bottom"
+                   appear="false"
+                   persisted="false"
+                   css="true"
+  >
+  </transition-stub>
+</div>
+<div>
+  <div class="van-cell van-cell--clickable"
+       role="button"
+       tabindex="0"
+  >
+    <div class="van-cell__title">
+      <span>
+        Listen To Click Events
+      </span>
+    </div>
+    <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
+    </i>
+  </div>
+  <transition-stub name="van-fade"
+                   appear="true"
+                   persisted="false"
+                   css="true"
+                   role="button"
+                   tabindex="0"
+  >
+  </transition-stub>
+  <transition-stub name="van-popup-slide-bottom"
+                   appear="false"
+                   persisted="false"
+                   css="true"
+  >
+  </transition-stub>
+  <div class="van-cell van-cell--clickable"
+       role="button"
+       tabindex="0"
+  >
+    <div class="van-cell__title">
+      <span>
+        Listen To Display Events
       </span>
     </div>
     <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">