diff --git a/docs/api/theme.md b/docs/api/theme.md
index 9afac5d247e1b601609263dce04ed3d2518bbe19..932bd5d9bd14d82244babcba03e0be6d7e7ab366 100644
--- a/docs/api/theme.md
+++ b/docs/api/theme.md
@@ -1,21 +1,21 @@
 ## uni.setAppTheme(options) @setapptheme
 
 <!-- UTSAPIJSON.setAppTheme.description -->
-
-uni.setAppTheme，并不会帮助开发者自动实现整个应用的亮/暗主题切换，它的作用是：
-1. 根据[theme.json](../collocation/themejson.md)，设置pages.json的亮/暗主题
-2. 触发uni.onAppThemeChange，开发者和组件作者均可监听这个事件，自行响应将页面设置为对应的亮/暗风格。
-
-当然组件作者也可以不监听onAppThemeChange，而是暴露主题切换API给开发者，由开发者监听主题切换，再调用组件的主题切换API。
-
-目前uni-app x的内置组件和UI相关的API（比如showModal），并不会响应setAppTheme。组件是暴露了样式属性供开发者自行设置，Modal相关API目前没有样式设置，后续会升级支持。
+
+uni.setAppTheme，并不会帮助开发者自动实现整个应用的亮/暗主题切换，它的作用是：
+1. 根据[theme.json](../collocation/themejson.md)，设置pages.json的亮/暗主题
+2. 触发uni.onAppThemeChange，开发者和组件作者均可监听这个事件，自行响应将页面设置为对应的亮/暗风格。
+
+当然组件作者也可以不监听onAppThemeChange，而是暴露主题切换API给开发者，由开发者监听主题切换，再调用组件的主题切换API。
+
+目前uni-app x的内置组件和UI相关的API（比如showModal），并不会响应setAppTheme。组件是暴露了样式属性供开发者自行设置，Modal相关API目前没有样式设置，后续会升级支持。
 
 <!-- UTSAPIJSON.setAppTheme.compatibility -->
 
 <!-- UTSAPIJSON.setAppTheme.param -->
 
-<!-- UTSAPIJSON.setAppTheme.returnValue -->
-
+<!-- UTSAPIJSON.setAppTheme.returnValue -->
+
 ```uts
 uni.setAppTheme({
   theme: "auto",
@@ -30,6 +30,51 @@ uni.setAppTheme({
 
 <!-- UTSAPIJSON.setAppTheme.tutorial -->
 
+## uni.onAppThemeChange(callback) @onappthemechange
+
+<!-- UTSAPIJSON.onAppThemeChange.description -->
+
+**注意**  
+- HBuilderX4.18版本为 [uni.setAppTheme](#setapptheme) 设置的 theme 值变化时触发监听回调，回调参数中的 appTheme 值可能是"light" | "dark" | "auto"。在 app 平台设置应用的 theme 值为 auto 后，需同时使用 [uni.onOsThemeChange](#onOsThemeChange) 监听系统主题变化来计算应用使用的主题。  
+- HBuilderX4.19版本调整为 应用实际计算后使用的主题值发生变化时才触发监听回调，回调参数中的 appTheme 值只可能是"light" | "dark"。 在 app 平台设置应用的 theme 值为 auto 后，当系统主题发生变化时会自动计算决定是否触发回调，也就是说无需使用 [uni.onOsThemeChange](#onOsThemeChange) 监听系统主题变化。  
+
+<!-- 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.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.description -->
@@ -38,17 +83,17 @@ uni.setAppTheme({
 
 <!-- UTSAPIJSON.onOsThemeChange.param -->
 
-<!-- UTSAPIJSON.onOsThemeChange.returnValue -->
-
+<!-- UTSAPIJSON.onOsThemeChange.returnValue -->
+
 ```uts
-//callbackId 用于注销监听
+//callbackId 用于注销监听
 val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> {
     console.log("onOsThemeChange---", res.osTheme)
 })
 ```
 
-<!-- UTSAPIJSON.onOsThemeChange.tutorial -->
-
+<!-- UTSAPIJSON.onOsThemeChange.tutorial -->
+
 **注意：**
 + android 10、iOS 13 才开始支持深色模式主题 `dark`，更低版本无法获取、监听OS的主题。
 
@@ -60,61 +105,20 @@ val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> {
 
 <!-- UTSAPIJSON.offOsThemeChange.param -->
 
-<!-- UTSAPIJSON.offOsThemeChange.returnValue -->
-
-```uts
+<!-- UTSAPIJSON.offOsThemeChange.returnValue -->
+
+```uts
 val callbackId = uni.onOsThemeChange((res: OsThemeChangeResult)=> {
     console.log("onOsThemeChange---", res.osTheme)
-})
-...
-...
-//注销监听
-uni.offOsThemeChange(callbackId)
+})
+...
+...
+//注销监听
+uni.offOsThemeChange(callbackId)
 ```
 
 <!-- UTSAPIJSON.offOsThemeChange.tutorial -->
 
-## uni.onAppThemeChange(callback) @onappthemechange
-
-<!-- UTSAPIJSON.onAppThemeChange.description -->
-
-<!-- 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.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 -->
-
 <!-- UTSAPIJSON.general_type.name -->
 
 <!-- UTSAPIJSON.general_type.param -->