tmui-cli 2.0.3 → 2.0.4

package/data/uni-app-x-docs/collocation/pagesjson.md

@@ -0,0 +1,462 @@
+# pages.json
+
+`pages.json` 文件是 uni-app x 的页面管理配置文件，决定**应用的首页**、页面文件的路径、窗口样式、原生的导航栏、底部的原生tabbar 等。
+
+**所有页面，均需在pages.json中注册，否则不会被打包到应用中。**
+
+在HBuilderX中新建页面，默认会在pages.json中自动注册。在HBuilderX中删除页面文件，也会在状态栏提示从pages.json中移除注册。
+
+除了管理页面，pages.json支持对页面进行特殊配置，比如应用首页的tabbar、每个页面的顶部导航栏设置。
+
+但这些uni-app中设计的功能，主要是为了解决页面由webview渲染带来的性能问题，由原生提供一些配置来优化。
+
+uni-app x的app平台，页面不再由webview渲染，其实不需要原生提供特殊配置来优化。但为了开发的便利和多端的统一，也支持了tabbar和导航栏设置。\
+但uni-app x不再支持uni-app的app-plus专用配置以及tabbar的midbutton。这些额外的功能，通过[uni-ui x](https://doc.dcloud.net.cn/uni-app-x/component/uni-ui-x/)的自定义导航栏和tabbar组件来满足。
+- 自定义导航栏：  [uni-nav-bar](https://doc.dcloud.net.cn/uni-app-x/component/uni-ui-x/uni-nav-bar.html)
+- 自定义tabbar：[uni-tab-bar](https://doc.dcloud.net.cn/uni-app-x/component/uni-ui-x/uni-tab.html)
+
+导航栏高度为 44px (不含状态栏)，tabBar 高度为 50px (不含安全区)。
+
+## 配置项列表
+
+<!-- PAGESJSON.pages.description -->
+
+<!-- PAGESJSON.pages.compatibility -->
+
+<!-- PAGESJSON.pages.table -->
+
+### globalStyle 配置项列表 @pages-globalstyle
+
+globalStyle节点里是所有页面都生效的全局样式配置。它的配置与页面级style基本相同，但优先级低于页面级style配置。
+
+<!-- PAGESJSON.globalStyle.description -->
+
+<!-- PAGESJSON.globalStyle.compatibility -->
+
+<!-- PAGESJSON.globalStyle.table -->
+
+#### h5 配置项列表 @globalstyle-h5
+
+<!-- PAGESJSON.globalStyle_h5.description -->
+
+<!-- PAGESJSON.globalStyle_h5.compatibility -->
+
+<!-- PAGESJSON.globalStyle_h5.table -->
+
+##### titleNView 配置项列表 @h5-titlenview
+
+<!-- PAGESJSON.globalStyle_h5_titleNView.description -->
+
+<!-- PAGESJSON.globalStyle_h5_titleNView.compatibility -->
+
+<!-- PAGESJSON.globalStyle_h5_titleNView.table -->
+
+##### pullToRefresh 配置项列表 @h5-pulltorefresh
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh.description -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh.compatibility -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh.table -->
+
+
+###### contentdown 配置项列表 @pulltorefresh-contentdown
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentdown.description -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentdown.compatibility -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentdown.table -->
+
+
+###### contentover 配置项列表 @pulltorefresh-contentover
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentover.description -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentover.compatibility -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentover.table -->
+
+###### contentrefresh 配置项列表 @pulltorefresh-contentrefresh
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentrefresh.description -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentrefresh.compatibility -->
+
+<!-- PAGESJSON.globalStyle_h5_pullToRefresh_contentrefresh.table -->
+
+
+#### mp-alipay 配置项列表 @globalstyle-mp-alipay
+
+<!-- PAGESJSON.globalStyle_mp-alipay.description -->
+
+<!-- PAGESJSON.globalStyle_mp-alipay.compatibility -->
+
+<!-- PAGESJSON.globalStyle_mp-alipay.table -->
+
+
+#### mp-weixin 配置项列表 @globalstyle-mp-weixin
+
+<!-- PAGESJSON.globalStyle_mp-weixin.description -->
+
+<!-- PAGESJSON.globalStyle_mp-weixin.compatibility -->
+
+<!-- PAGESJSON.globalStyle_mp-weixin.table -->
+
+### pages 配置项列表 @pagesoptionspage
+
+pages节点里注册页面，数据格式是数组，数组每个项都是一个对象，通过path属性指定页面路径，通过style指定该页面的样式配置。
+
+<!-- PAGESJSON.PagesOptionsPage.description -->
+
+<!-- PAGESJSON.PagesOptionsPage.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsPage.table -->
+
+**Tips：**
+
+- **pages节点的第一项为应用入口页（即首页）**
+- **应用中新增/减少页面**，都需要对 pages 数组进行修改
+- 文件名**不需要写后缀**，框架会自动寻找路径下的页面资源
+- 页面路径必须与真实的文件路径大小写保持一致，即**大小写敏感**
+
+**示例**
+
+假使开发目录为：
+
+<pre v-pre="" data-lang="">
+	<code class="lang-" style="padding:0">
+┌─pages
+│  ├─index
+│  │  └─index.uvue
+│  └─login
+│     └─login.uvue
+├─static
+├─main.uts
+├─App.uvue
+├─manifest.json
+└─pages.json
+	</code>
+</pre>
+
+则需要在 pages.json 中填写
+
+```json
+{
+    "pages": [
+        {
+            "path": "pages/index/index",
+            "style": { ... }
+        }, {
+            "path": "pages/login/login",
+            "style": { ... }
+        }
+    ]
+}
+```
+
+
+#### style 配置项列表 @pagesoptionspage-style
+
+用于设置每个页面的状态栏、导航条的颜色、文字等信息。
+
+页面中配置项会覆盖 [globalStyle](#pages-globalstyle) 中相同的配置项
+
+<!-- PAGESJSON.PagesOptionsPage_style.description -->
+
+<!-- PAGESJSON.PagesOptionsPage_style.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsPage_style.table -->
+
+<a id="pagesoptionspage-tips"></a>
+
+**Tips**
+- 横屏
+	* Web：横竖屏由手机浏览器控制，无法在pages.json中指定。uni-app x的页面和基础组件都支持自适应宽屏界面
+	* Android：默认是竖屏。从4.13起支持配置pageOrientation实现横屏或自动旋转适应
+	* iOS：在iPhone手机上默认竖屏，在iPad上默认自动旋转适应。从4.25起iPhone设置支持配置pageOrientation，iPad设备不受pageOrientation配置影响（表现为自动旋转适配），如需在iPad设备固定某个方向可以在项目的 Info.plist 中配置应用可支持的横竖屏列表来配置，详见[应用可支持横竖屏列表配置](https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-ios.html#orientation)，配置后应用将限定在可支持的横竖屏列表中配置的值（如配置应用可支持的列表仅为横屏，则应用只能显示为横屏）。uni-app x的页面和基础组件都支持自适应宽屏界面
+- 状态栏
+	* 手机顶部状态栏的背景色、前景色(white/black)与navigationBarBackgroundColor和navigationBarTextStyle相同
+	* 小程序平台，pages.json中各个颜色的设置仅支持普通的16进制数值。App和Web支持设为transparent，即透明。
+	* 如需动态设置状态栏颜色，使用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)的下拉刷新。
+- Android系统导航栏 (通常指手机底部按钮或手势指示条区域)
+	* 系统导航栏的背景颜色与backgroundColorContent颜色一致，导航栏的前景色会根据backgroundColorContent颜色自动适配 (4.21版本开始支持)
+	* tabBar页面的系统导航栏背景颜色取值策略[参考](#tabbar-tips)
+	* 系统导航栏为全面屏手势时，HBuilderX4.31版本调整页面内容可以渲染到手势指示条区域（低版本页面内容会自动避开手势指示条区域），如需适配可以通过[uni.getWindowInfo](../api/get-window-info.md)获取安全区域底部插入位置信息进行适配
+	* HBuilderX4.41版本起，App-Android平台支持配置页面内容是否渲染到虚拟按键区域，但横屏时会默认渲染到该区域且无法修改此行为，属于当前版本遗留问题，后续修复。
+
+**style示例**
+```javascript
+{
+  "pages": [{
+      "path": "pages/index/index",
+      "style": {
+        "navigationBarTitleText": "首页",//设置页面标题文字
+        "enablePullDownRefresh":true//开启下拉刷新
+      }
+    },
+    ...
+  ]
+}
+```
+
+##### navigationBarShadow 配置项列表 @style-navigationbarshadow
+
+<!-- PAGESJSON.PagesOptionsPage_style_navigationBarShadow.description -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_navigationBarShadow.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_navigationBarShadow.table -->
+
+#### 页面背景色@background
+- 页面容器背景色：可在页面 json 文件中通过 backgroundColorContent 属性配置，支持 #RRGGBB 写法，默认为白色
+- 窗口背景色：可在页面 json 文件中通过 backgroundColor 属性配置，支持 #RRGGBB 写法，默认为白色。被页面容器背景色覆盖，仅在页面设置下拉刷新时才可能看到此颜色
+
+##### h5 配置项列表 @style-h5
+
+<!-- PAGESJSON.PagesOptionsPage_style_h5.description -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_h5.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_h5.table -->
+
+
+##### mp-alipay 配置项列表 @style-mp-alipay
+
+<!-- PAGESJSON.PagesOptionsPage_style_mp-alipay.description -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_mp-alipay.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_mp-alipay.table -->
+
+
+##### mp-weixin 配置项列表 @style-mp-weixin
+
+<!-- PAGESJSON.PagesOptionsPage_style_mp-weixin.description -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_mp-weixin.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsPage_style_mp-weixin.table -->
+
+
+### tabBar 配置项列表 @pages-tabbar
+
+tabbar节点用于配置应用的tabbar，仅支持配置一个。如需在更多页面配置tabbar，见下面的自定义tabbar。
+
+<!-- PAGESJSON.tabBar.description -->
+
+<!-- PAGESJSON.tabBar.compatibility -->
+
+<!-- PAGESJSON.tabBar.table -->
+
+<a id="tabbar-tips"></a>
+
+**Tips**
+- backgroundColor
+	- app-android平台：系统导航（System navigation）栏的背景色会与 tabBar 背景色保持一致。如果应用没有配置 tabBar 页面导航栏背景颜色取值策略[参考](#pagesoptionspage-tips)
+	- app-ios平台：tabBar 会自动适配安全区域，底部安全区域背景色会与 tabBar 背景色保持一致。如果应用没有配置 tabBar，则不会自动适配底部安全区域，开发者需根据应用实际情况自行处理。
+
+- 自定义tabbar：[uni-tab-bar](https://doc.dcloud.net.cn/uni-app-x/component/uni-ui-x/uni-tab.html)
+自定义tabbar的核心逻辑：
+    1. tabbar页面刚开始只载入第一个子tab组件，其他tab组件是在点击相应的选项卡时v-if设为true来创建
+    2. 一个子tab一旦被v-if加载后，不要再v-if设为false去掉，也不通过v-show控制，而是通过css的visibility来控制显示和隐藏。这样可以保留每个子tab的状态，比如滚动位置、输入框内容。切换tab也会更快速。
+
+- tabbar的glassEffect（液态玻璃效果）
+	- 启用 glassEffect 后，iOS 所有支持版本均使用系统 UITabBar，iOS26 及以上 backgroundColor、borderStyle、color 和 height 属性将无效，玻璃材质的具体表现由系统版本决定。
+	- 启用 glassEffect 后，tabbar 以悬浮方式覆盖在页面内容上方。页面不再以 tabbar 顶部作为底部边界，而是延伸到屏幕底部。iOS 26 以下降级为毛玻璃 tabbar 时，页面布局行为保持一致，对应变化如下：
+        - 页面排版高度包含 TabBar 覆盖区域。
+		- UniPage.height 返回页面延伸到屏幕底部后的高度。
+		- uni.getWindowInfo() 和 uni.getSystemInfo() 保持现有实现，不额外将悬浮 TabBar 计入系统安全区。
+		- UniPage.safeAreaInsets.bottom 在 TabBar 显示时返回页面底部需要避让的完整距离，包含悬浮 TabBar 及系统底部安全区。
+		- UniPage.safeArea 根据上述页面安全区同步调整。
+		- CSS 变量 env(safe-area-inset-bottom) 和 --uni-safe-area-inset-bottom 与 UniPage.safeAreaInsets.bottom 保持一致。
+		- 显示或隐藏悬浮 TabBar 不改变页面高度，因此不会仅因 TabBar 显隐触发页面尺寸变化。
+		- 隐藏 TabBar 后，页面底部安全区恢复为系统原始安全区。
+	- 液态玻璃（Liquid Glass）是iOS26起提供的专有技术，如果开发者想在其他平台也使用悬浮毛玻璃tabbar，可以条件编译，在非iOS平台下使用 css 的 backdrop-filter。uni-ui x 中的 [uni-tab-bar](https://doc.dcloud.net.cn/uni-app-x/component/uni-ui-x/uni-tab.html) 的已提供毛玻璃示例。使用毛玻璃tabbar时，页面统一通顶，tabbar悬浮在安全区上方。但注意自定义tabbar的选项卡是组件而不是页面。
+
+#### PagesOptionsTabbarList 配置项列表 @pagesoptionstabbarlist
+
+<!-- PAGESJSON.PagesOptionsTabbarList.description -->
+
+<!-- PAGESJSON.PagesOptionsTabbarList.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsTabbarList.table -->
+
+**tabbar示例**
+```json
+"tabBar": {
+	"color": "#7A7E83",
+	"selectedColor": "#3cc51f",
+	"borderStyle": "black",
+	"backgroundColor": "#ffffff",
+	"list": [{
+		"pagePath": "pages/component/index",
+		"iconPath": "static/image/icon_component.png",
+		"selectedIconPath": "static/image/icon_component_HL.png",
+		"text": "组件"
+	}, {
+		"pagePath": "pages/API/index",
+		"iconPath": "static/image/icon_API.png",
+		"selectedIconPath": "static/image/icon_API_HL.png",
+		"text": "接口"
+	}]
+}
+```
+
+##### iconfont 配置项列表 @pagesoptionstabbarlist-iconfont
+
+<!-- PAGESJSON.PagesOptionsTabbarList_iconfont.description -->
+
+<!-- PAGESJSON.PagesOptionsTabbarList_iconfont.compatibility -->
+
+<!-- PAGESJSON.PagesOptionsTabbarList_iconfont.table -->
+
+#### midButton 配置项列表 @tabbar-midbutton
+
+<!-- PAGESJSON.tabBar_midButton.description -->
+
+<!-- PAGESJSON.tabBar_midButton.compatibility -->
+
+<!-- PAGESJSON.tabBar_midButton.table -->
+
+### topWindow 配置项列表 @pages-topwindow
+
+<!-- PAGESJSON.topWindow.description -->
+
+<!-- PAGESJSON.topWindow.compatibility -->
+
+<!-- PAGESJSON.topWindow.table -->
+
+#### matchMedia 配置项列表 @topwindow-matchmedia
+
+<!-- PAGESJSON.topWindow_matchMedia.description -->
+
+<!-- PAGESJSON.topWindow_matchMedia.compatibility -->
+
+<!-- PAGESJSON.topWindow_matchMedia.table -->
+
+### leftWindow 配置项列表 @pages-leftwindow
+
+<!-- PAGESJSON.leftWindow.description -->
+
+<!-- PAGESJSON.leftWindow.compatibility -->
+
+<!-- PAGESJSON.leftWindow.table -->
+
+#### matchMedia 配置项列表 @leftwindow-matchmedia
+
+<!-- PAGESJSON.leftWindow_matchMedia.description -->
+
+<!-- PAGESJSON.leftWindow_matchMedia.compatibility -->
+
+<!-- PAGESJSON.leftWindow_matchMedia.table -->
+
+### rightWindow 配置项列表 @pages-rightwindow
+
+<!-- PAGESJSON.rightWindow.description -->
+
+<!-- PAGESJSON.rightWindow.compatibility -->
+
+<!-- PAGESJSON.rightWindow.table -->
+
+#### matchMedia 配置项列表 @rightwindow-matchmedia
+
+<!-- PAGESJSON.rightWindow_matchMedia.description -->
+
+<!-- PAGESJSON.rightWindow_matchMedia.compatibility -->
+
+<!-- PAGESJSON.rightWindow_matchMedia.table -->
+
+### condition 配置项列表 @pages-condition
+
+启动模式配置，仅开发期间生效，用于模拟直达页面的场景。教程[详见](https://uniapp.dcloud.net.cn/collocation/pages.html#condition)
+
+<!-- PAGESJSON.condition.description -->
+
+<!-- PAGESJSON.condition.compatibility -->
+
+<!-- PAGESJSON.condition.table -->
+
+#### PagesConditionItem 配置项列表 @pagesconditionitem
+
+<!-- PAGESJSON.PagesConditionItem.description -->
+
+<!-- PAGESJSON.PagesConditionItem.compatibility -->
+
+<!-- PAGESJSON.PagesConditionItem.table -->
+
+
+
+### easycom 配置项列表 @pages-easycom
+
+easycom是uni-app提供的一种简化组件使用的方式。一般情况下组件放置在符合规范的位置时即可自动引用。
+
+但有时组件的路径或文件名无法满足easycom默认规范要求，可以在pages.json里进行规则的自定义。
+
+自定义easycom的详细教程[详见](https://uniapp.dcloud.net.cn/collocation/pages.html#easycom)
+
+<!-- PAGESJSON.easycom.description -->
+
+<!-- PAGESJSON.easycom.compatibility -->
+
+<!-- PAGESJSON.easycom.table -->
+
+### uniIdRouter 配置项列表 @pages-uniidrouter
+
+<!-- PAGESJSON.uniIdRouter.description -->
+
+<!-- PAGESJSON.uniIdRouter.compatibility -->
+
+<!-- PAGESJSON.uniIdRouter.table -->
+
+
+### subPackages 配置项列表 @pagessubpackages
+
+分包加载配置，此配置为小程序的分包加载机制。详细教程[详见](https://uniapp.dcloud.net.cn/collocation/pages.html#subpackages)
+
+subPackages 节点接收一个数组，数组每一项都是应用的子包，其属性值如下：
+
+<!-- PAGESJSON.PagesSubPackages.description -->
+
+<!-- PAGESJSON.PagesSubPackages.compatibility -->
+
+<!-- PAGESJSON.PagesSubPackages.table -->
+
+#### SubPackagePagesOptionsPage 配置项列表 @subpackagepagesoptionspage
+
+<!-- PAGESJSON.SubPackagePagesOptionsPage.description -->
+
+<!-- PAGESJSON.SubPackagePagesOptionsPage.compatibility -->
+
+<!-- PAGESJSON.SubPackagePagesOptionsPage.table -->
+
+##### style 配置项列表 @subpackagepagesoptionspage-style
+
+<!-- PAGESJSON.SubPackagePagesOptionsPage_style.description -->
+
+<!-- PAGESJSON.SubPackagePagesOptionsPage_style.compatibility -->
+
+<!-- PAGESJSON.SubPackagePagesOptionsPage_style.table -->
+
+### preloadRule 配置项列表 @pages-preloadrule
+
+分包预载配置。
+
+配置preloadRule后，在进入小程序某个页面时，由框架自动预下载可能需要的分包，提升进入后续分包页面时的启动速度
+
+preloadRule 中，key 是页面路径，value 是进入此页面的预下载配置，每个配置有以下几项：
+
+<!-- PAGESJSON.preloadRule.description -->
+
+<!-- PAGESJSON.preloadRule.compatibility -->
+
+<!-- PAGESJSON.preloadRule.table -->
+
+<!-- PAGESJSON.tutorial -->

package/data/uni-app-x-docs/collocation/themejson.md

@@ -0,0 +1,177 @@
+# theme.json
+
+> HBuilder X 4.18+ 支持
+
+完整的主题适配教程 [另见](../api/theme-change.md)。
+
+本文仅讲解theme.json的用法，用于解决pages.json的主题适配问题。
+
+当app需要暗黑主题时，开发者虽然可以自行决定自己的界面样式，但缺少合适的设置pages.json中样式的时机。
+
+在页面的onLoad中设置当前页面的style会来不及，因为某些平台页面早于onLoad就可以创建和进行窗体转场动画，\
+这会造成新页面动画刚开始页面的背景色、navigationBar背景色是一个风格，而在onLoad后颜色发生变化。\
+也就是俗称的 转场闪白 或 闪黑。
+
+小程序提供了theme.json来给解决这个问题。在theme.json里配置light和dark的颜色，然后在pages.json中引用。
+
+新页面创建时是根据pages.json的设置来初始化页面的，这样就可以在第一时间对页面样式进行适配，避免闪白闪黑。
+
+考虑到全端兼容，uni-app x的web和app也支持theme.json设置。
+
+但需要注意：**theme.json，仅负责pages.json的页面样式、tabbar样式的控制。不负责开发者自己的页面css样式控制。**
+
+适配暗黑模式，除通过theme.json控制pages.json的样式外，还需要了解更多API：
+- 获取OS/Host主题：[uni.getSystemInfo](../api/get-system-info.md)、[uni.getDeviceInfo](../api/get-device-info.md)，返回的osTheme、hostTheme属性
+- 监听OS主题切换：[uni.onOsThemeChange](../api/theme-change.md#onosthemechange)、[uni.offOsThemeChange](../api/theme-change.md#offosthemechange)、
+- 监听host主题切换：[uni.onHostThemeChange](../api/theme-change.md#onhostthemechange)、[uni.offHostThemeChange](../api/theme-change.md#offhostthemechange)、
+- 获取App主题：[uni.getSystemInfo](../api/get-system-info.md)、[uni.getAppBaseInfo](../api/get-app-base-info.md)，返回的appTheme属性
+- 设置App主题：[uni.setAppTheme](../api/theme-change.md#setapptheme)
+- 监听App主题切换：[uni.onAppThemeChange](../api/theme-change.md#onappthemechange)、[uni.offAppThemeChange](../api/theme-change.md#offappthemechange)、
+- manifest.json中设置App默认主题：[defaultAppTheme](../collocation/manifest.md#manifest-app)
+
+## theme.json使用步骤
+
+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` 用于颜色主题相关的变量定义，包含以下属性：
+
+| 属性  | 类型   | 必填 | 描述                 |
+| :---- | :----- | :--- | :------------------- |
+| light | Object | 是   | 浅色模式下的变量定义 |
+| dark  | Object | 是   | 深色模式下的变量定义 |
+
+示例如下：
+
+```json
+{
+	"light": {
+		"navBgColor": "#f8f8f8",
+		"navTxtStyle": "black"
+	},
+	"dark": {
+		"navBgColor": "#292929",
+		"navTxtStyle": "white"
+	}
+}
+```
+
+完成定义后，可在 `pages.json` 中全局配置或页面配置的相关属性中以 `@` 开头引用，例如：
+
+```json
+// 全局配置
+{
+  "globalStyle": {
+    "navigationBarBackgroundColor": "@navBgColor",
+    "navigationBarTextStyle": "@navTxtStyle"
+  }
+}
+// 页面配置
+{
+	"path": "pages/index/index",
+	"style":{
+		"navigationBarBackgroundColor": "@navBgColor",
+		"navigationBarTextStyle": "@navTxtStyle"
+	}
+}
+```
+
+配置完成后，调用相应 api 框架会自动所设属性，展示对应主题下的颜色。
+
+pages.json中并非所有配置项均支持使用theme.json中的变量，支持通过变量配置的属性如下所示：
+
+- 全局配置 globalStyle 与页面 style 支持：
+
+  - navigationBarBackgroundColor
+  - navigationBarTextStyle
+  - backgroundColor
+  - backgroundTextStyle
+
+- 全局配置 tabbar 属性：
+  - color
+  - selectedColor
+  - backgroundColor
+  - borderStyle
+  - list
+    - iconPath
+    - selectedIconPath
+
+## 配置示例@themeconfig
+
+pages.json（示例省略了主题相关以外的配置项）
+
+```json
+{
+	"globalStyle": {
+		"navigationBarBackgroundColor": "@navBgColor",
+		"navigationBarTextStyle": "@navTxtStyle",
+		"backgroundColor": "@bgColor",
+		"backgroundTextStyle": "@bgTxtStyle"
+	},
+	"tabBar": {
+		"color": "@tabFontColor",
+		"selectedColor": "@tabSelectedColor",
+		"backgroundColor": "@tabBgColor",
+		"borderStyle": "@tabBorderStyle",
+		"list": [
+			{
+				"iconPath": "@iconPath1",
+				"selectedIconPath": "@selectedIconPath1"
+			},
+			{
+				"iconPath": "@iconPath2",
+				"selectedIconPath": "@selectedIconPath2"
+			}
+		]
+	}
+}
+```
+
+theme.json
+
+```json
+{
+	"light": {
+		"navBgColor": "#f8f8f8",
+		"navTxtStyle": "black",
+		"bgColor": "#ffffff",
+		"bgTxtStyle": "light",
+		"bgColorTop": "#eeeeee",
+		"bgColorBottom": "#efefef",
+		"tabFontColor": "#000000",
+		"tabSelectedColor": "#3cc51f",
+		"tabBgColor": "#ffffff",
+		"tabBorderStyle": "black",
+		"iconPath1": "/static/icon1_light.png",
+		"selectedIconPath1": "/static/selected_icon1_light.png",
+		"iconPath2": "/static/icon2_light.png",
+		"selectedIconPath2": "/static/selected_icon2_light.png"
+	},
+	"dark": {
+		"navBgColor": "#292929",
+		"navTxtStyle": "white",
+		"bgColor": "#1f1f1f",
+		"bgTxtStyle": "dark",
+		"bgColorTop": "#292929",
+		"bgColorBottom": "#1f1f1f",
+		"tabFontColor": "#ffffff",
+		"tabSelectedColor": "#51a937",
+		"tabBgColor": "#292929",
+		"tabBorderStyle": "white",
+		"iconPath1": "/static/icon1_dark.png",
+		"selectedIconPath1": "/static/selected_icon1_dark.png",
+		"iconPath2": "/static/icon2_dark.png",
+		"selectedIconPath2": "/static/selected_icon2_dark.png"
+	}
+}
+```
+
+在[hello uni-app x](https://hellouniappx.dcloud.net.cn/)中，已经配置了theme.json，在 api 的主题切换示例中，可以体验。
+
+**注意：**
+- `iOS 13+`、`Android 10+`设备上才支持暗黑模式