overseas/uni_modules/uni-popup/readme.md

296 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

## Popup 弹出层
> **组件名uni-popup**
> 代码块: `uPopup`
> 关联组件:`uni-popup-dialog`,`uni-popup-message`,`uni-popup-share`,`uni-transition`
弹出层组件,在应用中弹出一个消息提示窗口、提示框等
> **注意事项**
> 为了避免错误使用,给大家带来不好的开发体验,请在使用组件前仔细阅读下面的注意事项,可以帮你避免一些错误。
> - 组件需要依赖 `sass` 插件 ,请自行手动安装
> - `uni-popup-message` 、 `uni-popup-dialog` 等扩展ui组件需要和 `uni-popup` 配套使用,暂不支持单独使用
> - `nvue` 中使用 `uni-popup` 时,尽量将组件置于其他元素后面,避免出现层级问题
> - `uni-popup` 并不能完全阻止页面滚动,可在打开 `uni-popup` 的时候手动去做一些处理,禁止页面滚动
> - 如果想在页面渲染完毕后就打开 `uni-popup` ,请在 `onReady` 或 `mounted` 生命周期内调用,确保组件渲染完毕
> - 在微信小程序开发者工具中启用真机调试popup 会延时出现,是因为 setTimeout 在真机调试中的延时问题导致的,预览和发布小程序不会出现此问题
> - 使用 `npm` 方式引入组件,如果确认引用正确,但是提示未注册组件或显示不正常,请尝试重新编译项目
> - `uni-popup` 中尽量不要使用 `scroll-view` 嵌套过多的内容,可能会影响组件的性能,导致组件无法打开或者打开卡顿
> - `uni-popup` 不会覆盖原生 tabbar 和原生导航栏
> - 组件支持 nvue ,需要在 `manifest.json > app-plus` 节点下配置 `"nvueStyleCompiler" : "uni-app"`
> - 如使用过程中有任何问题或者您对uni-ui有一些好的建议欢迎加入 uni-ui 交流群871950839
### 安装方式
本组件符合[easycom](https://uniapp.dcloud.io/collocation/pages?id=easycom)规范,`HBuilderX 2.5.5`起,只需将本组件导入项目,在页面`template`中即可直接使用,无需在页面中`import`和注册`components`。
如需通过`npm`方式使用`uni-ui`组件,另见文档:[https://ext.dcloud.net.cn/plugin?id=55](https://ext.dcloud.net.cn/plugin?id=55)
### 基本用法
**示例**
```html
<button @click="open">打开弹窗</button>
<uni-popup ref="popup" type="bottom">底部弹出 Popup</uni-popup>
```
```javascript
export default {
methods:{
open(){
// 通过组件定义的ref调用uni-popup方法 ,如果传入参数 type 属性将失效 ,仅支持 ['top','left','bottom','right','center']
this.$refs.popup.open('top')
}
}
}
```
### 设置主窗口背景色
在大多数场景下,并不需要设置 `background-color` 属性,因为`uni-popup`的主窗口默认是透明的,在向里面插入内容的时候 ,样式完全交由用户定制,如果设置了背景色 ,例如 `uni-popup-dialog` 中的圆角就很难去实现,不设置背景色,更适合用户去自由发挥。
而也有特例,需要我们主动去设置背景色,例如 `type = 'bottom'` 的时候 ,在异型屏中遇到了底部安全区问题(如 iphone 11因为 `uni-popup`的主要内容避开了安全区(设置`safe-area:true`),导致底部的颜色我们无法自定义,这时候使用 `background-color` 就可以解决这个问题。
**示例**
```html
<button @click="open">打开弹窗</button>
<uni-popup ref="popup" type="bottom" background-color="#fff">底部弹出 Popup</uni-popup>
```
### 禁用打开动画
在某些场景 ,可能不希望弹层有动画效果 ,只需要将 `animation` 属性设置为 `false` 即可以关闭动画。
**示例**
```html
<button @click="open">打开弹窗</button>
<uni-popup ref="popup" type="center" :animation="false">中间弹出 Popup</uni-popup>
```
### 禁用点击遮罩关闭
默认情况下,点击遮罩会自动关闭`uni-popup`,如不想点击关闭,只需将`mask-click`设置为`false`,这时候要关闭`uni-popup`,只能手动调用 `close` 方法。
**示例**
```html
<button @click="open">打开弹窗</button>
<uni-popup ref="popup" :mask-click="false">
<text>Popup</text>
<button @click="close">关闭</button>
</uni-popup>
```
```javascript
export default {
data() {
return {}
},
onReady() {},
methods: {
open() {
this.$refs.popup.open('top')
},
close() {
this.$refs.popup.close()
}
}
}
```
## API
### Popup Props
|属性名|类型|默认值|说明|
|:-:|:-:|:-:|:-:|
|animation|Boolean|true|是否开启动画|
|type|String|'center'|弹出方式|
|mask-click|Boolean|true|蒙版点击是否关闭弹窗|
|background-color|String|'none'|主窗口背景色|
|safe-area|Boolean|true|是否适配底部安全区|
#### Type Options
|属性名|说明|
|:-:| :-:|
|top|顶部弹出 |
|center|居中弹出|
|bottom|底部弹出|
|left|左侧弹出|
|right|右侧弹出|
|message|预置样式 :消息提示|
|dialog|预置样式 :对话框|
|share|预置样式 :底部弹出分享示例 |
### Popup Methods
|方法称名 |说明|参数|
|:-:|:-:|:-:|
|open|打开弹出层|open(String:type) ,如果参数可代替 type 属性|
|close|关闭弹出层 |-|
### Popup Events
|事件称名|说明|返回值|
|:-:|:-:|:-:|
|change|组件状态发生变化触发|e={show: truefalse,type:当前模式}|
|maskClick|点击遮罩层触发|-|
## 扩展组件说明
`uni-popup` 其实并没有任何样式,只提供基础的动画效果,给用户一个弹出层解决方案,仅仅是这样并不能满足开发需求,所以我们提供了三种基础扩展样式
### uni-popup-message 提示信息
`uni-popup` 的`type`属性改为 `message`,并引入对应组件即可使用消息提示 *该组件不支持单独使用*
**示例**
```html
<uni-popup ref="popup" type="message">
<uni-popup-message type="success" message="成功消息" :duration="2000"></uni-popup-message>
</uni-popup>
```
### PopupMessage Props
|属性名|类型|默认值|说明|
|:-:|:-:|:-:|:-:|
|type|String|success|消息提示主题|
|message|String|-|消息提示文字|
|duration|Number|3000|消息显示时间超过显示时间组件自动关闭设置为0 将不会关闭,需手动调用 close 方法关闭|
#### Type Options
|属性名|说明|
|:-:| :-:|
|success|成功 |
|warn|警告|
|error|失败|
|info|消息|
### PopupMessage Slots
|名称|说明|
|:-:|:-:|
|default|消息内容,会覆盖 message 属性|
### uni-popup-dialog 对话框
`uni-popup` 的`type`属性改为 `dialog`,并引入对应组件即可使用对话框 *该组件不支持单独使用*
**示例**
```html
<button @click="open">打开弹窗</button>
<uni-popup ref="popup" type="dialog">
<uni-popup-dialog mode="input" message="成功消息" :duration="2000" :before-close="true" @close="close" @confirm="confirm"></uni-popup-dialog>
</uni-popup>
```
```javascript
export default {
methods: {
open() {
this.$refs.popup.open()
},
/**
* 点击取消按钮触发
* @param {Object} done
*/
close() {
// TODO 做一些其他的事情before-close 为true的情况下手动执行 close 才会关闭对话框
// ...
this.$refs.popup.close()
},
/**
* 点击确认按钮触发
* @param {Object} done
* @param {Object} value
*/
confirm(value) {
// 输入框的值
console.log(value)
// TODO 做一些其他的事情,手动执行 close 才会关闭对话框
// ...
this.$refs.popup.close()
}
}
}
```
### PopupDialog Props
|属性名|类型|默认值|说明|
|:-:|:-:|:-:|:-:|
|type|String|success|对话框标题主题,可选值: success/warn/info/error|
|mode|String|base| 对话框模式可选值base提示对话框/input可输入对话框|
|title|String|-|对话框标题|
|content|String|-|对话框内容base模式下生效|
|value| String\Number|-|输入框默认值input模式下生效|
|placeholder|String|-|输入框提示文字input模式下生效|
|before-close|Boolean|false | 是否拦截按钮事件如为true则不会关闭对话框关闭需要手动执行 uni-popup 的 close 方法|
#### PopupDialog Events
|事件称名 |说明|返回值|
|:-:|:-:|:-:|
|close|点击dialog取消按钮触发|-|
|confirm|点击dialog确定按钮触发|e={value:input模式下输入框的值}|
### PopupDialog Slots
|名称|说明|
|:-:|:-:|
|default|自定义内容,回覆盖原有的内容显示|
### uni-popup-share 分享示例
分享示例,不作为最终可使用的组件,只做为样式组件,供用户自行修改,`后续的开发计划是实现实际的分享逻辑,参数可配置`。
`uni-popup``type` 属性改为 `share`,并引入对应组件即可使用 *该组件不支持单独使用*
**示例**
```html
<uni-popup ref="popup" type="share">
<uni-popup-share title="分享到" @select="select"></uni-popup-share>
</uni-popup>
```
### PopupShare Props
|属性名|类型|默认值|说明|
|:-:|:-:|:-:| :-: |
|title|String|-|分享弹窗标题|
|before-close|Boolean|false | 是否拦截按钮事件如为true则不会关闭对话框关闭需要手动执行 uni-popup 的 close 方法|
### PopupShare Events
|事件称名|说明|返回值|
|:-:|:-:|:-:|
|select|选择触发|e = {item,index}:所选参数|
**Tips**
- share 分享组件,只是作为一个扩展示例,如果需要修改数据源,请到组件内修改
## 帮助
在使用中如遇到无法解决的问题,请提 [Issues](https://github.com/dcloudio/uni-ui/issues) 给我们。
## 组件示例
点击查看:[https://hellouniapp.dcloud.net.cn/pages/extUI/popup/popup](https://hellouniapp.dcloud.net.cn/pages/extUI/popup/popup)