🚀 组合式 API - 你的开发利器

🌟 介绍

欢迎来到 Vant 组合式 API 的世界！🎉

@vant/use 就像是一个装满了各种开发工具的百宝箱 🧰，它为你提供了一系列精心设计的组合式 API。这些 API 不仅在 Vant 组件内部发挥着重要作用，更是你日常开发中的得力助手！

🎯 为什么选择 @vant/use？

• ⚡ 开箱即用：无需重复造轮子，直接使用经过实战检验的 API
• 🔧 高度可复用：一次引入，处处使用
• 📱 移动端优化：专为移动端场景精心优化
• 🛡️ 类型安全：完整的 TypeScript 支持
• 🎨 Vue 3 原生：基于 Composition API 设计

📦 安装

虽然 Vant 的依赖中已经包含了 @vant/use，但我们强烈推荐显式地安装它，这样可以获得更好的开发体验和类型提示：

# 使用 npm
npm i @vant/use

# 使用 yarn
yarn add @vant/use

# 使用 pnpm
pnpm add @vant/use

# 使用 Bun
bun add @vant/use

🎮 快速上手

让我们通过一个简单的例子来感受一下组合式 API 的魅力！下面我们使用 useWindowSize 来实时获取窗口尺寸：

<template>
  <div class="window-info">
    <h3>📱 当前窗口信息</h3>
    <p>宽度：{{ width }}px</p>
    <p>高度：{{ height }}px</p>
    <p>屏幕类型：{{ screenType }}</p>
  </div>
</template>

<script setup>
import { useWindowSize } from '@vant/use';
import { computed } from 'vue';

// 获取窗口尺寸，自动响应变化
const { width, height } = useWindowSize();

// 根据宽度判断设备类型
const screenType = computed(() => {
  if (width.value < 768) return '📱 移动设备';
  if (width.value < 1024) return '📟 平板设备';
  return '💻 桌面设备';
});
</script>

🎯 实际应用场景

📱 响应式布局控制

import { useWindowSize } from '@vant/use';

const { width } = useWindowSize();
const isMobile = computed(() => width.value < 768);

// 根据屏幕尺寸动态调整布局
watch(isMobile, (mobile) => {
  if (mobile) {
    // 移动端布局逻辑
  } else {
    // 桌面端布局逻辑
  }
});

🎪 交互体验优化

import { useClickAway, useToggle } from '@vant/use';

const [visible, toggle] = useToggle(false);
const popupRef = ref();

// 点击外部区域关闭弹窗
useClickAway(popupRef, () => {
  if (visible.value) {
    toggle(false);
  }
});

📚 API 列表

下面是 Vant 为你精心准备的所有组合式 API，每一个都是开发中的实用工具：

🔧 API 名称	📝 功能描述	🎯 适用场景
useClickAway	🖱️ 监听点击元素外部的事件	弹窗、下拉菜单、搜索建议
useCountDown	⏰ 提供倒计时管理能力	验证码、活动倒计时、限时抢购
useCustomFieldValue	📝 自定义表单组件中的表单项	表单组件开发、数据绑定
useEventListener	👂 方便地进行事件绑定	滚动监听、键盘事件、触摸事件
usePageVisibility	👁️ 获取页面的可见状态	视频播放控制、数据轮询优化
useRect	📐 获取元素的大小及其相对于视口的位置	动画定位、滚动定位、碰撞检测
useRelation	🔗 建立父子组件之间的关联关系	组件库开发、复杂组件通信
useScrollParent	📜 获取元素最近的可滚动父元素	无限滚动、虚拟滚动、滚动同步
useToggle	🔄 用于在布尔值之间进行切换	开关控制、模态框、手风琴
useWindowSize	📏 获取浏览器窗口的视口宽度和高度	响应式设计、图表自适应
useRaf	🎬 提供 requestAnimationFrame 管理能力	动画控制、性能优化、帧率控制

💡 最佳实践

🎯 按需引入

// ✅ 推荐：按需引入
import { useWindowSize, useToggle } from '@vant/use';

// ❌ 避免：全量引入
import * as VantUse from '@vant/use';

🔄 组合使用

// 多个 API 组合使用，创造更强大的功能
import { useWindowSize, useEventListener, useToggle } from '@vant/use';

export function useResponsiveMenu() {
  const { width } = useWindowSize();
  const [menuVisible, toggleMenu] = useToggle(false);
  
  // 监听 ESC 键关闭菜单
  useEventListener('keydown', (e) => {
    if (e.key === 'Escape') {
      toggleMenu(false);
    }
  });
  
  // 桌面端自动显示菜单
  watch(width, (newWidth) => {
    if (newWidth >= 1024) {
      toggleMenu(true);
    }
  });
  
  return {
    menuVisible,
    toggleMenu,
    isMobile: computed(() => width.value < 768)
  };
}

🛠️ 开发技巧

📊 性能监控

import { useWindowSize, useRaf } from '@vant/use';

// 监控窗口尺寸变化频率
const { width, height } = useWindowSize();
let resizeCount = 0;

watch([width, height], () => {
  resizeCount++;
  console.log(`窗口尺寸变化次数: ${resizeCount}`);
});

🎨 调试工具

// 开发环境下的调试助手
if (process.env.NODE_ENV === 'development') {
  const { width, height } = useWindowSize();
  
  // 在控制台显示当前窗口信息
  watch([width, height], ([w, h]) => {
    console.log(`🖥️ 窗口尺寸: ${w} x ${h}`);
  }, { immediate: true });
}

🌐 浏览器兼容性

所有 API 都经过了广泛的兼容性测试，支持：

• ✅ 现代浏览器：Chrome 60+、Firefox 60+、Safari 12+
• ✅ 移动端浏览器：iOS Safari 12+、Android Chrome 60+
• ✅ 微信小程序：支持 H5 页面
• ⚠️ IE 浏览器：需要 polyfill 支持

📖 相关文档

🎯 核心概念

• Vue 3 Composition API - 了解组合式 API 的设计理念
• VueUse - 更多实用的 Vue 组合式工具库

🛠️ 开发工具

• Vue DevTools - Vue 官方开发者工具
• Vite - 推荐的构建工具
• TypeScript - 类型安全的 JavaScript

🎨 设计系统

• 主题定制 - 自定义组件主题

---

🎉 开始你的组合式 API 之旅吧！ 选择一个感兴趣的 API，点击查看详细文档，让开发变得更加高效和有趣！