From 0e37afaa8bb5c757ad6b911779a7839a92a999c8 Mon Sep 17 00:00:00 2001 From: wanganxp Date: Sun, 2 Jun 2024 05:01:24 +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/_sidebar.md | 31 ++++++++-------- docs/api/_sidebar.md | 2 +- docs/api/get-provider.md | 20 ++++++++++ docs/api/theme.md | 6 +-- docs/collocation/themejson.md | 70 ++++++++++++++++++++++++----------- docs/css/transform.md | 6 +++ 6 files changed, 94 insertions(+), 41 deletions(-) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index f3c19dc1..b1edad60 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -10,6 +10,22 @@ * web平台专题指南 * [概述](web/README.md) * [服务端渲染ssr](web/ssr.md) +* app平台专题指南 + * uni-app x 原生SDK和离线打包 + * [概述](native/README.md) + * Android离线打包 + * [原生工程配置](native/use/android.md) + * 模块配置 + * [内置模块](native/modules/android/others.md) + * [uni-ad](native/modules/android/uni-ad.md) + * [uni-facialRecognitionVerify](native/modules/android/uni-facialRecognitionVerify.md) + * [uni-payment](native/modules/android/uni-payment.md) + * [uni-push](native/modules/android/uni-push.md) + * [uni-video](native/modules/android/uni-video.md) + * [uni-verify](native/modules/android/uni-verify.md) + * [启动与通信](native/use/androidcomm.md) + * [自定义基座](native/debug/android.md) + * 运行和调试 * [真机运行](https://uniapp.dcloud.net.cn/tutorial/run/run-app.html) * [Android审查元素](debug/android-inspector.md) @@ -17,21 +33,6 @@ * [源码和示例](sample.md) * [uni错误规范](https://uniapp.dcloud.net.cn/tutorial/err-spec.html) * [跨平台框架及原生对比](select.md) -* 离线打包 - * [概述](native/README.md) - * Android离线打包 - * [原生工程配置](native/use/android.md) - * 模块配置 - * [内置模块](native/modules/android/others.md) - * [uni-ad](native/modules/android/uni-ad.md) - * [uni-facialRecognitionVerify](native/modules/android/uni-facialRecognitionVerify.md) - * [uni-payment](native/modules/android/uni-payment.md) - * [uni-push](native/modules/android/uni-push.md) - * [uni-video](native/modules/android/uni-video.md) - * [uni-verify](native/modules/android/uni-verify.md) - * [启动与通信](native/use/androidcomm.md) - * [自定义基座](native/debug/android.md) - * 更新日志 * [正式版](release.md) * [Alpha 版](release-note-alpha.md) diff --git a/docs/api/_sidebar.md b/docs/api/_sidebar.md index 44e1927f..bc3f74c0 100644 --- a/docs/api/_sidebar.md +++ b/docs/api/_sidebar.md @@ -25,7 +25,7 @@ * [交互反馈](prompt.md) * [动态加载字体](load-font-face.md) * [rpx2px](rpx2px.md) - + * [暗黑主题](theme.md) * 网络 * [发起请求request](request.md) * [上传文件](upload-file.md) diff --git a/docs/api/get-provider.md b/docs/api/get-provider.md index 1acf760c..faacb3a3 100644 --- a/docs/api/get-provider.md +++ b/docs/api/get-provider.md @@ -2,6 +2,26 @@ +uni-app的api，统一了多平台的差异。但在app平台，有的功能可以由很多SDK来支撑。比如 +- 支付：有支付宝支持、微信支付、iap支付 +- 定位：有系统定位、腾讯定位、高德定位 + +不同的SDK，本身的api是完全不同的，甚至同一个SDK的Android和iOS的API也不一样。 + +uni-app 通过 provider 机制来统一不同的SDK，屏蔽他们的差异。同一个功能的不同的SDK，都被称为该功能的 provider，即供应商。 + +比如对于支付模块，有 支付宝 和 微信 这2个 provider 可用。 + +由于这些[模块和SDK](../collocation/manifest-modules.md)在打包时是可选的，那么在运行时可以通过 `uni.getProvider`，来获取到本App包中包含的provider清单。 + +注意我们要把SDK和App的概念区分清楚。对于支付的2个provider，支付宝和微信，它们也有各自的主App。 + +本API `uni.getProvider`，只是获取开发者的App包中的provider清单。但本API不负责判断这些provider的主App是否安装在同一台手机上。 + +微信比较特殊，如果没有微信App，微信支付无法完成。其他SDK无此限制。 + +所以微信支付SDK，自身提供了获取微信主App是否安装的API，那么这个API也被封装到了本API返回的对象里。 + diff --git a/docs/api/theme.md b/docs/api/theme.md index cda7964c..9afac5d2 100644 --- a/docs/api/theme.md +++ b/docs/api/theme.md @@ -2,8 +2,8 @@ -uni.setAppTheme，并不会帮助开发者自动实现亮/暗主题切换，它的作用是： -1. 根据theme.json，设置pages.json的亮/暗主题 +uni.setAppTheme，并不会帮助开发者自动实现整个应用的亮/暗主题切换，它的作用是： +1. 根据[theme.json](../collocation/themejson.md)，设置pages.json的亮/暗主题 2. 触发uni.onAppThemeChange，开发者和组件作者均可监听这个事件，自行响应将页面设置为对应的亮/暗风格。 当然组件作者也可以不监听onAppThemeChange，而是暴露主题切换API给开发者，由开发者监听主题切换，再调用组件的主题切换API。 @@ -50,7 +50,7 @@ val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> { **注意：** -+ android 平台 android版本 10 开始支持深色模式主题 `dark`，低于10不支持深色模式主题 ++ android 10、iOS 13 才开始支持深色模式主题 `dark`，更低版本无法获取、监听OS的主题。 ## uni.offOsThemeChange(id) @offosthemechange diff --git a/docs/collocation/themejson.md b/docs/collocation/themejson.md index 7a1b3840..1405a6d5 100644 --- a/docs/collocation/themejson.md +++ b/docs/collocation/themejson.md @@ -2,36 +2,39 @@ > HBuilder X 4.18+ 支持 -### app +`iOS 13+`、`Android 10+` 提供了暗黑模式/深色模式，之前的模式称为light，暗黑称为dark。 -使用步骤 +当app需要暗黑主题时，开发者虽然可以自行决定自己的界面样式，但缺少合适的设置pages.json中样式的时机。 -1. 在 `theme.json` 中定义相关变量 -2. 在 `pages.json` 中以@开头引用变量 -3. 可选在 `manifest.json -> app` 中配置主题默认值 `"defaultAppTheme": "light"`, 支持通过[主题API](https://doc.dcloud.net.cn/uni-app-x/api/theme.html)动态设置 +在页面的onLoad中设置当前页面的style会来不及，因为某些平台页面早于onLoad就可以创建和进行窗体转场动画，\ +这会造成新页面动画刚开始页面的背景色、navigationBar背景色是一个风格，而在onLoad后颜色发生变化。\ +也就是俗称的 转场闪白 或 闪黑。 -**注意：** -- `iOS 13+`、`Android 10+`设备上才支持 +小程序提供了theme.json来给解决这个问题。在theme.json里配置light和dark的颜色，然后在pages.json中引用。 -支持通过变量配置的属性如下所示： +新页面创建时是根据pages.json的设置来初始化页面的，这样就可以在第一时间对页面样式进行适配，避免闪白闪黑。 -- 全局配置 globalStyle 与页面支持 +考虑到全端兼容，uni-app x的web和app也支持theme.json设置。 - - navigationBarBackgroundColor - - navigationBarTextStyle - - backgroundColor - - backgroundTextStyle +但需要注意：**theme.json，仅负责pages.json的页面样式、tabbar样式的控制。不负责开发者自己的页面css样式控制。** -- 全局配置 tabbar 属性： - - color - - selectedColor - - backgroundColor - - borderStyle - - list - - iconPath - - selectedIconPath +适配暗黑模式，除通过theme.json控制pages.json的样式外，还需要了解更多API： +- 获取OS主题：[uni.getSystemInfo](../api/get-system-info.md)、[uni.getDevideInfo](../api/get-device-info.md)，返回的osTheme属性 +- 监听OS主题切换：[uni.onOsThemeChange](../api/theme.md#onosthemechange)、[uni.offOsThemeChange](../api/theme.md#offosthemechange)、 +- 获取App主题：[uni.getSystemInfo](../api/get-system-info.md)、[uni.getAppBaseInfo](../api/get-app-base-info.md)，返回的appTheme属性 +- 设置App主题：[uni.setAppTheme](../api/theme.md#setapptheme) +- 监听App主题切换：[uni.onAppThemeChange](../api/theme.md#onappthemechange)、[uni.offAppThemeChange](../api/theme.md#offappthemechange)、 +- manifest.json中设置App默认主题：[defaultAppTheme](../collocation/manifest.md#manifest-app) + +## theme.json使用步骤 -## 变量配置文件 theme.json@themejson +1. 在项目根目录下创建theme.json +2. 在 `theme.json` 中定义相关变量 +3. 在 `pages.json` 中以@开头引用变量 +4. 可选在 `manifest.json -> app` 中配置主题默认值 `"defaultAppTheme": "light"`, 支持通过[主题API](https://doc.dcloud.net.cn/uni-app-x/api/theme.html)动态设置 + + +## theme.json内容描述 @themejson `theme.json` 用于颜色主题相关的变量定义，包含以下属性： @@ -77,6 +80,24 @@ 配置完成后，调用相应 api 框架会自动所设属性，展示对应主题下的颜色。 +pages.json中并非所有配置项均支持使用theme.json中的变量，支持通过变量配置的属性如下所示： + +- 全局配置 globalStyle 与页面 style 支持： + + - navigationBarBackgroundColor + - navigationBarTextStyle + - backgroundColor + - backgroundTextStyle + +- 全局配置 tabbar 属性： + - color + - selectedColor + - backgroundColor + - borderStyle + - list + - iconPath + - selectedIconPath + ## 配置示例@themeconfig pages.json（示例省略了主题相关以外的配置项） @@ -146,3 +167,8 @@ theme.json } } ``` + +在[hello uni-app x](https://hellouniappx.dcloud.net.cn/)中，已经配置了theme.json，在 api 的主题切换示例中，可以体验。 + +**注意：** +- `iOS 13+`、`Android 10+`设备上才支持暗黑模式 \ No newline at end of file diff --git a/docs/css/transform.md b/docs/css/transform.md index b44d4094..c5425128 100644 --- a/docs/css/transform.md +++ b/docs/css/transform.md @@ -11,6 +11,12 @@ + +web中经常使用scaleY缩放一个1px的线条变成0.5px的细线。这个方案在app也适用。示例如下： +```html + +``` + **注意事项**：iOS 平台设置了`rotateX()`、`rotateY()`、`rotateZ()`的组件视图是在三维空间中的旋转具有穿透效果，会被同一层级中其他组件视图遮盖住穿透的部分，如果不想被遮盖同层级中请不要存在其他组件。 -- GitLab