跳到主要内容
版本：4.x

Vue3 Composition APIs

信息

Taro v3.4.0+ 开始支持

Vue3 提供了 Composition API（组合式 API） 特性，和传统的 Options API 不同，Composition API 提供了全新的编码方式 ，可以让我们更好地去组织和复用代码逻辑。

本文将会介绍 Taro 提供的一些自定义 Composition APIs。而关于 Composition API 的相关用法和内置 API 等信息，请参阅 Vue 文档：

Taro Composition APIs​

Taro 内置的一些 Composition API，可以从 @tarojs/taro 包中引入使用。

例子：

在 setup 函数中使用
<script>
  import { useDidShow } from '@tarojs/taro'

  export default {
    setup() {
      useDidShow(() => console.log('onShow'))
    },
  }
</script>
在 <script setup> 中使用
<script setup>
  import { useDidShow } from '@tarojs/taro'

  useDidShow(() => console.log('onShow'))
</script>

useRouter​

等同于 Taro.getCurrentInstance().router。

示例代码
// { path: '', params: { ... } }
const router = useRouter()

useLoad​

信息

Taro v3.5.0+ 开始支持

等同于页面的 onLoad 生命周期钩子。

示例代码
useLoad(() => {
  console.log('onLoad')
})

useReady​

等同于页面的 onReady 生命周期钩子。

从此生命周期开始可以使用 createCanvasContext 或 createSelectorQuery 等 API 访问小程序渲染层的 DOM 节点。

示例代码
useReady(() => {
  const query = wx.createSelectorQuery()
})

useDidShow​

页面显示/切入前台时触发。等同于 onShow 页面生命周期钩子。

示例代码
useDidShow(() => {
  console.log('onShow')
})

useDidHide​

页面隐藏/切入后台时触发。等同于 onHide 页面生命周期钩子。

示例代码
useDidHide(() => {
  console.log('onHide')
})

useUnload​

信息

Taro v3.5.0+ 开始支持

等同于页面的 onUnload 生命周期钩子。

示例代码
useUnload(() => {
  console.log('onUnload')
})

usePullDownRefresh​

监听用户下拉动作。等同于 onPullDownRefresh 页面生命周期钩子。

示例代码
usePullDownRefresh(() => {
  console.log('onPullDownRefresh')
})

useReachBottom​

监听用户上拉触底事件。等同于 onReachBottom 页面生命周期钩子。

示例代码
useReachBottom(() => {
  console.log('onReachBottom')
})

usePageScroll​

监听用户滑动页面事件。等同于 onPageScroll 页面生命周期钩子。

示例代码
usePageScroll((res) => {
  console.log(res.scrollTop)
})

useResize​

小程序屏幕旋转时触发。等同于 onResize 页面生命周期钩子。

示例代码
useResize((res) => {
  console.log(res.size.windowWidth)
  console.log(res.size.windowHeight)
})

useShareAppMessage​

监听用户点击页面内转发按钮（Button 组件 openType='share'）或右上角菜单“转发”按钮的行为，并自定义转发内容。等同于 onShareAppMessage 页面生命周期钩子。

使用时，必须为页面配置 enableShareAppMessage: true。（修改配置文件后请重新编译项目）

page.vue
<script setup>
  import { useShareAppMessage } from '@tarojs/taro'

  useShareAppMessage((res) => {
    if (res.from === 'button') {
      // 来自页面内转发按钮
      console.log(res.target)
    }
    return {
      title: '自定义转发标题',
      path: '/page/user?id=123',
    }
  })
</script>
page.config.js
export default {
  enableShareAppMessage: true,
}

useTabItemTap​

点击 tab 时触发。等同于 onTabItemTap 页面生命周期钩子。

示例代码
useTabItemTap((item) => {
  console.log(item.index)
  console.log(item.pagePath)
  console.log(item.text)
})

useShareTimeline​

监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。等同于 onShareTimeline 页面生命周期钩子。

只有微信小程序支持，基础库 2.11.3 开始支持，本接口为 Beta 版本，暂只在 Android 平台支持

使用时，必须为页面配置 enableShareTimeline: true。（修改配置文件后请重新编译项目）

page.vue
<script setup>
  import { useShareTimeline } from '@tarojs/taro'

  useShareTimeline(() => {
    console.log('onShareTimeline')
  })
</script>
page.config.js
export default {
  enableShareTimeline: true,
}

useAddToFavorites​

监听用户点击右上角菜单“收藏”按钮的行为，并自定义收藏内容。等同于 onAddToFavorites 页面生命周期钩子。

只有微信小程序支持，本接口为 Beta 版本，安卓 7.0.15 版本起支持，暂只在安卓平台支持

示例代码
useAddToFavorites((res) => {
  // webview 页面返回 webviewUrl
  console.log('WebviewUrl: ', res.webviewUrl)
  return {
    title: '自定义标题',
    imageUrl: 'https://demo.png',
    query: 'name=xxx&age=xxx',
  }
})

useSaveExitState​

信息

Taro v3.5.0+ 开始支持

每当小程序可能被销毁之前，页面回调函数 onSaveExitState 会被调用，可以进行退出状态的保存。

只有微信小程序支持，基础库 2.7.4 开始支持。

示例代码
useSaveExitState(() => {
  const exitState = { myDataField: 'myData' } // 需要保存的数据
  return {
    data: exitState,
    expireTimeStamp: Date.now() + 24 * 60 * 60 * 1000, // 超时时刻
  }
})

useTitleClick​

只有支付宝小程序支持。等同于 onTitleClick 页面生命周期钩子。

点击标题触发。

示例代码
useTitleClick(() => console.log('onTitleClick'))

useOptionMenuClick​

只有支付宝小程序支持。等同于 onOptionMenuClick 页面生命周期钩子。

点击导航栏额外图标触发。

示例代码
useOptionMenuClick(() => console.log('onOptionMenuClick'))

usePullIntercept​

只有支付宝小程序支持。等同于 onPullIntercept 页面生命周期钩子。

下拉截断时触发。

示例代码
usePullIntercept(() => console.log('onPullIntercept'))