Merge branch 'main' into main

DreamOfIce · web-flow · commit ee9bc5c90c79 · 2025-09-04T16:50:34.000+08:00
diff --git a/examples/mini-program-example/src/pages/api/taro/hooks/index.tsx b/examples/mini-program-example/src/pages/api/taro/hooks/index.tsx
@@ -96,6 +96,10 @@ export default class Index extends React.Component {
         id: 'useOptionMenuClick',
         func: null,
       },
+      {
+        id: 'useKeyboardHeight',
+        func: null,
+      },
       {
         id: 'usePullIntercept',
         func: null,
diff --git a/packages/shared/src/runtime-hooks.ts b/packages/shared/src/runtime-hooks.ts
@@ -95,6 +95,7 @@ const defaultMiniLifecycle: MiniLifecycle = {
       'defer:onTabItemTap', // defer: 需要等页面组件挂载后再调用
       'onTitleClick',
       'onOptionMenuClick',
+      'events:onKeyboardHeight', // events: 支付宝平台需要挂载到 config.events 上
       'onPopMenuClick',
       'onPullIntercept',
       'onAddToFavorites'
diff --git a/packages/taro-framework-react/src/api-loader.ts b/packages/taro-framework-react/src/api-loader.ts
@@ -7,6 +7,7 @@ export default function (str: string) {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
@@ -33,6 +34,7 @@ taro.useError = useError
 taro.useLaunch = useLaunch
 taro.useLoad = useLoad
 taro.useOptionMenuClick = useOptionMenuClick
+taro.useKeyboardHeight = useKeyboardHeight
 taro.usePageNotFound = usePageNotFound
 taro.usePageScroll = usePageScroll
 taro.usePullDownRefresh = usePullDownRefresh
@@ -58,6 +60,7 @@ export {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
diff --git a/packages/taro-framework-react/src/runtime/hooks.ts b/packages/taro-framework-react/src/runtime/hooks.ts
@@ -78,6 +78,7 @@ export const useUnload = createTaroHook('onUnload')
 /** Mini-Program */
 export const useAddToFavorites = createTaroHook('onAddToFavorites')
 export const useOptionMenuClick = createTaroHook('onOptionMenuClick')
+export const useKeyboardHeight = createTaroHook('onKeyboardHeight')
 export const useSaveExitState = createTaroHook('onSaveExitState')
 export const useShareAppMessage = createTaroHook('onShareAppMessage')
 export const useShareTimeline = createTaroHook('onShareTimeline')
diff --git a/packages/taro-framework-solid/src/api-loader.ts b/packages/taro-framework-solid/src/api-loader.ts
@@ -7,6 +7,7 @@ export default function (str: string) {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
@@ -33,6 +34,7 @@ taro.useError = useError
 taro.useLaunch = useLaunch
 taro.useLoad = useLoad
 taro.useOptionMenuClick = useOptionMenuClick
+taro.useKeyboardHeight = useKeyboardHeight
 taro.usePageNotFound = usePageNotFound
 taro.usePageScroll = usePageScroll
 taro.usePullDownRefresh = usePullDownRefresh
@@ -58,6 +60,7 @@ export {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
diff --git a/packages/taro-framework-solid/src/runtime/hooks.ts b/packages/taro-framework-solid/src/runtime/hooks.ts
@@ -79,6 +79,7 @@ export const useUnload = createTaroHook('onUnload')
 /** Mini-Program */
 export const useAddToFavorites = createTaroHook('onAddToFavorites')
 export const useOptionMenuClick = createTaroHook('onOptionMenuClick')
+export const useKeyboardHeight = createTaroHook('onKeyboardHeight')
 export const useSaveExitState = createTaroHook('onSaveExitState')
 export const useShareAppMessage = createTaroHook('onShareAppMessage')
 export const useShareTimeline = createTaroHook('onShareTimeline')
diff --git a/packages/taro-framework-vue3/src/api-loader.ts b/packages/taro-framework-vue3/src/api-loader.ts
@@ -8,6 +8,7 @@ export default function (str: string) {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
@@ -35,6 +36,7 @@ taro.useLaunch = useLaunch
 taro.setGlobalDataPlugin = setGlobalDataPlugin
 taro.useLoad = useLoad
 taro.useOptionMenuClick = useOptionMenuClick
+taro.useKeyboardHeight = useKeyboardHeight
 taro.usePageNotFound = usePageNotFound
 taro.usePageScroll = usePageScroll
 taro.usePullDownRefresh = usePullDownRefresh
@@ -60,6 +62,7 @@ export {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
diff --git a/packages/taro-framework-vue3/src/runtime/composition-functions.ts b/packages/taro-framework-vue3/src/runtime/composition-functions.ts
@@ -81,6 +81,7 @@ export const useUnload = createTaroHook('onUnload')
 /** Mini-Program */
 export const useAddToFavorites = createTaroHook('onAddToFavorites')
 export const useOptionMenuClick = createTaroHook('onOptionMenuClick')
+export const useKeyboardHeight = createTaroHook('onKeyboardHeight')
 export const useSaveExitState = createTaroHook('onSaveExitState')
 export const useShareAppMessage = createTaroHook('onShareAppMessage')
 export const useShareTimeline = createTaroHook('onShareTimeline')
diff --git a/packages/taro-platform-harmony-cpp/src/runtime/framework/hooks.ts b/packages/taro-platform-harmony-cpp/src/runtime/framework/hooks.ts
@@ -83,6 +83,7 @@ export const useUnload = createTaroHook('onUnload')
 /** Mini-Program */
 export const useAddToFavorites = createTaroHook('onAddToFavorites')
 export const useOptionMenuClick = createTaroHook('onOptionMenuClick')
+export const useKeyboardHeight = createTaroHook('onKeyboardHeight')
 export const useSaveExitState = createTaroHook('onSaveExitState')
 export const useShareAppMessage = createTaroHook('onShareAppMessage')
 export const useShareTimeline = createTaroHook('onShareTimeline')
diff --git a/packages/taro-platform-harmony/src/runtime-framework/react/hooks.ts b/packages/taro-platform-harmony/src/runtime-framework/react/hooks.ts
@@ -84,6 +84,7 @@ export const useUnload = createTaroHook('onUnload')
 /** Mini-Program */
 export const useAddToFavorites = createTaroHook('onAddToFavorites')
 export const useOptionMenuClick = createTaroHook('onOptionMenuClick')
+export const useKeyboardHeight = createTaroHook('onKeyboardHeight')
 export const useSaveExitState = createTaroHook('onSaveExitState')
 export const useShareAppMessage = createTaroHook('onShareAppMessage')
 export const useShareTimeline = createTaroHook('onShareTimeline')
diff --git a/packages/taro-platform-harmony/src/runtime-framework/solid/hooks.ts b/packages/taro-platform-harmony/src/runtime-framework/solid/hooks.ts
@@ -78,6 +78,7 @@ export const useUnload = createTaroHook('onUnload')
 /** Mini-Program */
 export const useAddToFavorites = createTaroHook('onAddToFavorites')
 export const useOptionMenuClick = createTaroHook('onOptionMenuClick')
+export const useKeyboardHeight = createTaroHook('onKeyboardHeight')
 export const useSaveExitState = createTaroHook('onSaveExitState')
 export const useShareAppMessage = createTaroHook('onShareAppMessage')
 export const useShareTimeline = createTaroHook('onShareTimeline')
diff --git a/packages/taro-platform-harmony/src/utils/api-loader.ts b/packages/taro-platform-harmony/src/utils/api-loader.ts
@@ -7,6 +7,7 @@ export function apiLoader (str: string) {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
@@ -33,6 +34,7 @@ taro.useError = useError
 taro.useLaunch = useLaunch
 taro.useLoad = useLoad
 taro.useOptionMenuClick = useOptionMenuClick
+taro.useKeyboardHeight = useKeyboardHeight
 taro.usePageNotFound = usePageNotFound
 taro.usePageScroll = usePageScroll
 taro.usePullDownRefresh = usePullDownRefresh
@@ -58,6 +60,7 @@ export {
   useLaunch,
   useLoad,
   useOptionMenuClick,
+  useKeyboardHeight,
   usePageNotFound,
   usePageScroll,
   usePullDownRefresh,
diff --git a/packages/taro-runtime/src/dsl/common.ts b/packages/taro-runtime/src/dsl/common.ts
@@ -239,16 +239,30 @@ export function createPageConfig (component: any, pageName?: string, data?: Reco
 
   LIFECYCLES.forEach((lifecycle) => {
     let isDefer = false
+    let isEvent = false
     lifecycle = lifecycle.replace(/^defer:/, () => {
       isDefer = true
       return ''
     })
-    config[lifecycle] = function () {
-      const exec = () => safeExecute(this.$taroPath, lifecycle, ...arguments)
-      if (isDefer) {
-        hasLoaded.then(exec)
-      } else {
-        return exec()
+    lifecycle = lifecycle.replace(/^events:/, () => {
+      isEvent = true
+      return ''
+    })
+
+    if (isEvent && process.env.TARO_ENV === 'alipay') {
+      // 初始化 config.events 对象
+      if (!config.events) config.events = {}
+      config.events[lifecycle] = function () {
+        return safeExecute(this.$taroPath, lifecycle, ...arguments)
+      }
+    } else {
+      config[lifecycle] = function () {
+        const exec = () => safeExecute(this.$taroPath, lifecycle, ...arguments)
+        if (isDefer) {
+          hasLoaded.then(exec)
+        } else {
+          return exec()
+        }
       }
     }
   })
diff --git a/packages/taro-runtime/src/dsl/instance.ts b/packages/taro-runtime/src/dsl/instance.ts
@@ -33,6 +33,7 @@ export interface PageLifeCycle extends Show {
   onAddToFavorites?(): void
   onLoad?(options: Record<string, unknown>, cb?: TFunc): void
   onOptionMenuClick?(): void
+  onKeyboardHeight?(obj: { height: number }): void
   onPageScroll?(obj: { scrollTop: number }): void
   onPullDownRefresh?(): void
   onPullIntercept?(): void
@@ -57,6 +58,8 @@ export interface PageInstance extends PageLifeCycle {
   options?: Record<string, unknown>
   /** 页面渲染引擎类型 */
   renderer?: 'webview' | 'skyline'
+  /** 页面事件对象，支付宝小程序特有，详见[events](https://opendocs.alipay.com/mini/framework/page-detail#events) */
+  events?: Record<string, (...args: any[]) => any>
   /** 获得一个 EventChannel 对象，用于页面间通讯 */
   getOpenerEventChannel?(): Record<string, any>
   /** 执行关键帧动画，详见[动画](https://developers.weixin.qq.com/miniprogram/dev/framework/view/animation.html) */
diff --git a/packages/taro/types/api/taro.hooks.d.ts b/packages/taro/types/api/taro.hooks.d.ts
@@ -133,6 +133,12 @@ declare module '../index' {
      */
     useOptionMenuClick(callback: () => void): void
 
+    /**
+     * 键盘高度变化时的回调。
+     * @supported alipay
+     */
+    useKeyboardHeight(callback: (payload: { height: number }) => void): void
+
     /**
      * 下拉中断时的回调。
      * @supported alipay, h5, harmony_hybrid
diff --git a/packages/taro/types/taro.component.d.ts b/packages/taro/types/taro.component.d.ts
@@ -45,6 +45,8 @@ declare module './index' {
     eh?(event: MpEvent): void
     onLoad(options: Record<string, unknown>): void
     onOptionMenuClick?(): void
+    /** 键盘高度变化时触发 @supported alipay */
+    onKeyboardHeight?(opt: { height: number; }): void
     onPageScroll?(opt: PageScrollObject): void
     onPopMenuClick?(): void
     onPullDownRefresh?(): void
diff --git a/tests/__tests__/__snapshots__/babel.spec.ts.snap b/tests/__tests__/__snapshots__/babel.spec.ts.snap
@@ -626,6 +626,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/compiler-macros.spec.ts.snap b/tests/__tests__/__snapshots__/compiler-macros.spec.ts.snap
@@ -626,6 +626,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/config.spec.ts.snap b/tests/__tests__/__snapshots__/config.spec.ts.snap
@@ -626,6 +626,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -2454,6 +2455,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -4144,6 +4146,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -5850,6 +5853,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -7498,6 +7502,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/css-modules.spec.ts.snap b/tests/__tests__/__snapshots__/css-modules.spec.ts.snap
@@ -626,6 +626,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -2329,6 +2330,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/framework.spec.ts.snap b/tests/__tests__/__snapshots__/framework.spec.ts.snap
@@ -626,6 +626,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -2846,6 +2847,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/mini-platform.spec.ts.snap b/tests/__tests__/__snapshots__/mini-platform.spec.ts.snap
@@ -807,6 +807,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -1923,6 +1924,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -2900,6 +2902,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/parse-html.spec.ts.snap b/tests/__tests__/__snapshots__/parse-html.spec.ts.snap
@@ -626,6 +626,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/prerender.spec.ts.snap b/tests/__tests__/__snapshots__/prerender.spec.ts.snap
@@ -626,6 +626,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -3688,6 +3689,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
@@ -6750,6 +6752,7 @@ require("./runtime");
         function useUnload() {}
         function useAddToFavorites() {}
         function useOptionMenuClick() {}
+        function useKeyboardHeight() {}
         function useSaveExitState() {}
         function useShareAppMessage() {}
         function useShareTimeline() {}
diff --git a/tests/__tests__/__snapshots__/sass.spec.ts.snap b/tests/__tests__/__snapshots__/sass.spec.ts.snap
diff --git a/tests/__tests__/__snapshots__/skyline.spec.ts.snap b/tests/__tests__/__snapshots__/skyline.spec.ts.snap
diff --git a/tests/__tests__/__snapshots__/subpackages.spec.ts.snap b/tests/__tests__/__snapshots__/subpackages.spec.ts.snap
diff --git a/tests/__tests__/__snapshots__/tabbar.spec.ts.snap b/tests/__tests__/__snapshots__/tabbar.spec.ts.snap
diff --git a/tests/__tests__/__snapshots__/ts.spec.ts.snap b/tests/__tests__/__snapshots__/ts.spec.ts.snap
diff --git a/tests/__tests__/__snapshots__/wx-hybrid.spec.ts.snap b/tests/__tests__/__snapshots__/wx-hybrid.spec.ts.snap
diff --git a/tests/__tests__/mocks/taro.ts b/tests/__tests__/mocks/taro.ts
