Vue Nice Modal

@ebay/nice-modal-react Vue 版本。

vue-nice-modal 是一个工具库,可以将 Vue.js 的 modal 组件转换为基于 Promise 的 API。

支持 Vue 2.x,通过 vue-demi。

English | 简体中文

一个优雅的 Vue 模态框状态管理方案，支持 Vue 2 和 Vue 3。

特性

• 🎯 简单直观的 API
• 🔄 基于 Promise 的模态框操作
• 🎨 框架无关 - 可配合任何 UI 库使用
• ⚡️ 轻量级，零依赖
• 🔌 支持 Vue 2 和 Vue 3
• 📦 完整的 TypeScript 支持

安装

1# npm
2npm install vue-nice-modal
3
4# pnpm
5pnpm add vue-nice-modal

使用方式

1. Provider 包裹应用

1<!-- App.vue -->
2<template>
3  <NiceModalProvider>
4    <router-view />
5  </NiceModalProvider>
6</template>
7
8<script setup>
9  import { Provider as NiceModalProvider } from 'vue-nice-modal';
10</script>

2. 创建模态框组件

1<!-- my-modal.vue -->
2<template>
3  <van-dialog
4    show-cancel-button
5    :value="modal.visible.value"
6    :close-on-click-overlay="false"
7    :title="title"
8    :message="content"
9    @closed="modal.remove"
10    @confirm="handleConfirm"
11    @cancel="handleCancel"
12  />
13</template>
14
15<script setup>
16  import { useModal } from 'vue-nice-modal';
17
18  const modal = useModal();
19  defineProps(['title', 'content']);
20
21  const handleCancel = () => {
22    modal.reject('cancel');
23    modal.hide();
24  };
25
26  const handleConfirm = () => {
27    modal.resolve('confirm');
28    modal.hide();
29  };
30</script>

可与任何 UI 库配合使用，如 element-ui

1<!-- my-modal.vue -->
2<template>
3  <el-dialog
4    :title="title"
5    :visible="modal.visible.value"
6    append-to-body
7    @closed="modal.remove"
8  >
9    <span>{{ content }}</span>
10    <span slot="footer" class="dialog-footer">
11      <el-button @click="handleCancel">取 消</el-button>
12      <el-button type="primary" @click="handleConfirm">确 定</el-button>
13    </span>
14  </el-dialog>
15</template>

使用 NiceModal.create 创建模态框高阶组件

1// my-modal.js
2import NiceModal from 'vue-nice-modal';
3
4import _MyModal from './my-modal.vue';
5
6export const MyModal = NiceModal.create(_MyModal);

3. 使用模态框

3.1 基础用法 - 直接使用组件

1const showModal = async () => {
2  try {
3    const res = await NiceModal.show(MyModal, {
4      title: '标题',
5      content: '内容',
6    });
7    console.log('结果:', res);
8  } catch (error) {
9    console.log('取消:', error);
10  }
11};

3.2 声明式用法 - 通过 ID 引用已声明的模态框

可继承声明处上下文

1<template>
2  <MyModal id="my-modal" />
3</template>
4
5<script setup>
6  const showModal = async () => {
7    try {
8      const res = await NiceModal.show('my-modal', {
9        title: '标题',
10        content: '内容',
11      });
12      console.log('结果:', res);
13    } catch (error) {
14      console.log('取消:', error);
15    }
16  };
17</script>

3.3 Hook 用法 - 使用 useModal 组合式 API

1const modal = NiceModal.useModal(MyModal);
2
3const showModal = async () => {
4  try {
5    const res = await modal.show({
6      title: '标题',
7      content: '内容',
8    });
9    console.log('结果:', res);
10  } catch (error) {
11    console.log('取消:', error);
12  }
13};

3.4 注册用法 - 通过注册后使用 ID 调用

1// 预先注册模态框
2NiceModal.register('register-modal', MyModal);
3
4const showModal = async () => {
5  try {
6    const res = await NiceModal.show('register-modal', {
7      title: '标题',
8      content: '内容',
9    });
10    console.log('结果:', res);
11  } catch (error) {
12    console.log('取消:', error);
13  }
14};

API 参考

组件

NiceModal.Provider

模态框容器组件，需要包裹在应用最外层。

NiceModal.create(Component)

高阶组件，用于创建模态框组件。

方法

show(modalId, args?)

显示模态框，支持传入参数。

• modalId: 模态框 ID 或组件
• args: 传递给模态框的参数
• 返回: Promise

hide(modalId)

隐藏模态框。

• modalId: 模态框 ID 或组件
• 返回: Promise

remove(modalId)

从 DOM 中移除模态框。

• modalId: 模态框 ID 或组件

register(id, component, props?)

注册模态框组件。

• id: 模态框 ID
• component: 模态框组件
• props: 默认 props

unregister(id)

注销模态框组件。

• id: 模态框 ID

Hook

useModal(modal?, args?)

返回值:

• id: 模态框 ID
• args: 模态框参数
• visible: 可见状态
• show(args?): 显示模态框
• hide(): 隐藏模态框
• remove(): 移除模态框
• resolve(value): 解析模态框 Promise
• reject(reason): 拒绝模态框 Promise
• resolveHide(value): 解析隐藏 Promise

类型支持

本包提供完整的 TypeScript 类型声明，支持 props 和参数的类型推导。

构建产物

• 支持 Tree Shaking
• 提供 ESM/CJS 两种格式

1dist/
2  ├── esm/           # ES Module 格式
3  └── lib/           # CommonJS 格式

浏览器兼容性

• iOS >= 9
• Android >= 4.4
• 现代浏览器的最新两个版本

License

MIT