From 061cd58081f4197e2979b4af4a23ec25fe6c86b2 Mon Sep 17 00:00:00 2001 From: wanganxp Date: Wed, 23 Oct 2024 08:28:23 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api/dialog-page.md | 54 +++++++++++++++++++++++++++-------- docs/api/get-app.md | 14 ++++++--- docs/api/get-current-pages.md | 5 ++++ docs/api/privacy.md | 14 +++++++++ docs/collocation/pagesjson.md | 2 ++ docs/component/button.md | 2 +- 6 files changed, 74 insertions(+), 17 deletions(-) diff --git a/docs/api/dialog-page.md b/docs/api/dialog-page.md index 0fc77ad7..6465ed73 100644 --- a/docs/api/dialog-page.md +++ b/docs/api/dialog-page.md @@ -1,3 +1,41 @@ +## 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 @@ -16,6 +54,8 @@ +`closeDialogPage` 可通过 `dialogPage` 参数指定要关闭的 `dialogPage`, 不指定时默认关闭当前页面的所有 `dialogPage`。 + @@ -33,9 +73,7 @@ ## Tips -* `dialogPage` 背景固定为透明，不支持设置背景颜色。 -* 每个 `dialogPage` 都会与普通 `page` 进行关联，也就是 `dialogPage` 的所属页面，`dialogPage` 可通过 `getParentPage` 方法获取所属页面。 -* `dialogPage` 不影响页面栈和路由地址，可通过如下方式获取 `dialogPage`。 +* 可通过如下方式获取 `dialogPage`。 ```js // 1. 通过 parentPage 获取 dialogPage 集合 const pages = getCurrentPages() @@ -46,12 +84,4 @@ const dialogPages = page.getDialogPages() // 2. 在 dialogPage 中通过 this.$page 获取 dialogPage 实例 const dialogPage = this.$page -``` -* `openDialogPage` 时可通过 `parentPage` 参数指定所属页面，不指定时默认为当前页面。\ -在 `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 +``` \ No newline at end of file diff --git a/docs/api/get-app.md b/docs/api/get-app.md index 5f1824a3..18c4b26e 100644 --- a/docs/api/get-app.md +++ b/docs/api/get-app.md @@ -2,6 +2,11 @@ +- HBuilderX 4.31以前，getApp返回的是vue实例。并且在uts插件中无法使用。 +- HBuilderX 4.31+，新增了UniApp对象，用于管理app，getApp返回的是UniApp对象。而vue实例，则是UniApp对象的一个vm属性。 + +UniApp对象可以在uts插件和uvue页面中同时使用，但vm属性以及相关的globalData仍然只能在uvue页面中才能使用。 + @@ -10,12 +15,13 @@ - - +### 全局方法调用@appmethods 以上示例，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()`。 + + + diff --git a/docs/api/get-current-pages.md b/docs/api/get-current-pages.md index 40fe63ae..3e63e071 100644 --- a/docs/api/get-current-pages.md +++ b/docs/api/get-current-pages.md @@ -2,6 +2,10 @@ +HBuilderX 4.31+，强化了页面对象，新增了UniPage对象。getCurrentPages()返回值改为UniPage对象数组。 + +UniPage对象强化了开发者对页面的管理功能，并且支持在uts插件中使用。 + @@ -9,6 +13,7 @@ ::: warning 注意 +- HBuilderX 4.31+，$getPageStyle和$setPageStyle不再需要加前缀$。 - 使用`选项式 API` 时，不可创建 `route`、`options` 同名响应式变量，否则会覆盖当前 `page 实例` 的同名属性。 - 仅 `Web` 与 `iOS` 端支持通过 `page.$vm` 获取 vue 实例。 ::: diff --git a/docs/api/privacy.md b/docs/api/privacy.md index 47aa94a0..68545fa0 100644 --- a/docs/api/privacy.md +++ b/docs/api/privacy.md @@ -1,3 +1,15 @@ +## 隐私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 @@ -16,6 +28,8 @@ +适用于隐私协议变更，需要重新同意的场景。 + diff --git a/docs/collocation/pagesjson.md b/docs/collocation/pagesjson.md index c2ccd17e..13c075b5 100644 --- a/docs/collocation/pagesjson.md +++ b/docs/collocation/pagesjson.md @@ -167,6 +167,8 @@ pages节点里注册页面，数据格式是数组，数组每个项都是一个 * 如需动态设置状态栏颜色，使用api [uni.setNavigationBarColor](../api/set-navigation-bar-color.md) * 当navigationStyle设为custom时，原生导航栏不显示。此时需要注意系统状态栏背景色恒为透明。 * 注意不同手机的状态栏高度并不相同，如需获取本机的状态栏高度，使用api [uni.getWindowInfo](../api/get-window-info.md) 或 css变量 [--status-bar-height](../css/common/variable.md) + * 配置hideStatusBar可以隐藏状态栏 + * 同时隐藏状态栏hideStatusBar和底部指示器hideBottomNavigationIndicator，可以实现页面全屏 - 下拉刷新 * pages.json中下拉刷新是页面级配置，方便使用但灵活度有限。 * 如需自定义下拉刷新，请使用[scroll-view](../component/scroll-view.md)或[list-view](../component/list-view.md)的下拉刷新。 diff --git a/docs/component/button.md b/docs/component/button.md index 70b0f8ba..877c83db 100644 --- a/docs/component/button.md +++ b/docs/component/button.md @@ -20,7 +20,7 @@ + 如果hover-class属性值设置为none，在style样式里面设置了同名的none样式，none样式将不起作用，没有点击态效果 + 如果hover-class属性值设置为button-hover或者不设置hover-class属性值，在style样式里面设置了同名的button-hover样式，点击效果将使用button-hover样式 + 如果hover-class属性值设置为无效值（或非法值），没有点击态效果 - +- `open-type="agreePrivacyAuthorization"`，用于开发者在让用户同意隐私协议时，放置“同意”按钮。它并非强制性的，它只是开发者和插件作者之间的一种通信方式。并不是没有点下这个按钮，技术上就拦截了涉及隐私的API的调用。[详见](../api/privacy.md) -- GitLab