Vben Alert 轻量提示框

Alert 提供了一组纯 JavaScript 调用的轻量提示框能力，适合快速创建 alert、confirm、prompt 这类简单交互。

适用场景

Alert 与 Modal 的能力有部分重叠，但更适合临时确认、简单提示和轻量输入场景。复杂弹窗仍然建议使用 Vben Modal。

注意

通过 alert、confirm、prompt 动态创建的弹窗，在已经打开的情况下不支持 HMR 热更新。修改相关代码后，需要关闭后重新打开。

基础用法

使用 alert 创建只有确认按钮的提示框。

<script lang="ts" setup>
import { h } from 'vue';

import { alert, VbenButton } from '@vben/common-ui';

import { Result } from 'antdv-next';

function showAlert() {
  alert('This is an alert message');
}

function showIconAlert() {
  alert({
    content: 'This is an alert message with icon',
    icon: 'success',
  });
}

function showCustomAlert() {
  alert({
    buttonAlign: 'center',
    content: h(Result, {
      status: 'success',
      subTitle: '已成功创建订单。订单ID：2017182818828182881',
      title: '操作成功',
    }),
  });
}
</script>
<template>
  <div class="flex gap-4">
    <VbenButton @click="showAlert">Alert</VbenButton>
    <VbenButton @click="showIconAlert">Alert With Icon</VbenButton>
    <VbenButton @click="showCustomAlert">Alert With Custom Content</VbenButton>
  </div>
</template>

使用 confirm 创建带确认和取消按钮的提示框。

<script lang="ts" setup>
import { h, ref } from 'vue';

import { alert, confirm, VbenButton } from '@vben/common-ui';

import { Checkbox, message } from 'antdv-next';

function showConfirm() {
  confirm('This is an alert message')
    .then(() => {
      alert('Confirmed');
    })
    .catch(() => {
      alert('Canceled');
    });
}

function showIconConfirm() {
  confirm({
    content: 'This is an alert message with icon',
    icon: 'success',
  });
}

function showfooterConfirm() {
  const checked = ref(false);
  confirm({
    cancelText: '不要虾扯蛋',
    confirmText: '是的，我们都是NPC',
    content:
      '刚才发生的事情，为什么我似乎早就经历过一般？\n我甚至能在事情发生过程中潜意识里预知到接下来会发生什么。\n\n听起来挺玄乎的，你有过这种感觉吗？',
    footer: () =>
      h(
        Checkbox,
        {
          checked: checked.value,
          class: 'flex-1',
          'onUpdate:checked': (v) => (checked.value = v),
        },
        '不再提示',
      ),
    icon: 'question',
    title: '未解之谜',
  }).then(() => {
    if (checked.value) {
      message.success('我不会再拿这个问题烦你了');
    } else {
      message.info('下次还要继续问你哟');
    }
  });
}

function showAsyncConfirm() {
  confirm({
    beforeClose({ isConfirm }) {
      if (isConfirm) {
        // 这里可以执行一些异步操作。如果最终返回了false，将阻止关闭弹窗
        return new Promise((resolve) => setTimeout(resolve, 2000));
      }
    },
    content: 'This is an alert message with async confirm',
    icon: 'success',
  }).then(() => {
    alert('Confirmed');
  });
}
</script>
<template>
  <div class="flex gap-4">
    <VbenButton @click="showConfirm">Confirm</VbenButton>
    <VbenButton @click="showIconConfirm">Confirm With Icon</VbenButton>
    <VbenButton @click="showfooterConfirm">Confirm With Footer</VbenButton>
    <VbenButton @click="showAsyncConfirm">Async Confirm</VbenButton>
  </div>
</template>

使用 prompt 创建可接收用户输入的提示框。

<script lang="ts" setup>
import { h } from 'vue';

import { alert, prompt, useAlertContext, VbenButton } from '@vben/common-ui';

import { BadgeJapaneseYen } from '@lucide/vue';
import { Input, RadioGroup, Select } from 'antdv-next';

function showPrompt() {
  prompt({
    content: '请输入一些东西',
  })
    .then((val) => {
      alert(`已收到你的输入：${val}`);
    })
    .catch(() => {
      alert('Canceled');
    });
}

function showSlotsPrompt() {
  prompt({
    component: () => {
      // 获取弹窗上下文。注意：只能在setup或者函数式组件中调用
      const { doConfirm } = useAlertContext();
      return h(
        Input,
        {
          onKeydown(e: KeyboardEvent) {
            if (e.key === 'Enter') {
              e.preventDefault();
              // 调用弹窗提供的确认方法
              doConfirm();
            }
          },
          placeholder: '请输入',
          prefix: '充值金额：',
          type: 'number',
        },
        {
          addonAfter: () => h(BadgeJapaneseYen),
        },
      );
    },
    content:
      '此弹窗演示了如何使用自定义插槽，并且可以使用useAlertContext获取到弹窗的上下文。\n在输入框中按下回车键会触发确认操作。',
    icon: 'question',
    modelPropName: 'value',
  }).then((val) => {
    if (val) alert(`你输入的是${val}`);
  });
}

function showSelectPrompt() {
  prompt({
    component: Select,
    componentProps: {
      options: [
        { label: 'Option A', value: 'Option A' },
        { label: 'Option B', value: 'Option B' },
        { label: 'Option C', value: 'Option C' },
      ],
      placeholder: '请选择',
      // 弹窗会设置body的pointer-events为none，这回影响下拉框的点击事件
      popupClassName: 'pointer-events-auto',
    },
    content: '此弹窗演示了如何使用component传递自定义组件',
    icon: 'question',
    modelPropName: 'value',
  }).then((val) => {
    if (val) {
      alert(`你选择了${val}`);
    }
  });
}

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function showAsyncPrompt() {
  prompt({
    async beforeClose(scope) {
      if (scope.isConfirm) {
        if (scope.value) {
          // 模拟异步操作，如果不成功，可以返回false
          await sleep(2000);
        } else {
          alert('请选择一个选项');
          return false;
        }
      }
    },
    component: RadioGroup,
    componentProps: {
      class: 'flex flex-col',
      options: [
        { label: 'Option 1', value: 'option1' },
        { label: 'Option 2', value: 'option2' },
        { label: 'Option 3', value: 'option3' },
      ],
    },
    content: '选择一个选项后再点击[确认]',
    icon: 'question',
    modelPropName: 'value',
  }).then((val) => {
    alert(`${val} 已设置。`);
  });
}
</script>
<template>
  <div class="flex gap-4">
    <VbenButton @click="showPrompt">Prompt</VbenButton>
    <VbenButton @click="showSlotsPrompt"> Prompt With slots </VbenButton>
    <VbenButton @click="showSelectPrompt">Prompt With Select</VbenButton>
    <VbenButton @click="showAsyncPrompt">Prompt With Async</VbenButton>
  </div>
</template>

useAlertContext

当 content、footer 或 icon 使用的是自定义组件时，可以在这些组件内部通过 useAlertContext() 获取当前弹窗上下文，并主动触发确认或取消。

注意

useAlertContext 只能在 setup 或函数式组件中使用。:::

Methods

方法	描述	类型	版本要求
doConfirm	触发当前弹窗的确认操作	() => void	>5.5.4
doCancel	触发当前弹窗的取消操作	() => void	>5.5.4

类型说明

export type IconType = 'error' | 'info' | 'question' | 'success' | 'warning';

export type BeforeCloseScope = {
  isConfirm: boolean;
};

export type AlertProps = {
  beforeClose?: (
    scope: BeforeCloseScope,
  ) => boolean | Promise<boolean | undefined> | undefined;
  bordered?: boolean;
  buttonAlign?: 'center' | 'end' | 'start';
  cancelText?: string;
  centered?: boolean;
  confirmText?: string;
  containerClass?: string;
  content: Component | string;
  contentClass?: string;
  contentMasking?: boolean;
  footer?: Component | string;
  icon?: Component | IconType;
  overlayBlur?: number;
  showCancel?: boolean;
  title?: string;
};

export type PromptProps<T = any> = {
  beforeClose?: (scope: {
    isConfirm: boolean;
    value: T | undefined;
  }) => boolean | Promise<boolean | undefined> | undefined;
  component?: Component;
  componentProps?: Recordable<any>;
  componentSlots?:
    | (() => any)
    | Recordable<unknown>
    | VNode
    | VNodeArrayChildren;
  defaultValue?: T;
  modelPropName?: string;
} & Omit<AlertProps, 'beforeClose'>;

export function alert(options: AlertProps): Promise<void>;
export function alert(
  message: string,
  options?: Partial<AlertProps>,
): Promise<void>;
export function alert(
  message: string,
  title?: string,
  options?: Partial<AlertProps>,
): Promise<void>;

export async function prompt<T = any>(
  options: Omit<AlertProps, 'beforeClose'> & {
    beforeClose?: (
      scope: BeforeCloseScope & {
        value: T;
      },
    ) => boolean | Promise<boolean | undefined> | undefined;
    component?: Component;
    componentProps?: Recordable<any>;
    defaultValue?: T;
    modelPropName?: string;
  },
): Promise<T | undefined>;

贡献者

Claude Code

Netfan xingyu4j dream-weave Jin Mao

shabidadadi

页面历史

最后编辑于 4 天前

查看完整历史

0b86378-refactor: migrate lint toolchain to oxc locked pairing (#8481)

a7cd0ea-docs: fix style (#8410)

91a2e80-fix: 优化代码格式，合并类型声明

6b3bcee-docs(@vben/docs): sync component docs with current APIs

d18f561-docs: update alert and apiComponent docs (#5961)

bf7496f-feat: add useAlertContext for Alert component (#5947)

f0e9e55-feat: alert support customize footer (#5940)

71e8d12-fix: improve prompt component (#5879)

ecf518b-fix: alert beforeClose callback arguments fixed (#5845)

44138f5-feat: add preset alert, confirm, prompt components that can be simple called (#5843)