hooks

QXS-BNS 提供了实用的 Vue 3 Composition API Hooks，本指南将帮助你快速上手使用。

📦 安装

# 安装 Hooks 包
pnpm add @qxs-bns/hooks

🚀 使用方式

按需引入（推荐）

<script setup lang="ts">
import { usePagination } from '@qxs-bns/hooks'

const {
  currentPage,
  pageSize,
  total,
  totalPages,
  changePage,
  changePageSize
} = usePagination({
  defaultPageSize: 10,
  total: 100
})
</script>

完整引入

import * as QxsHooks from '@qxs-bns/hooks'

const pagination = QxsHooks.usePagination({ total: 100 })

🚀 使用示例

分页管理

<template>
  <div>
    <!-- 数据列表 -->
    <div v-for="item in data" :key="item.id">
      {{ item.name }}
    </div>

    <!-- 分页器 -->
    <el-pagination
      v-model:current-page="currentPage"
      v-model:page-size="pageSize"
      :total="total"
      @current-change="handlePageChange"
      @size-change="handleSizeChange"
    />
  </div>
</template>

<script setup lang="ts">
import { usePagination } from '@qxs-bns/hooks'

const {
  currentPage,
  pageSize,
  total,
  totalPages,
  changePage,
  changePageSize,
  setTotal
} = usePagination({
  defaultPageSize: 10
})

// 模拟数据加载
const data = ref([])

const loadData = async () => {
  const response = await fetch(`/api/data?page=${currentPage.value}&size=${pageSize.value}`)
  const result = await response.json()

  data.value = result.data
  setTotal(result.total)
}

// 页码变化
const handlePageChange = (page: number) => {
  changePage(page)
  loadData()
}

// 页大小变化
const handleSizeChange = (size: number) => {
  changePageSize(size)
  loadData()
}

// 初始加载
onMounted(() => {
  loadData()
})
</script>

响应式特性

<script setup lang="ts">
import { usePagination } from '@qxs-bns/hooks'

const pagination = usePagination({ total: 100 })

// 自动计算总页数
watchEffect(() => {
  console.log(`当前第 ${pagination.currentPage.value} 页，共 ${pagination.totalPages.value} 页`)
})

// 监听页码变化
watch(pagination.currentPage, (newPage) => {
  console.log(`切换到第 ${newPage} 页`)
})
</script>

📋 可用 Hooks

Hook 名	说明	文档
usePagination	分页状态管理	✅

🎯 特色功能

TypeScript 支持

所有 Hooks 都提供完整的 TypeScript 类型定义：

import type { PaginationOptions, PaginationReturn } from '@qxs-bns/hooks'

const options: PaginationOptions = {
  defaultPage: 1,
  defaultPageSize: 20,
  total: 200
}

const pagination: PaginationReturn = usePagination(options)

响应式设计

基于 Vue 3 的响应式系统，自动追踪依赖：

<script setup lang="ts">
import { usePagination } from '@qxs-bns/hooks'

const { currentPage, pageSize, totalPages } = usePagination({
  total: 100
})

// 自动计算总页数
watchEffect(() => {
  console.log(`当前第 ${currentPage.value} 页，共 ${totalPages.value} 页`)
})
</script>

组合使用

Hooks 可以灵活组合使用：

<script setup lang="ts">
import { usePagination, useRequest, useLoading } from '@qxs-bns/hooks'

const { loading, setLoading } = useLoading()
const pagination = usePagination({ defaultPageSize: 10 })

const { data, execute } = useRequest(async () => {
  setLoading(true)
  try {
    const result = await fetchData({
      page: pagination.currentPage.value,
      size: pagination.pageSize.value
    })
    pagination.setTotal(result.total)
    return result.data
  } finally {
    setLoading(false)
  }
})
</script>

🔧 开发指南

创建自定义 Hook

import { ref, computed } from 'vue'

export function useCounter(initialValue = 0) {
  const count = ref(initialValue)
  
  const increment = () => count.value++
  const decrement = () => count.value--
  const reset = () => count.value = initialValue
  
  const isZero = computed(() => count.value === 0)
  const isPositive = computed(() => count.value > 0)
  
  return {
    count: readonly(count),
    increment,
    decrement,
    reset,
    isZero,
    isPositive
  }
}

测试 Hooks

import { renderHook } from '@testing-library/vue'
import { usePagination } from '@qxs-bns/hooks'

describe('usePagination', () => {
  it('should initialize with default values', () => {
    const { result } = renderHook(() => usePagination({ total: 100 }))
    
    expect(result.currentPage.value).toBe(1)
    expect(result.pageSize.value).toBe(10)
    expect(result.totalPages.value).toBe(10)
  })
})

📚 相关资源

• Vue 3 Composition API
• VueUse - 更多实用 Hooks
• 组件库
• 工具函数

🤝 贡献

欢迎贡献新的 Hooks！请参考：

• 开发指南
• 代码规范
• 测试规范

📝 状态说明

• ✅ 已完成并可用
• 🚧 开发中
• 📋 计划中
• ❌ 已废弃