提交 061cd580 编写于 作者: W wanganxp

完善文档

上级 2a836993
## dialogPage概述
HBuilderX 4.31+新增了dialogPage,适用于制作弹框。
### 需求背景
- uni.showModal、actionsheet,自定义性不足
- 通过前端组件实现的弹框,无法覆盖pages.json的导航栏和tabbar
- 前端实现的弹框,无法拦截back按键,一点back整页关了
- 组件方式实现弹框,需要每个页面都引入组件,写法较麻烦
### dialogPage方案
dialogPage是一种背景透明的页面,可以覆盖pages.json中的导航栏和tabbar。之前的page被称为主page或parentPage。dialogPage需要挂在主page上。
dialogPage是一种特殊的page,它和主page有很多相同之处:
- dialogPage需在pages.json注册
- dialogPage有页面生命周期,onLoad里也可以拿到各种参数
- dialogPage里如果引用了组件,对于组件而言,其page就是dialogPage。组合式组件中监听onPageShow,是监听dialogPage,而不是dialogPage的parentPage。
- dialogPage可以通过uni.$on等eventbus方案进行页面级通信
dialogPage和主page的区别:
- dialogPage的背景固定为透明、大小为铺满应用。蒙层由页面内部实现,蒙层颜色、是否响应点击,均由页面内部处理。如果是模态,蒙层不应该允许点击;非模态,则点击蒙层应关闭dialogPage
- dialogPage不使用uni.navigatorTo等路由API,而是单独提供了`openDialogPage``closeDialogPage`
- dialogPage不影响页面栈和路由地址,在getCurrentPages里不能直接得到dialogPage(需在UniPage对象通过getDialogPages获取)
- dialogPage不响应iOS侧滑返回,即disableSwipeBack永远为true。响应Android的back键和back手势,可以在dialogPage中自定义如何响应。
- dialogPage不影响调用页面或其parentPage的show、hide生命周期。
- dialogPage中可以调用普通路由api,比如uni.navigateTo、navigateBack,但并不作用于dialogPage,而是作用于其parentPage。即,之前的路由API均只作用于主Page。
- 在web平台,dialogPage显示时,不影响URL的变化。
- dialogPage默认没有窗体动画,建议在页面内通过css或uts操作页面元素进行动画。
dialogPage的绑定:
- dialogPage需绑定在某个主页面上,即parentPage。parentPage页面关闭时,自动销毁相关dialogPage。
- 在app的onLaunch调用openDialogPage,绑定到首页。
- `openDialogPage` 时可通过 `parentPage` 参数指定所属页面,不指定时默认为当前页面。
多dialogPage注意事项:
- dialogPage可以有多个,通过UniPage对象的getDialogPages()可以获取主页面挂载的所有dialogPage。
- 多个dialogPage层叠时,可以通过close api任意关闭某个dialogPage。
- 当前 dialogPage 关闭会触发前一个 dialogPage onShow 生命周期
## uni.openDialogPage(options) @opendialogpage ## uni.openDialogPage(options) @opendialogpage
<!-- UTSAPIJSON.openDialogPage.description --> <!-- UTSAPIJSON.openDialogPage.description -->
...@@ -16,6 +54,8 @@ ...@@ -16,6 +54,8 @@
<!-- UTSAPIJSON.closeDialogPage.description --> <!-- UTSAPIJSON.closeDialogPage.description -->
`closeDialogPage` 可通过 `dialogPage` 参数指定要关闭的 `dialogPage`, 不指定时默认关闭当前页面的所有 `dialogPage`
<!-- UTSAPIJSON.closeDialogPage.compatibility --> <!-- UTSAPIJSON.closeDialogPage.compatibility -->
<!-- UTSAPIJSON.closeDialogPage.param --> <!-- UTSAPIJSON.closeDialogPage.param -->
...@@ -33,9 +73,7 @@ ...@@ -33,9 +73,7 @@
<!-- UTSAPIJSON.general_type.param --> <!-- UTSAPIJSON.general_type.param -->
## Tips ## Tips
* `dialogPage` 背景固定为透明,不支持设置背景颜色。 * 可通过如下方式获取 `dialogPage`
* 每个 `dialogPage` 都会与普通 `page` 进行关联,也就是 `dialogPage` 的所属页面,`dialogPage` 可通过 `getParentPage` 方法获取所属页面。
* `dialogPage` 不影响页面栈和路由地址,可通过如下方式获取 `dialogPage`
```js ```js
// 1. 通过 parentPage 获取 dialogPage 集合 // 1. 通过 parentPage 获取 dialogPage 集合
const pages = getCurrentPages() const pages = getCurrentPages()
...@@ -46,12 +84,4 @@ const dialogPages = page.getDialogPages() ...@@ -46,12 +84,4 @@ const dialogPages = page.getDialogPages()
// 2. 在 dialogPage 中通过 this.$page 获取 dialogPage 实例 // 2. 在 dialogPage 中通过 this.$page 获取 dialogPage 实例
const dialogPage = this.$page const dialogPage = this.$page
``` ```
* `openDialogPage` 时可通过 `parentPage` 参数指定所属页面,不指定时默认为当前页面。\ \ No newline at end of file
`app onLaunch` 调用 `openDialogPage`, `dialogPage``parentPage` 为首页。
* `dialogPage` 不响应 `iOS` 侧滑返回,响应 `Android` 的 back 键和 back 手势。
* `dialogPage` 有页面的所有生命周期,且不影响 `parentPage` 的生命周期。\
新的 `dialogPage` 会触发当前 `dialogPage` `onHide` 生命周期, 当前 `dialogPage` 关闭会触发前一个 `dialogPage` `onShow` 生命周期。
* `dialogPage` 中可以调用路由 API,比如 `uni.navigateTo``uni.navigateBack`,路由 API不会作用于 `dialogPage`
* `closeDialogPage` 可通过 `dialogPage` 参数指定要关闭的 `dialogPage`, 不指定时默认关闭当前页面的所有 `dialogPage`
* `parentPage` 销毁时,其关联的 `dialogPage` 也会被销毁。
\ No newline at end of file
...@@ -2,6 +2,11 @@ ...@@ -2,6 +2,11 @@
<!-- UTSAPIJSON.getApp.description --> <!-- UTSAPIJSON.getApp.description -->
- HBuilderX 4.31以前,getApp返回的是vue实例。并且在uts插件中无法使用。
- HBuilderX 4.31+,新增了UniApp对象,用于管理app,getApp返回的是UniApp对象。而vue实例,则是UniApp对象的一个vm属性。
UniApp对象可以在uts插件和uvue页面中同时使用,但vm属性以及相关的globalData仍然只能在uvue页面中才能使用。
<!-- UTSAPIJSON.getApp.compatibility --> <!-- UTSAPIJSON.getApp.compatibility -->
<!-- UTSAPIJSON.getApp.param --> <!-- UTSAPIJSON.getApp.param -->
...@@ -10,12 +15,13 @@ ...@@ -10,12 +15,13 @@
<!-- UTSAPIJSON.getApp.example --> <!-- UTSAPIJSON.getApp.example -->
<!-- UTSAPIJSON.getApp.tutorial --> ### 全局方法调用@appmethods
以上示例,getApp()后调用了app.uvue里定义的increasetLifeCycleNum方法。app.uvue的源码[另见](https://gitcode.net/dcloud/hello-uni-app-x/-/blob/alpha/App.uvue) 以上示例,getApp()后调用了app.uvue里定义的increasetLifeCycleNum方法。app.uvue的源码[另见](https://gitcode.net/dcloud/hello-uni-app-x/-/blob/alpha/App.uvue)
### 全局方法调用@appmethods **调整** :HBuilderX 4.31 `getApp()` 返回值调整为 `UniApp` 类型,调用 `App.uvue` 中定义的全局方法,需要由 `getApp().methodName()` 调整为 `getApp().vm?.methodName()`
HBuilderX 4.31 `getApp()` 返回值调整为 `UniApp` 类型,调用 `App.uvue` 中定义的全局方法,需要由 `getApp().methodName()` 调整为 `getApp().vm?.methodName()`
<!-- UTSAPIJSON.getApp.tutorial -->
<!-- UTSAPIJSON.general_type.name --> <!-- UTSAPIJSON.general_type.name -->
<!-- UTSAPIJSON.general_type.param --> <!-- UTSAPIJSON.general_type.param -->
...@@ -2,6 +2,10 @@ ...@@ -2,6 +2,10 @@
<!-- UTSAPIJSON.getCurrentPages.description --> <!-- UTSAPIJSON.getCurrentPages.description -->
HBuilderX 4.31+,强化了页面对象,新增了UniPage对象。getCurrentPages()返回值改为UniPage对象数组。
UniPage对象强化了开发者对页面的管理功能,并且支持在uts插件中使用。
<!-- UTSAPIJSON.getCurrentPages.compatibility --> <!-- UTSAPIJSON.getCurrentPages.compatibility -->
<!-- UTSAPIJSON.getCurrentPages.param --> <!-- UTSAPIJSON.getCurrentPages.param -->
...@@ -9,6 +13,7 @@ ...@@ -9,6 +13,7 @@
<!-- UTSAPIJSON.getCurrentPages.returnValue --> <!-- UTSAPIJSON.getCurrentPages.returnValue -->
::: warning 注意 ::: warning 注意
- HBuilderX 4.31+,$getPageStyle和$setPageStyle不再需要加前缀$。
- 使用`选项式 API` 时,不可创建 `route``options` 同名响应式变量,否则会覆盖当前 `page 实例` 的同名属性。 - 使用`选项式 API` 时,不可创建 `route``options` 同名响应式变量,否则会覆盖当前 `page 实例` 的同名属性。
-`Web``iOS` 端支持通过 `page.$vm` 获取 vue 实例。 -`Web``iOS` 端支持通过 `page.$vm` 获取 vue 实例。
::: :::
......
## 隐私API
因为uni-app下开发者的js代码执行较晚,所以框架提供了原生隐私协议框,但自定义性较差。
uni-app x并不需要这套机制,开发者的代码就是原生代码,执行时机很早,可以自己弹出隐私协议政策。(如在app launch生命周期中弹出dialogPage的协议框)
但应用开发者和插件开发者,有时需要共享隐私协议是否同意的状态。所以提供了如下一批能力。
- `uni.getPrivacySetting`:获取用户是否同意了隐私协议
- `uni.resetPrivacyAuthorization`:重置隐私协议状态。适用于隐私协议变更,需要重新同意的场景
- `uni.onPrivacyAuthorizationChange``uni.offPrivacyAuthorizationChange`:监听和取消监听用户是否同意隐私协议
-[button组件](../component/button.md)中,提供了属性open-type="agreePrivacyAuthorization"。之所以同意隐私协议是按钮,而不是API,是因为需要用户真实的同意。避免插件作者通过API非正常设置隐私协议为同意。所以开发者务必在隐私协议的同意按钮处使用 open-type="agreePrivacyAuthorization" 的 button组件。
## uni.getPrivacySetting(options) @getprivacysetting ## uni.getPrivacySetting(options) @getprivacysetting
<!-- UTSAPIJSON.getPrivacySetting.description --> <!-- UTSAPIJSON.getPrivacySetting.description -->
...@@ -16,6 +28,8 @@ ...@@ -16,6 +28,8 @@
<!-- UTSAPIJSON.resetPrivacyAuthorization.description --> <!-- UTSAPIJSON.resetPrivacyAuthorization.description -->
适用于隐私协议变更,需要重新同意的场景。
<!-- UTSAPIJSON.resetPrivacyAuthorization.compatibility --> <!-- UTSAPIJSON.resetPrivacyAuthorization.compatibility -->
<!-- UTSAPIJSON.resetPrivacyAuthorization.param --> <!-- UTSAPIJSON.resetPrivacyAuthorization.param -->
......
...@@ -167,6 +167,8 @@ pages节点里注册页面,数据格式是数组,数组每个项都是一个 ...@@ -167,6 +167,8 @@ pages节点里注册页面,数据格式是数组,数组每个项都是一个
* 如需动态设置状态栏颜色,使用api [uni.setNavigationBarColor](../api/set-navigation-bar-color.md) * 如需动态设置状态栏颜色,使用api [uni.setNavigationBarColor](../api/set-navigation-bar-color.md)
* 当navigationStyle设为custom时,原生导航栏不显示。此时需要注意系统状态栏背景色恒为透明。 * 当navigationStyle设为custom时,原生导航栏不显示。此时需要注意系统状态栏背景色恒为透明。
* 注意不同手机的状态栏高度并不相同,如需获取本机的状态栏高度,使用api [uni.getWindowInfo](../api/get-window-info.md) 或 css变量 [--status-bar-height](../css/common/variable.md) * 注意不同手机的状态栏高度并不相同,如需获取本机的状态栏高度,使用api [uni.getWindowInfo](../api/get-window-info.md) 或 css变量 [--status-bar-height](../css/common/variable.md)
* 配置hideStatusBar可以隐藏状态栏
* 同时隐藏状态栏hideStatusBar和底部指示器hideBottomNavigationIndicator,可以实现页面全屏
- 下拉刷新 - 下拉刷新
* pages.json中下拉刷新是页面级配置,方便使用但灵活度有限。 * pages.json中下拉刷新是页面级配置,方便使用但灵活度有限。
* 如需自定义下拉刷新,请使用[scroll-view](../component/scroll-view.md)[list-view](../component/list-view.md)的下拉刷新。 * 如需自定义下拉刷新,请使用[scroll-view](../component/scroll-view.md)[list-view](../component/list-view.md)的下拉刷新。
......
...@@ -20,7 +20,7 @@ ...@@ -20,7 +20,7 @@
+ 如果hover-class属性值设置为none,在style样式里面设置了同名的none样式,none样式将不起作用,没有点击态效果 + 如果hover-class属性值设置为none,在style样式里面设置了同名的none样式,none样式将不起作用,没有点击态效果
+ 如果hover-class属性值设置为button-hover或者不设置hover-class属性值,在style样式里面设置了同名的button-hover样式,点击效果将使用button-hover样式 + 如果hover-class属性值设置为button-hover或者不设置hover-class属性值,在style样式里面设置了同名的button-hover样式,点击效果将使用button-hover样式
+ 如果hover-class属性值设置为无效值(或非法值),没有点击态效果 + 如果hover-class属性值设置为无效值(或非法值),没有点击态效果
- `open-type="agreePrivacyAuthorization"`,用于开发者在让用户同意隐私协议时,放置“同意”按钮。它并非强制性的,它只是开发者和插件作者之间的一种通信方式。并不是没有点下这个按钮,技术上就拦截了涉及隐私的API的调用。[详见](../api/privacy.md)
<!-- UTSCOMJSON.button.children --> <!-- UTSCOMJSON.button.children -->
<!-- UTSCOMJSON.button.example --> <!-- UTSCOMJSON.button.example -->
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册