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

2025-04-06 03:57:59 +08:00 · 2023-01-02 12:33:51 +08:00 · 2023-01-02 12:33:51 +08:00 · aa7cd12fcf
commit aa7cd12fcf
parent 4e3c32bc2b
4 changed files with 328 additions and 21 deletions
--- a/packages/vant/src/popup/README.md
+++ b/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.
@ -158,15 +243,15 @@ 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_ |
+| 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         | -                   |
-| close            | Emitted when closing Popup         | -                   |
-| opened           | Emitted when Popup is opened       | -                   |
-| closed           | Emitted when Popup is closed       | -                   |
+| open | Emitted immediately when Popup is opened | - |
+| close | Emitted immediately when Popup is closed | - |
+| opened | Emitted when Popup is opened and the animation ends | - |
+| closed | Emitted when Popup is closed and the animation ends | - |

 ### Slots

--- a/packages/vant/src/popup/README.zh-CN.md
+++ b/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             | 打开弹出层时触发           | -                   |
-| close            | 关闭弹出层时触发           | -                   |
+| open             | 打开弹出层时立即触发       | -                   |
+| close            | 关闭弹出层时立即触发       | -                   |
 | opened           | 打开弹出层且动画结束后触发 | -                   |
 | closed           | 关闭弹出层且动画结束后触发 | -                   |

--- a/packages/vant/src/popup/demo/index.vue
+++ b/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>
--- a/packages/vant/src/popup/test/snapshots/demo.spec.ts.snap
+++ b/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">