控制器实例 API

获取弹出层控制器实例。

类型

function usePopup(): IController

详细信息

作为增强型的 Vue 组合式工具函数，除了在组件内使用，还可以在任何非组件的地方使用。

唯一的前提是需要先调用 createPopupPlus() 方法创建一个核心实例，并将其安装到 app 实例上。

示例

组合式 API

// 在组件内使用
import { onMounted } from 'vue'
import { usePopup } from 'vue-popup-plus'

const popup = usePopup()

onMounted(() => {
	popup.render({
		component: () => import('./HelloPopup.vue'),
	})
})

router.ts

// 在独立文件中使用
import { usePopup } from 'vue-popup-plus'
import { createRouter, createWebHashHistory } from 'vue-router'

const popup = usePopup()

const router = createRouter({
	history: createWebHashHistory(),
	routes: [
		{ path: '/', component: () => import('./Home.vue') },
		{ path: '/login', component: () => import('./Login.vue') },
	],
})

router.beforeEach((to, from, next) => {
	if (!checkAuth() && to.path !== '/login') {
		popup.render({
			component: () => import('./HelloPopup.vue'),
		})
	} else {
		next()
	}
})

渲染一个弹出层，返回该弹出层实例 ID。

类型

function render(options: RenderOption): InstanceId

参数类型

type RenderOption<TComponent extends Component = Component> =
	RenderComponentOptions<TComponent> &
		RenderConfigOptions &
		RenderStyleOptions

type RenderComponentOptions<TComponent extends Component = Component> = {
	/**
	 * 弹出层渲染的视图组件
	 *
	 * - 要创建一个弹出层，这是唯一必要的参数。
	 * - 支持同步组件和异步组件，为了提高加载速度，优化构建体积，建议使用异步组件。
	 * - 对于异步组件，无需使用 `defineAsyncComponent` 方法定义组件，直接传入
	 *   ()=>import() 函数即可。
	 */
	component: TComponent
	/**
	 * 弹出层渲染的视图组件的 props
	 *
	 * - 除了组件的属性，还支持传入组件的事件监听器，事件监听器的名称需要以
	 *   `on` 开头，例如 `onClick` 、 `onInput` 等。
	 * - 会自动根据传入的组件进行类型推导，提供完善的类型提示
	 */
	componentProps?: ExtractComponentPropTypes<TComponent>
	/**
	 * 弹出层渲染之后的回调
	 */
	onMounted?: () => void
	/**
	 * 弹出层销毁之后的回调
	 *
	 * - 触发时会将 popup.destroy() 方法的负载参数 payload 作为参数传入
	 */
	onUnmounted?: (payload?: any) => void
}

type MaskDestroyHandler = (close: (payload?: any) => Promise<void>) => void

export type RenderConfigOptions = {
	/**
	 * 弹出层挂载的父元素
	 *
	 * - 不指定时，默认挂载到 body 元素下
	 */
	appendTo?: Element | string
	/**
	 * 弹出层是否显示遮罩层
	 *
	 * - 默认值为 `true`
	 */
	mask?: boolean
	/**
	 * 点击遮罩层是否销毁弹出层
	 *
	 * - 默认值为 `false` ，点击遮罩层不会销毁弹出层
	 * - 传入 `true` ，点击遮罩层会销毁弹出层
	 * - 可传入一个函数，该函数接收一个 `(payload?: any) => Promise<void>`
	 *   类型的函数作为参数，执行后将销毁弹出层，可传入销毁携带的负载参数，返回的
	 *   `Promise` 对象会在弹出层销毁动画完成后 `resolve()` 。
	 * - 仅在 `mask` 参数为 `true` 时有效
	 *
	 * @since 1.6.0
	 */
	maskDestroy?: boolean | MaskDestroyHandler
	/**
	 * @deprecated 1.6.0
	 * 请使用 {@link maskDestroy} 作为代替
	 *
	 * 点击遮罩层是否关闭弹出层
	 *
	 * - 默认值为 false
	 * - 仅在 `mask` 参数为 `true` 时有效
	 */
	maskClickClose?: boolean
	/**
	 * 弹出层是否禁用窗口滚动
	 *
	 * - 默认值为 `true`
	 */
	disableScroll?: boolean
}
type MaskDestroyHandler = (close: (payload?: any) => Promise<void>) => void

type RenderConfigOptions = {
	/**
	 * 弹出层挂载的父元素
	 *
	 * - 不指定时，默认挂载到 body 元素下
	 */
	appendTo?: Element | string
	/**
	 * 弹出层是否显示遮罩层
	 *
	 * - 默认值为 `true`
	 */
	mask?: boolean
	/**
	 * 点击遮罩层是否销毁弹出层
	 *
	 * - 默认值为 `false` ，点击遮罩层不会销毁弹出层
	 * - 传入 `true` ，点击遮罩层将销毁弹出层
	 * - 可传入一个函数，该函数接收一个 `(payload?: any) => Promise<void>`
	 *   类型的函数作为参数，执行后将销毁弹出层，可传入销毁携带的负载参数，返回的
	 *   `Promise` 对象会在弹出层销毁动画完成后 `resolve()` 。
	 * - 仅在 `mask` 参数为 `true` 时有效
	 *
	 * @since 1.6.0
	 */
	maskDestroy?: boolean | MaskDestroyHandler
	/**
	 * 弹出层是否禁用窗口滚动
	 *
	 * - 默认值为 `true`
	 */
	disableScroll?: boolean
}

type RenderStyleOptions = {
	/**
	 * 弹出层宽度
	 *
	 * - 默认为 `'auto'` ，即自适应
	 * - 使用 number 类型时，单位为 px
	 * - 使用 string 类型时，支持一切 css 合法值
	 *
	 * @example
	 * width: 300
	 * width: '300px'
	 * width: '50%'
	 * width: 'inherit'
	 */
	width?: string | number
	/**
	 * 弹出层最大宽度
	 *
	 * - 默认为 `'auto'` ，即自适应
	 * - 使用 number 类型时，单位为 px
	 * - 使用 string 类型时，支持一切 css 合法值
	 *
	 * @example
	 * maxWidth: 300
	 * maxWidth: '300px'
	 * maxWidth: '50%'
	 * maxWidth: 'inherit'
	 */
	maxWidth?: string | number
	/**
	 * 弹出层最小宽度
	 *
	 * - 默认值为 `'auto'` ，即自适应
	 * - 使用 number 类型时，单位为 px
	 * - 使用 string 类型时，支持一切 css 合法值
	 *
	 * @example
	 * minWidth: 300
	 * minWidth: '300px'
	 * minWidth: '50%'
	 * minWidth: 'inherit'
	 */
	minWidth?: string | number
	/**
	 * 弹出层高度
	 *
	 * - 默认值为 `'auto'` ，即自适应
	 * - 使用 number 类型时，单位为 px
	 * - 使用 string 类型时，支持一切 css 合法值
	 *
	 * @example
	 * height: 300
	 * height: '300px'
	 * height: '50%'
	 * height: 'inherit'
	 */
	height?: string | number
	/**
	 * 弹出层最大高度
	 *
	 * - 默认值为 `'auto'` ，即自适应
	 * - 使用 number 类型时，单位为 px
	 * - 使用 string 类型时，支持一切 css 合法值
	 *
	 * @example
	 * maxHeight: 300
	 * maxHeight: '300px'
	 * maxHeight: '50%'
	 * maxHeight: 'inherit'
	 */
	maxHeight?: string | number
	/**
	 * 弹出层最小高度
	 *
	 * - 默认值为 `'auto'` ，即自适应
	 * - 使用 number 类型时，单位为 px
	 * - 使用 string 类型时，支持一切 css 合法值
	 *
	 * @example
	 * minHeight: 300
	 * minHeight: '300px'
	 * minHeight: '50%'
	 * minHeight: 'inherit'
	 */
	minHeight?: string | number
	/**
	 * 弹出层位置
	 *
	 * - 默认为 `'center'` ，即居中显示
	 * - 更多位置请查看 {@link Placement}
	 *
	 * @since 1.5.0
	 */
	placement?: Placement
	/**
	 * 弹出层视图动画类型
	 *
	 * - 默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出
	 * - 更多动画类型请查看 {@link IAnimations}
	 */
	viewAnimation?: Animation
	/**
	 * 弹出层视图水平偏移量
	 *
	 * - 默认为 0 ，单位为 px
	 *
	 * @since 1.1.0
	 */
	viewTranslateX?: number
	/**
	 * 弹出层视图垂直偏移量
	 *
	 * - 默认为 0 ，单位为 px
	 *
	 * @since 1.1.0
	 */
	viewTranslateY?: number
	/**
	 * 弹出层视图是否允许超出窗口边界
	 *
	 * - 默认为 false
	 */
	viewTranslateOverflow?: boolean
	/**
	 * 弹出层遮罩动画类型
	 *
	 * - 默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出
	 * - 更多动画类型请查看 {@link IAnimations}
	 */
	maskAnimation?: Animation
	/**
	 * 弹出层遮罩是否启用模糊效果
	 *
	 * - 默认为 `false`
	 * - 仅在 `mask` 参数为 `true` 时有效
	 *
	 * @since 1.3.0
	 */
	maskBlur?: boolean
	/**
	 * 弹出层遮罩是否启用透明效果
	 *
	 * - 默认为 `false`
	 * - 优先级高于 `maskBlur`
	 * - 仅在 `mask` 参数为 `true` 时有效
	 *
	 * @since 1.6.0
	 */
	maskTransparent?: boolean
	/**
	 * 弹出层动画时长
	 *
	 * - 默认为 `100` ，单位为 毫秒
	 */
	animationDuration?: number
	/**
	 * 弹出层 zIndex
	 *
	 * - 若不设置，则使用全局递增的 zIndex 值
	 */
	zIndex?: number
}

// 弹出层位置
type Placement =
	| 'left-top'
	| 'left'
	| 'left-bottom'
	| 'top'
	| 'center'
	| 'bottom'
	| 'right-top'
	| 'right'
	| 'right-bottom'

详细信息

component 是唯一的必填参数，支持同步组件和异步组件。建议使用异步组件，当弹出层未渲染时，将不会加载其代码，从而优化加载速度和构建体积。

viewAnimation 和 maskAnimation 仅支持动画类型常量 POPUP_ANIMATIONS 中提供的动画类型，具体可以参考核心 API - 常量 POPUP_ANIMATIONS。

示例

import HelloPopup from './HelloPopup.vue'

// 同步组件
popup.render({
	component: HelloPopup,
})

// 异步组件
popup.render({
	component: () => import('./HelloPopup.vue'),
})

类型

function update(instanceId: InstanceId, options: UpdateOption): void

参数类型

type UpdateOption = {
	/**
	 * 弹出层宽度
	 *
	 * - 默认为 auto，即自适应，支持 string 和 number 类型，string
	 *   类型更为灵活，number 类型方便计算
	 */
	width?: string | number
	/**
	 * 弹出层最大宽度
	 *
	 * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
	 *   类型方便计算
	 */
	maxWidth?: string | number
	/**
	 * 弹出层最小宽度
	 *
	 * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
	 *   类型方便计算
	 */
	minWidth?: string | number
	/**
	 * 弹出层高度
	 *
	 * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
	 *   类型方便计算
	 */
	height?: string | number
	/**
	 * 弹出层最大高度
	 *
	 * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
	 *   类型方便计算
	 */
	maxHeight?: string | number
	/**
	 * 弹出层最小高度
	 *
	 * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
	 *   类型方便计算
	 */
	minHeight?: string | number
	/**
	 * 弹出层位置
	 *
	 * - 默认为 center ，即居中
	 *
	 * @since 1.5.0
	 */
	placement?: Placement
	/**
	 * 弹出层视图动画类型
	 *
	 * - 默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出
	 */
	viewAnimation?: Animation
	/**
	 * 弹出层视图水平偏移量
	 *
	 * - 默认为 0 ，单位为 px
	 *
	 * @since 1.1.0
	 */
	viewTranslateX?: number
	/**
	 * 弹出层视图垂直偏移量
	 *
	 * - 默认为 0 ，单位为 px
	 *
	 * @since 1.1.0
	 */
	viewTranslateY?: number
	/**
	 * 弹出层视图是否允许超出窗口边界
	 *
	 * - 默认为 false
	 */
	viewTranslateOverflow?: boolean
	/**
	 * 弹出层遮罩动画类型
	 *
	 * - 默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出
	 */
	maskAnimation?: Animation
	/**
	 * 弹出层遮罩是否启用模糊效果
	 *
	 * - 默认为 true
	 *
	 * @since 1.3.0
	 */
	maskBlur?: boolean
	/**
	 * 弹出层动画时长
	 *
	 * - 默认为 100 ，单位为 毫秒
	 */
	animationDuration?: number
	/**
	 * 弹出层 zIndex
	 *
	 * - 若不设置，则使用全局递增的 zIndex 值
	 */
	zIndex?: number
}

详细信息

第一个参数是弹出层实例 ID，第二个参数是更新选项。

只允许更新和样式有关的渲染选项，因为其他选项会在弹出层渲染时确定，无法动态更新。

示例

popup.update(instanceId, {
	width: '50%',
})

类型

function destroy(instanceId: InstanceId, payload?: any): void

详细信息

第一个参数是弹出层实例 ID，第二个参数是可选的自定义数据，如果渲染弹出层时传入了 onUnmounted 回调函数，则会将该数据作为参数传递给回调函数。

示例

const instanceId = popup.render({
	component: () => import('./HelloPopup.vue'),
	onUnmounted: (payload) => {
		// 弹出层销毁时将获取自定义数据
		console.log(payload) // 'This is a custom payload'
	},
})

// 销毁弹出层时传递自定义数据
popup.destroy(instanceId, 'This is a custom payload')

类型

function getComputedStyle(instanceId: InstanceId): ComputedStyle | null

type ComputedStyle = ComputedRef<{
	/**
	 * 弹出层的宽度
	 */
	width: number
	/**
	 * 弹出层的高度
	 */
	height: number
	/**
	 * 弹出层的 z-index
	 */
	zIndex: number
	/**
	 * 弹出层的 translateX
	 */
	translateX: number
	/**
	 * 弹出层的 translateY
	 */
	translateY: number
}>

详细信息

传入弹出层的实例 ID，当该弹出层视图已挂载时，返回该弹出层视图的计算样式。否则返回 null。

计算样式本质是一个 Vue 的计算属性。

示例

// 视图组件内
import { usePopup, usePopupInstanceId } from 'vue-popup-plus'

const popup = usePopup()
const instanceId = usePopupInstanceId()

function getComputedStyle() {
	const computedStyle = popup.getComputedStyle(instanceId)

	console.log(computedStyle?.value.width) // 弹出层的宽度
}

类型

function use(plugin: Plugin, options?: any): void

详细信息

第一个参数是插件实例，第二个参数是可选的插件注册选项。

插件实例是由 definePlugin() 函数所定义的插件实例。

插件注册选项由插件开发者定义，具体需要参考对应的插件文档。

示例

import { createPopup } from 'vue-popup-plus'
import { presetPlugin } from 'vue-popup-plus-plugin-preset'

const popup = createPopup()

popup.use(presetPlugin)

类型

const version: string

详细信息

Vue Popup Plus 版本号，格式为 x.y.z，其中 x 为主版本号，y 为次版本号，z 为修订版本号。

主版本号一般不会改变。

次版本号更新意味着包含存在兼容性改动，需要注意升级时的影响。

修订版本号更新意味着只包含 bug 修复和性能优化，不会引入新的功能或兼容性问题。

示例

import { usePopup } from 'vue-popup-plus'

const popup = usePopup()

console.log(popup.version)

控制器实例 API

类型

详细信息

示例

类型

参数类型

详细信息

示例

相关参考

类型

参数类型

详细信息

示例

相关参考

类型

详细信息

示例

相关参考

类型

详细信息

示例

相关参考

类型

详细信息

示例

相关参考

类型

详细信息

示例

相关参考

控制器实例 API ​

usePopup() ​

类型 ​

详细信息 ​

示例 ​

popup.render() ​

类型 ​

参数类型 ​

详细信息 ​

示例 ​

相关参考 ​

popup.update() ​

类型 ​

参数类型 ​

详细信息 ​

示例 ​

相关参考 ​

popup.destroy() ​

类型 ​

详细信息 ​

示例 ​

相关参考 ​

popup.getComputedStyle() 1.6.0+ ​

类型 ​

详细信息 ​

示例 ​

相关参考 ​

popup.use() 1.6.0- ​

类型 ​

详细信息 ​

示例 ​

相关参考 ​

popup.version ​

类型 ​

详细信息 ​

示例 ​

相关参考 ​

控制器实例 API

usePopup()

类型

详细信息

示例

popup.render()

类型

参数类型

详细信息

示例

相关参考

popup.update()

类型

参数类型

详细信息

示例

相关参考

popup.destroy()

类型

详细信息

示例

相关参考

popup.getComputedStyle() 1.6.0+

类型

详细信息

示例

相关参考

popup.use() 1.6.0-

类型

详细信息

示例

相关参考

popup.version

类型

详细信息

示例

相关参考