You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
294 lines
10 KiB
294 lines
10 KiB
|
|
|
|
## Popup 弹出层
|
|
> 代码块： `uPopup`
|
|
> 关联组件：`uni-transition`,`uni-popup-dialog`,`uni-popup-message`,`uni-popup-share`
|
|
|
|
|
|
弹出层组件，在应用中弹出一个消息提示窗口、提示框等
|
|
|
|
|
|
> 为了避免错误使用，给大家带来不好的开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。
|
|
> - 组件需要依赖 `sass` 插件 ，请自行手动安装
|
|
> - `uni-popup-message` 、 `uni-popup-dialog` 等扩展ui组件，需要和 `uni-popup` 配套使用，暂不支持单独使用
|
|
> - `nvue` 中使用 `uni-popup` 时，尽量将组件置于其他元素后面，避免出现层级问题
|
|
> - `uni-popup` 并不能完全阻止页面滚动，可在打开 `uni-popup` 的时候手动去做一些处理，禁止页面滚动
|
|
> - 如果需要在子扩展组件内关闭 `uni-popup` ，请使用扩展（provide/inject）方式，其他方式可能会出现不可预知问题
|
|
> - 如果想在页面渲染完毕后就打开 `uni-popup` ，请在 `onReady` 或 `mounted` 生命周期内调用，确保组件渲染完毕
|
|
> - 在微信小程序开发者工具中，启用真机调试，popup 会延时出现，是因为 setTimeout 在真机调试中的延时问题导致的，预览和发布小程序不会出现此问题
|
|
> - 使用 `npm` 方式引入组件，如果确认引用正确，但是提示未注册组件或显示不正常，请尝试重新编译项目
|
|
> - `uni-popup` 中尽量不要使用 `scroll-view` 嵌套过多的内容，可能会影响组件的性能，导致组件无法打开或者打开卡顿
|
|
> - `uni-popup` 不会覆盖原生 tabbar 和原生导航栏
|
|
|
|
|
|
|
|
### 安装方式
|
|
|
|
本组件符合[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方法
|
|
this.$refs.popup.open()
|
|
}
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
## API
|
|
|
|
### Popup Props
|
|
|
|
| 属性名 | 类型 | 默认值 | 说明 |
|
|
| :-: | :-: | :-: | :-: |
|
|
| animation | Boolean |true | 是否开启动画 |
|
|
| type | String |center | 弹出方式 |
|
|
| maskClick | Boolean |true | 蒙版点击是否关闭弹窗 |
|
|
|
|
#### Type Options
|
|
|
|
| 属性名 | 说明 |
|
|
| :-: | :-: |
|
|
| top | 顶部弹出 |
|
|
| center | 居中弹出 |
|
|
| bottom | 底部弹出 |
|
|
| message | 预置样式 ：消息提示 |
|
|
| dialog | 预置样式 ：对话框 |
|
|
| share | 预置样式 ：底部弹出分享示例 |
|
|
|
|
|
|
### Popup Methods
|
|
|
|
|方法称名 |说明 |参数|
|
|
|:-: |:-: |:-:|
|
|
|open |打开弹出层 |- |
|
|
|close |关闭弹出层 |- |
|
|
|
|
|
|
### Popup Events
|
|
|
|
|事件称名 |说明 |返回值 |
|
|
|:-: |:-: |:-: |
|
|
|change |组件状态发生变化触发 |e={show: true｜false,type:当前模式} |
|
|
|
|
|
|
## 扩展组件说明
|
|
`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>
|
|
```
|
|
|
|
### uni-popup-message 属性说明
|
|
|
|
| 属性名 | 类型 | 默认值 | 说明 |
|
|
| :-: | :-: | :-: | :-: |
|
|
| type | String |success| 消息提示主题，可选值： success/warn/info/error |
|
|
| message | String |- | 消息提示文字 |
|
|
| duration | Number |3000 | 消息显示时间，超过显示时间组件自动关闭，设置为0 将不会关闭，需手动调用 close 方法关闭 |
|
|
|
|
### uni-popup-dialog 对话框
|
|
|
|
将 `uni-popup` 的`type`属性改为 `dialog`，并引入对应组件即可使用对话框 ，*该组件不支持单独使用*
|
|
|
|
**示例**
|
|
|
|
```html
|
|
<uni-popup ref="popup" type="dialog">
|
|
<uni-popup-dialog type="input" message="成功消息" :duration="2000" :before-close="true" @close="close" @confirm="confirm"></uni-popup-dialog>
|
|
</uni-popup>
|
|
```
|
|
|
|
```javascript
|
|
export default {
|
|
methods:{
|
|
/**
|
|
* 点击取消按钮触发
|
|
* @param {Object} done
|
|
*/
|
|
close(done){
|
|
// TODO 做一些其他的事情，before-close 为true的情况下，手动执行 done 才会关闭对话框
|
|
// ...
|
|
done()
|
|
},
|
|
/**
|
|
* 点击确认按钮触发
|
|
* @param {Object} done
|
|
* @param {Object} value
|
|
*/
|
|
confirm(done,value){
|
|
// 输入框的值
|
|
console.log(value)
|
|
// TODO 做一些其他的事情，手动执行 done 才会关闭对话框
|
|
// ...
|
|
done()
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### uni-popup-dialog 属性说明
|
|
|
|
| 属性名 | 类型 | 默认值 | 说明 |
|
|
| :-: | :-: | :-: | :-: |
|
|
| 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，则不会关闭对话框，关闭需要监听 dialog 的 close 事件，并执行 done()|
|
|
|
|
#### dialog 事件说明
|
|
|
|
|事件称名 |说明 |返回值 |
|
|
|:-: |:-: |:-: |
|
|
|close |点击dialog取消按钮触发 |done:执行关闭对话框 |
|
|
|confirm |点击dialog确定按钮触发 |done:执行关闭对话框：value：input模式下输入框的值 |
|
|
|
|
|
|
### 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>
|
|
```
|
|
|
|
### uni-popup-share 属性说明
|
|
|
|
| 属性名| 类型 | 默认值 | 说明 |
|
|
| :-: | :-: | :-: | :-: |
|
|
| title | String | | 分享弹窗标题 |
|
|
|
|
### uni-popup-share 事件说明
|
|
|
|
|事件称名 |说明 |返回值 |
|
|
|:-: |:-: |:-: |
|
|
|select |选择触发 |e = {item,index}：所选参数,done：执行关闭窗口 |
|
|
|
|
**Tips**
|
|
- share 分享组件，只是作为一个扩展示例，如果需要修改数据源，请到组件内修改
|
|
|
|
## 如何扩展自己的 uni-popup 弹出层样式？
|
|
`uni-popup` 组件内容是通过 `slot` 插槽的方式去实现的，所以这极大的方便了我们的扩展。
|
|
|
|
现在我们可以在不改动 `uni-popup` 组件主体的情况下，方便的去扩展我们自己的弹出层样式。
|
|
|
|
### 添加自定义类型
|
|
如果要去扩展 `uni-popup`，我们需要把组件*引入本地*，才能去进行扩展。
|
|
|
|
组件放到本地后，在组件目录找到 `popup.js` ，在 `config` 变量中定义自己的类型，key 为当前要定义的类型，value 为弹出类型（top/bottom/center）
|
|
我们以 `uni-popup-share` 为例，看如何扩展一个`share` 底部分享的一个 `uni-popup` 子组件，代码参考 `uni-popup-share.vue`。
|
|
|
|
```javascript
|
|
|
|
// popup.js
|
|
const config = {
|
|
// ...
|
|
// 分享 key:share 为我们定义的类型 value : 'bottom' 为弹出方向（top/bottom/center）
|
|
// 这样配置好之后，我们自定义的弹出层就会从底部弹出
|
|
share:'bottom',
|
|
}
|
|
|
|
```
|
|
|
|
### 创建扩展组件
|
|
|
|
在组件目录创建文件 ，例 `uni-popup-share/uni-popup-share.vue`，结构与其他组件没有区别。
|
|
|
|
在组件内直接编写样式逻辑即可，如需自定义效果更强，可以通过 props 接受页面参数。
|
|
|
|
|
|
### 与父组件 `uni-popup` 进行通讯
|
|
|
|
组件通讯我们使用了 `provide/inject` ， 具体逻辑我们不需要关心，只要在子组件配置 `inject` ，即可获取父组件方法变量等。
|
|
|
|
```javascript
|
|
|
|
// uni-popup-share.vue
|
|
export default {
|
|
name: 'UniPopupShare',
|
|
props: {
|
|
title: {
|
|
type: String,
|
|
default: '分享到'
|
|
}
|
|
},
|
|
// 直接把下面这一行代码，放到自己的组件内
|
|
inject: ['popup'],
|
|
// ...
|
|
methons:{
|
|
/**
|
|
* 定义的选择事件，选择内容后触发
|
|
*/
|
|
select(item, index) {
|
|
// 将事件发送到页面，在页面进行监听
|
|
this.$emit('select', {
|
|
item,
|
|
index
|
|
}, () => {
|
|
// 延迟操作，执行父组件的close事件，关闭弹出层
|
|
this.popup.close()
|
|
})
|
|
},
|
|
/**
|
|
* 关闭窗口
|
|
*/
|
|
close() {
|
|
// 执行父组件的close事件，关闭弹出层
|
|
this.popup.close()
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
### 使用自定义组件
|
|
|
|
通过上面几个步骤 ，我们就可以使用这个组件了，只需要把我们自定义的组件放置到 `uni-popup` 组件内即可 ，指定 `uni-popup` 的 `type` 为我们第一步定义好的 `share`
|
|
|
|
```html
|
|
<uni-popup ref="popup" type="share">
|
|
<uni-popup-share title="分享到" @select="select"></uni-popup-share>
|
|
</uni-popup>
|
|
```
|
|
|
|
之后就可以按照 `uni-popup` 的使用方式去打开关闭弹出层了。更多细节可以参考 `uni-popup-message` 和 `uni-popup-dialog`。
|
|
|
|
|
|
**Tips**
|
|
- 如果扩展组件目录名和组件名不一致，可能不会被 `easycom` 正确引用，请配置`easycom`规则或修改组件名称
|
|
|
|
### 分享你的组件
|
|
|
|
通过组件扩展，你可以扩展出更丰富的弹出层样式，如果您想让更多人使用你定制的组件，或者您有更好的点子或更好的实现方式，欢迎给我们提交 [PR](https://github.com/dcloudio/uni-ui/pulls)，如被采用，会合并到示例中。
|
|
|
|
在使用中如遇到无法解决的问题，请提 [Issues](https://github.com/dcloudio/uni-ui/issues) 给我们。
|
|
|
|
|