快速开始

本指南将帮助你在 5 分钟内快速上手 QXS-BNS 组件库

📦 安装

环境要求

• Node.js >= 16.0.0
• Vue >= 3.2.0
• TypeScript >= 4.5.0 (可选)

分包安装 (推荐)

# 只安装需要的包
pnpm add @qxs-bns/components  # 组件库
pnpm add @qxs-bns/utils       # 工具函数
pnpm add @qxs-bns/hooks       # Vue Hooks
pnpm add @qxs-bns/directives  # 自定义指令
pnpm add @qxs-bns/icons       # 图标库

🚀 基础用法

按需引入 (推荐)

推荐的使用方式，支持 Tree-shaking：

// main.ts
import { createApp } from 'vue'
import { QxsFixedActionBar, QxsPhotoCropTool } from '@qxs-bns/components'
import { ArgoLog, Storage } from '@qxs-bns/utils'
import { usePagination } from '@qxs-bns/hooks'
import { vDebounce, vWaves } from '@qxs-bns/directives'

const app = createApp(App)

// 注册组件
app.component('QxsFixedActionBar', QxsFixedActionBar)
app.component('QxsPhotoCropTool', QxsPhotoCropTool)

// 注册指令
app.directive('debounce', vDebounce)
app.directive('waves', vWaves)

app.mount('#app')

移动端专用

对于移动端项目，使用轻量级组件（不依赖 Element Plus）：

// 移动端组件 - 无 Element Plus 依赖
import {
  QxsFixedActionBar,    // 固定操作栏
  QxsPhotoCropTool,     // 图片裁剪工具
} from '@qxs-bns/components'

// 工具函数
import { ArgoLog, Storage, Device } from '@qxs-bns/utils'

// Vue Hooks
import { usePagination } from '@qxs-bns/hooks'

// 自定义指令
import { vDebounce, vWaves, vCopy } from '@qxs-bns/directives'

// SVG 图标
import { QxsIconHome, QxsIconUser } from '@qxs-bns/icons'

🎯 第一个示例

桌面端示例

创建一个包含数据图表和文件上传的页面：

<template>
  <div class="desktop-demo">
    <h1>QXS-BNS 桌面端示例</h1>

    <!-- 数据图表组件 -->
    <QxsDataChart
      :data="chartData"
      type="line"
      title="用户增长趋势"
    />

    <!-- 文件上传组件 -->
    <QxsFileUpload
      v-model="fileList"
      :limit="3"
      accept=".jpg,.png,.pdf"
      @success="handleUploadSuccess"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { QxsDataChart, QxsFileUpload } from '@qxs-bns/components'
import { ArgoLog } from '@qxs-bns/utils'

const chartData = ref([
  { name: '1月', value: 100 },
  { name: '2月', value: 200 },
  { name: '3月', value: 300 }
])

const fileList = ref([])

const handleUploadSuccess = (file: any) => {
  ArgoLog.info('文件上传成功', file)
}
</script>

移动端示例

创建一个移动端页面：

<template>
  <div class="mobile-demo">
    <h1>QXS-BNS 移动端示例</h1>

    <!-- 图片裁剪工具 -->
    <QxsPhotoCropTool
      v-model="croppedImage"
      :aspect-ratio="1"
      @crop="handleCrop"
    />

    <!-- 固定操作栏 -->
    <QxsFixedActionBar :actions="actions" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { QxsPhotoCropTool, QxsFixedActionBar } from '@qxs-bns/components'
import { Storage, Device } from '@qxs-bns/utils'

const croppedImage = ref('')
const storage = new Storage('demo_')

const actions = ref([
  {
    text: '保存',
    type: 'primary',
    onClick: () => {
      storage.set('croppedImage', croppedImage.value)
      console.log('图片已保存')
    }
  }
])

const handleCrop = (result: string) => {
  console.log('裁剪完成:', result)
}

// 检测设备类型
console.log('当前设备:', Device.isMobile() ? '移动端' : '桌面端')
</script>

工具函数示例

import { ArgoLog, Storage, DateTransfer, Device } from '@qxs-bns/utils'

// 日志记录
ArgoLog.info('用户登录', { userId: 123 })
ArgoLog.error('请求失败', { error: 'Network Error' })

// 本地存储
const storage = new Storage('myApp_')
storage.set('user', { name: 'John', age: 25 })
const user = storage.get('user')

// 日期处理
const formatted = DateTransfer.format(new Date(), 'YYYY-MM-DD HH:mm:ss')
const relative = DateTransfer.fromNow(new Date('2024-01-01'))

// 设备检测
if (Device.isMobile()) {
  console.log('移动端设备')
}

Hooks 示例

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

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

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

const handlePageChange = (page: number) => {
  changePage(page)
  // 加载数据...
}

// 设置总数
setTotal(100)
</script>

🎉 恭喜！

你已经成功上手 QXS-BNS 组件库！

📚 下一步

深入学习

• 组件文档 - 浏览所有可用组件
• 工具函数 - 了解实用工具函数
• Hooks 文档 - 学习 Vue 3 Hooks
• 指令文档 - 掌握自定义指令

开发指南

• 开发指南 - 了解开发规范和流程
• 依赖管理 - 学习智能依赖管理
• 主题定制 - 自定义主题样式

获取帮助

• GitHub Issues - 报告问题
• 在线文档 - 查看最新文档