tmui-cli 2.0.3 → 2.0.4

package/data/uni-app-x-docs/api/theme-change.md

@@ -0,0 +1,477 @@
+## 暗黑主题适配教程light和dark
+
+### 基础概念
+`iOS 13+`、`Android 10+` 提供了暗黑模式/深色模式，之前的模式称为light，暗黑称为dark。
+
+同时也要注意，低于上述版本的手机，系统层没有暗黑模式概念。
+
+在uni-app x中，有3种主题概念：OSTheme、hostTheme、appTheme。每种主题在不同平台支持度不同，获取、设置和监听变化的方式也不同。
+
+|主题概念	|描述												|App|Web|小程序	|获取方式																			|设置方式												|监听变化							|
+|--				|--													|--	|--	|--			|--																						|--															|--										|
+|osTheme	|手机OS的当前主题							|√	|x	|x			|[uni.getDeviceInfo](./get-device-info.md)		|-															|[uni.onOsThemeChange](#onosthemechange)|
+|hostTheme|浏览器或小程序宿主的当前主题	|x	|√	|√			|[uni.getAppBaseInfo](./get-app-base-info.md)		|-															|[uni.onHostThemeChange](#onhostthemechange)|
+|appTheme	|App当前主题									|√	|X	|x			|[uni.getAppBaseInfo](./get-app-base-info.md)	|[uni.setAppTheme](#setapptheme)|[uni.onAppThemeChange](#onappthemechange)|
+
+Web和小程序注意：
+- 没有能力获取os的主题。只能获取浏览器或小程序宿主的主题，即hostTheme。
+- 可以选择不响应hostTheme（darkmode设置为false），也可以根据hostTheme调整自身的表现（darkmode设置为true）。
+- 一旦在manifest里开启darkmode，pages.json的tabbar、导航栏、页面背景色，某些浏览器或小程序自带的组件和涉及UI的API，都会跟随hostTheme变化，开发者的应用无法控制这些ui的主题。比如浏览器的alert()、小程序的showModal。
+
+一般情况下，独立设置主题的场景常见于App平台，所以App平台新增了appTheme的概念。appTheme有几个用途：
+1. 独立于osTheme设置主题
+2. 方便开发者和插件作者协作。推荐各个插件作者在涉及UI时，支持主题适配，响应App的主题变化
+3. uni-app x框架自带的一些UI页面，比如showActionSheet、比如pages.json的页面设置，会响应appTheme的变化
+
+开发者做主题适配时需要先明确需求，这3种做法，需要做的事情都不一样：
+1. 只做dark，不做light
+- 只需要在pages.json的globalStyle里写死页面背景、tabBar以及navigationBar的背景前景颜色。
+- 在uvue页面里写死暗色系颜色值。无需动态判断、无需css变量。本文接下来都不用再看了。
+2. 只跟随“上家”（App的上家是osTheme、小程序和web的上家是hostTheme），不需要给用户提供手动切换
+- 要做一些事情，见下
+3. App上提供独立的light/dark/auto选项给用户，可以根据osTheme，也可以独立设置
+- 要做更多事情，了解appTheme相关API，见下
+
+### 主题适配处理内容范围
+开发者做主题适配时需处理的内容范围，涉及manifest.json、theme.json、pages.json、app.uvue，以及自己的uvue页面。
+
+#### 1.manifest.json
+web 端、小程序需要配置 [manifest.json](../collocation/manifest.md) 中 `web`、`mp-weixin` 根节点的 `"darkmode": true`。配置后如果不生效请重新编译运行
+```json
+{
+	"mp-weixin": {
+		"darkmode": true
+	},
+	"web": {
+		"darkmode": true
+	}
+}
+```
+
+#### 2. pages.json和theme.json
+
+[pages.json](../collocation/pagesjson.md)的亮黑设置，需要通过[theme.json](../collocation/themejson.md)处理。
+
+要特别注意，**适配暗黑模式，如果要适配pages.json中的tabbar和Navigationbar，需放置theme.json文件**。
+
+下面是pages.json中的globalStyle设置，在属性值中，通过@来引用theme.json中定义的值：
+```json
+"globalStyle": {
+	"navigationBarTextStyle": "@navigationBarTextStyle",
+	"navigationBarBackgroundColor": "@navigationBarBackgroundColor",
+	"backgroundColor": "@backgroundColor",
+	"backgroundTextStyle": "@backgroundTextStyle"
+},
+```
+
+下面是theme.json的样例。theme.json的位置放在pages.json同级目录下。
+
+在light和dark节点下，分别命名一批同名的变量，并分别赋值。这些变量可以在pages.json里直接引用。
+```json
+{
+  "light": {
+    "navigationBarTextStyle": "white",
+    "navigationBarBackgroundColor": "#007AFF",
+    "backgroundColor": "#efeff4",
+    "tabBarPagebackgroundColorContent": "#efeff4",
+    "backgroundTextStyle": "dark"
+  },
+  "dark": {
+    "navigationBarTextStyle": "white",
+    "navigationBarBackgroundColor": "#1F1F1F",
+    "backgroundColor": "#1F1F1F",
+    "tabBarPagebackgroundColorContent": "#1F1F1F",
+    "backgroundTextStyle": "light"
+  }
+}
+```
+
+完整的theme.json教程详见：[theme.json](../collocation/themejson.md)
+
+theme.json 里的变量仅能用于 pages.json。uvue页面不能引用。
+
+在web和小程序中，theme.json的dark部分生效的前提是：
+1. manifest设置了`darkmode:true`
+2. 浏览器和小程序宿主如微信，主题外观是dark。
+
+在App中，可以通过manifest.json的[`app.defaultAppTheme`](../collocation/manifest.md#manifest-app)配置应用默认主题，可取值为light、dark、auto，默认值为light。配置为auto时，appTheme会跟随OS主题变化。
+
+```json
+{
+	"app": {
+		"defaultAppTheme": "auto"
+	}
+}
+```
+
+如果应用为用户提供主题切换功能，可以在运行时通过[uni.setAppTheme](#setapptheme)设置light、dark或auto。
+
+完成上述基础配置后，页面和组件的主题样式可以根据平台及版本选择以下一种方案。
+
+#### 3. 使用媒体查询适配主题（推荐）
+
+以下平台可以使用`@media (prefers-color-scheme: light)`和`@media (prefers-color-scheme: dark)`设置主题样式：
+
+- Web和小程序平台
+- HBuilderX 5.25+的App平台蒸汽模式
+
+在支持上述能力的平台，推荐优先使用媒体查询适配主题。
+
+媒体查询会根据hostTheme或appTheme自动匹配。主题变化时，匹配的样式也会自动更新，无需监听主题变化、维护响应式变量或动态切换class。详见[@media媒体查询](../css/common/at-rules.md#media)。
+
+页面只需要使用固定的class，通过媒体查询分别定义亮色和暗色样式：
+
+```vue
+<template>
+	<view class="page">
+		<text class="title">根据当前主题显示不同颜色的文字</text>
+	</view>
+</template>
+
+<style>
+	@media (prefers-color-scheme: light) {
+		.page {
+			--text-color: #333333;
+		}
+	}
+
+	@media (prefers-color-scheme: dark) {
+		.page {
+			--text-color: #ffffff;
+		}
+	}
+
+	.title {
+		color: var(--text-color);
+	}
+</style>
+```
+
+媒体查询和page选择器，可以在app.uvue里使用，从而实现所有页面的效果批量控制。除非页面配置了禁止全局样式影响。
+
+如果App平台需要为用户提供light、dark、auto选项，直接调用`uni.setAppTheme`即可。appTheme变化后，媒体查询会自动更新匹配的样式。
+
+#### 4. 监听主题并动态切换class（老版兼容方案）
+
+以下App平台场景，由于不支持媒体查询，只能通过API使用监听主题变化，然后动态切换class：
+
+- HBuilderX 5.25之前的App平台
+- App平台VDOM模式
+
+在已支持媒体查询的平台，如果业务逻辑还需要读取当前主题状态，可以另外使用主题API获取和监听，但样式仍可使用媒体查询，无需动态切换class。
+
+为了在同一套代码中兼容上述App平台场景，以下示例在各端统一使用动态class。为避免每个页面都监听主题变化，可以在app.uvue中获取并监听主题，将结果存放在`store/index.uts`中，供各页面使用。
+
+如果应用只需要跟随上家，不独立设置主题，App平台需要先将`app.defaultAppTheme`配置为auto，然后可以这样处理：
+
+```ts
+// app.uvue
+import { state } from '@/store/index.uts'
+
+onLaunch(() => {
+	// #ifdef WEB || MP-WEIXIN
+	state.isDark = (uni.getAppBaseInfo().hostTheme == 'dark')
+	uni.onHostThemeChange((result) => {
+		state.isDark = (result.hostTheme == 'dark')
+	})
+	// #endif
+
+	// #ifdef APP
+	state.isDark = (uni.getDeviceInfo().osTheme == 'dark')
+	uni.onOsThemeChange((result: OsThemeChangeResult) => {
+		state.isDark = (result.osTheme == 'dark')
+	})
+	// #endif
+})
+```
+
+`store/index.uts`的内容如下：
+
+```ts
+type State = {
+	// 是否为暗黑主题
+	isDark: boolean
+}
+
+export const state = reactive({
+	isDark: false
+} as State)
+```
+
+如果App平台允许用户独立设置主题，则需要获取和监听appTheme：
+
+```ts
+// app.uvue
+import { state } from '@/store/index.uts'
+
+onLaunch(() => {
+	// #ifdef WEB || MP-WEIXIN
+	state.isDark = (uni.getAppBaseInfo().hostTheme == 'dark')
+	uni.onHostThemeChange((result) => {
+		state.isDark = (result.hostTheme == 'dark')
+	})
+	// #endif
+
+	// #ifdef APP
+	const appTheme = uni.getAppBaseInfo().appTheme
+	state.isDark = appTheme == 'auto'
+		? uni.getDeviceInfo().osTheme == 'dark'
+		: appTheme == 'dark'
+	uni.onAppThemeChange((result: AppThemeChangeResult) => {
+		state.isDark = (result.appTheme == 'dark')
+	})
+	// #endif
+})
+```
+
+可以在app.uvue的全局样式中定义亮色和暗色class。除非页面或组件的样式隔离策略禁止全局样式影响，否则页面可以直接使用这些class。
+
+```css
+.theme-light {
+	--text-color: #333333;
+}
+
+.theme-dark {
+	--text-color: #ffffff;
+}
+```
+
+页面根节点根据`state.isDark`动态切换class：
+
+```vue
+<template>
+	<view :class="state.isDark ? 'theme-dark' : 'theme-light'">
+		<text class="title">根据当前主题显示不同颜色的文字</text>
+	</view>
+</template>
+
+<script setup lang="uts">
+	import { state } from '@/store/index.uts'
+</script>
+
+<style>
+	.title {
+		color: var(--text-color);
+	}
+</style>
+```
+
+动态切换class，由于要执行script，性能没有媒体查询高。另外动态切换class的代码，和theme.json的执行可能不在同一帧，会造成theme.json先生效、class后生效，有闪烁感。推荐升级到5.25的蒸汽模式，使用媒体查询方案适配主题。
+
+#### 内置组件和UI相关的API的说明
+
+uni-app x的App和Web平台框架中自带的界面，均已适配暗黑模式（小程序平台由小程序宿主自行适配）
+- uni.showActionSheet（HBuilderX 4.51+）
+- uni.showModal （HBuilderX 4.61+）
+- uni.chooseLocation （HBuilderX 4.33+）
+- uni.openLocation （HBuilderX 4.41+）
+- uni.chooseImage/chooseVideo/chooseMedia/chooseFile，当调用系统的选择界面时，该界面的主题跟随osTheme，应用层无法干预
+
+uni-app x的内置组件，在App和Web平台均支持css设置所有样式，这样就可以在所有样式控制中使用css变量。但小程序平台的内置组件，依赖其自身实现，有的组件需要通过属性控制样式，此时无法使用css变量。
+
+### 示例项目
+
+1. hello uni-app x示例目前使用媒体查询适配主题。其`app.uvue`、页面和组件样式中使用`@media (prefers-color-scheme: light)`和`@media (prefers-color-scheme: dark)`定义不同主题下的样式，`pages/CSS/prefers-color-scheme`页面提供了完整示例。
+2. [test-theme](https://gitcode.com/dcloud/test-theme)，是一个基于无媒体查询的、动态切换class的示例项目，演示主题设置。
+
+
+<!-- ## uni.setAppTheme(options) @setapptheme -->
+
+<!-- UTSAPIJSON.setAppTheme.name -->
+
+<!-- UTSAPIJSON.setAppTheme.description -->
+
+uni.setAppTheme用于设置App当前主题。开发者仍需为不同主题定义相应的页面和组件样式。它的作用是：
+1. 根据[theme.json](../collocation/themejson.md)，设置pages.json的亮/暗主题
+2. HBuilderX 5.25+，在App平台蒸汽模式下，自动更新`@media (prefers-color-scheme: light)`和`@media (prefers-color-scheme: dark)`匹配的样式
+3. 触发uni.onAppThemeChange，开发者和组件作者均可监听这个事件，自行响应将页面设置为对应的亮/暗风格。
+
+当然组件作者也可以不监听onAppThemeChange，而是暴露主题切换API给开发者，由开发者监听主题切换，再调用组件的主题切换API。
+
+uni-app x的UI相关的API（比如showModal），也会响应setAppTheme。
+
+<!-- UTSAPIJSON.setAppTheme.compatibility -->
+
+<!-- UTSAPIJSON.setAppTheme.param -->
+
+<!-- UTSAPIJSON.setAppTheme.returnValue -->
+
+```uts
+uni.setAppTheme({
+  theme: "auto",
+  success: function() {
+    console.log("设置appTheme为 auto 成功")
+  },
+  fail: function(e: IAppThemeFail) {
+    console.log("设置appTheme为 auto 失败,原因:", e.errMsg)
+  }
+})
+```
+
+<!-- UTSAPIJSON.setAppTheme.tutorial -->
+
+<!-- ## uni.onAppThemeChange(callback) @onappthemechange -->
+
+<!-- UTSAPIJSON.onAppThemeChange.name -->
+
+<!-- UTSAPIJSON.onAppThemeChange.description -->
+
+**版本历史调整**
+- HBuilderX 4.18版本的逻辑是：[uni.setAppTheme](#setapptheme) 设置的 theme 值变化时触发本监听回调，回调参数中的 appTheme 值可能是"light" | "dark" | "auto"。在 app 平台设置应用的 theme 值为 auto 后，需再次查询osTheme来判断当前的真实主题。如果应用主题是auto，那么需要同时监听osTheme的变化。
+- HBuilderX 4.19版本调整为：应用的light/dark主题真正发生变化时触发监听回调。无论是手动设置setAppTheme还是跟随osTheme变化，只要真正变化了就会触发本监听。回调参数中的 appTheme 值只能是"light" | "dark"。
+
+<!-- UTSAPIJSON.onAppThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.onAppThemeChange.param -->
+
+<!-- UTSAPIJSON.onAppThemeChange.returnValue -->
+
+```uts
+//callbackId 用于注销监听
+val callbackId = uni.onAppThemeChange((res: AppThemeChangeResult) => {
+  console.log("onAppThemeChange", res.appTheme)
+})
+```
+
+<!-- UTSAPIJSON.onAppThemeChange.tutorial -->
+
+<!-- ## uni.offAppThemeChange(id) @offappthemechange -->
+
+<!-- UTSAPIJSON.offAppThemeChange.name -->
+
+<!-- UTSAPIJSON.offAppThemeChange.description -->
+
+<!-- UTSAPIJSON.offAppThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.offAppThemeChange.param -->
+
+<!-- UTSAPIJSON.offAppThemeChange.returnValue -->
+
+```uts
+val callbackId = uni.onAppThemeChange((res: AppThemeChangeResult) => {
+  console.log("onAppThemeChange", res.appTheme)
+})
+//...
+//...
+//注销监听
+uni.offAppThemeChange(this.appThemeChangeId)
+```
+
+<!-- UTSAPIJSON.offAppThemeChange.tutorial -->
+
+<!-- ## uni.onOsThemeChange(callback) @onosthemechange -->
+
+<!-- UTSAPIJSON.onOsThemeChange.name -->
+
+<!-- UTSAPIJSON.onOsThemeChange.description -->
+
+<!-- UTSAPIJSON.onOsThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.onOsThemeChange.param -->
+
+<!-- UTSAPIJSON.onOsThemeChange.returnValue -->
+
+```uts
+//callbackId 用于注销监听
+val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> {
+    console.log("onOsThemeChange---", res.osTheme)
+})
+```
+
+<!-- UTSAPIJSON.onOsThemeChange.tutorial -->
+
+**注意：**
++ android 10、iOS 13 才开始支持深色模式主题 `dark`，更低版本无法获取、监听OS的主题。
++ iOS平台应用在进入后台时，会分别截取 app 在 light 和 dark 模式下的截图，用于系统主题切换的同时对后台 app 预览视图进行切换，所以会切换多次 light/dark 模式，程序正常响应 change 事件即可，否则系统截取的图片可能会出现异常，如果确实有必要忽略这种情况下的 change 事件可以在 onHide 后自行忽略。
+
+<!-- ## uni.offOsThemeChange(id) @offosthemechange -->
+
+<!-- UTSAPIJSON.offOsThemeChange.name -->
+
+<!-- UTSAPIJSON.offOsThemeChange.description -->
+
+<!-- UTSAPIJSON.offOsThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.offOsThemeChange.param -->
+
+<!-- UTSAPIJSON.offOsThemeChange.returnValue -->
+
+```uts
+val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> {
+    console.log("onOsThemeChange---", res.osTheme)
+})
+...
+...
+//注销监听
+uni.offOsThemeChange(callbackId)
+```
+
+<!-- UTSAPIJSON.offOsThemeChange.tutorial -->
+
+<!-- UTSAPIJSON.offOsThemeChange.example -->
+
+<!-- ## uni.onHostThemeChange(callback) @onhostthemechange -->
+
+<!-- UTSAPIJSON.onHostThemeChange.name -->
+
+<!-- UTSAPIJSON.onHostThemeChange.description -->
+
+<!-- UTSAPIJSON.onHostThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.onHostThemeChange.param -->
+
+<!-- UTSAPIJSON.onHostThemeChange.returnValue -->
+
+<!-- UTSAPIJSON.onHostThemeChange.tutorial -->
+
+<!-- UTSAPIJSON.onHostThemeChange.example -->
+
+<!-- ## uni.offHostThemeChange(id) @offhostthemechange -->
+
+<!-- UTSAPIJSON.offHostThemeChange.name -->
+
+<!-- UTSAPIJSON.offHostThemeChange.description -->
+
+<!-- UTSAPIJSON.offHostThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.offHostThemeChange.param -->
+
+<!-- UTSAPIJSON.offHostThemeChange.returnValue -->
+
+<!-- UTSAPIJSON.offHostThemeChange.tutorial -->
+
+<!-- UTSAPIJSON.offHostThemeChange.example -->
+
+<!-- UTSAPIJSON.onThemeChange.name -->
+
+<!-- UTSAPIJSON.onThemeChange.description -->
+
+<!-- UTSAPIJSON.onThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.onThemeChange.param -->
+
+<!-- UTSAPIJSON.onThemeChange.returnValue -->
+
+<!-- UTSAPIJSON.onThemeChange.tutorial -->
+
+<!-- UTSAPIJSON.onThemeChange.example -->
+
+<!-- UTSAPIJSON.offThemeChange.name -->
+
+<!-- UTSAPIJSON.offThemeChange.description -->
+
+<!-- UTSAPIJSON.offThemeChange.compatibility -->
+
+<!-- UTSAPIJSON.offThemeChange.param -->
+
+<!-- UTSAPIJSON.offThemeChange.returnValue -->
+
+<!-- UTSAPIJSON.offThemeChange.tutorial -->
+
+<!-- UTSAPIJSON.offThemeChange.example -->
+
+<!-- UTSAPIJSON.themeChange.example -->
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->

package/data/uni-app-x-docs/api/theme.md

@@ -0,0 +1,5 @@
+---
+layout: SimpleLayout
+---
+
+文档已迁移，请前往[themeChange](theme-change.md)查看最新文档

package/data/uni-app-x-docs/api/toast.md

@@ -0,0 +1,62 @@
+<!-- ## uni.showToast(options) @showtoast -->
+
+<!-- UTSAPIJSON.showToast.name -->
+
+<!-- UTSAPIJSON.showToast.description -->
+
+<!-- UTSAPIJSON.showToast.compatibility -->
+
+<!-- UTSAPIJSON.showToast.param -->
+
+<!-- UTSAPIJSON.showToast.returnValue -->
+
+<!-- UTSAPIJSON.showToast.example -->
+
+<!-- UTSAPIJSON.showToast.tutorial -->
+
+<!-- ## uni.hideToast() @hidetoast -->
+
+<!-- UTSAPIJSON.hideToast.name -->
+
+<!-- UTSAPIJSON.hideToast.description -->
+
+<!-- UTSAPIJSON.hideToast.compatibility -->
+
+<!-- UTSAPIJSON.hideToast.param -->
+
+<!-- UTSAPIJSON.hideToast.returnValue -->
+
+<!-- UTSAPIJSON.hideToast.example -->
+
+<!-- UTSAPIJSON.hideToast.tutorial -->
+
+<!-- UTSAPIJSON.toast.example -->
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->
+
+## Bug & Tips@tips
+- 在 iOS、微信小程序、Web 平台，showToast 是和页面（包括 dialogPage）绑定的
+- 在 Android 平台
+	* position 设为 bottom 时，为系统toast，此时与 App 绑定，而不是与页面绑定。position 不为 bottom 时仍与页面绑定
+	* 系统toast 不支持 icon 图标，仅支持文字
+	* 部分 Android ROM，如 MIUI，调用系统 toast 时，会在 toast 行首自动加上 App 图标。此为 ROM 行为，目的是帮助用户区分该 toast 是哪个 App 弹出的
+- 在 HarmonyOS 平台
+  - 5.24 及以下
+    - 只有系统 toast ，和 App window 绑定
+  	- 不支持 icon 图标，仅支持文字
+  - 5.25 及以上：
+  	* position 设为 bottom 时，为系统 toast。position 不为 bottom 时仍与页面绑定
+  	* 当 position 设为除 bottom 之外的值时，支持 icon、mask、image 参数
+- 当 Toast 和页面绑定时：
+  + 当showToast执行时，会寻找当前页面栈顶的窗体（包括 dialogPage），找到后进行绑定，然后弹出 Toast。
+	+ 在支持 dialogPage 的平台（Web和App），[uni.showModal](./modal.md)、[uni.showActionSheet](./action-sheet.md) 也是 dialogPage 实现的，此时 toast 会绑定到这些 dialogPage 上
+	+ 在弹出 Toast 后，再次打开新页面，新页面会覆盖原页面弹出的 Toast。
+		+ 如需在新页面（包括 dialogPage）弹出 Toast，需要再次调用 showToast
+  + 关闭页面（包括 dialogPage）时，Toast 会跟随页面（包括 dialogPage）一起消失
+		+ 如需在dialogPage关闭后，仍然弹出 Toast，需要在关闭dialogPage后再次调用 showToast
+- 当 Toast 和应用绑定时，也即系统 toast：
+	弹出和关闭页面，系统 toast 都不会跟随页面被遮挡或消失。
+- Android 11 及以上版本，应用进入后台后，调用系统 toast 不弹出。 [文档地址](https://developer.android.google.cn/about/versions/11/behavior-changes-11?hl=nb#toasts)
+- showToast 里的 Loading，和 showLoading 的区别是，showLoading 需要手动调用 HideLoading 才会关闭。而 showToast 里的 Loading 显示指定时间后会自动关闭。一般情况都需要精准控制关闭时机，所以大多使用 showLoading 和 hideLoading