qxs-bns

Appearance

安装指南 ​

📋 环境要求 ​

在开始之前，请确保你的开发环境满足以下要求：

环境版本要求说明
Node.js>= 16.0.0推荐使用 LTS 版本
Vue>= 3.2.0支持 Composition API
TypeScript>= 4.5.0可选，但强烈推荐
包管理器pnpm/npm/yarn推荐使用 pnpm

📦 安装方式 ​

分包安装 (推荐) ​

QXS-BNS 采用 monorepo 架构，支持按需安装特定包：

核心包 ​

bash
# 组件库 (包含桌面端和移动端组件)
pnpm add @qxs-bns/components

# 工具函数库
pnpm add @qxs-bns/utils

# Vue 3 Hooks
pnpm add @qxs-bns/hooks

# 自定义指令
pnpm add @qxs-bns/directives

# SVG 图标库
pnpm add @qxs-bns/icons

主题样式 ​

bash
# 主题样式包
pnpm add @qxs-bns/theme-chalk

移动端专用 ​

bash
# 移动端组件 (不依赖 Element Plus)
pnpm add @qxs-bns/components-v2

🌐 CDN 引入 ​

对于简单的原型或演示项目，可以通过 CDN 引入各个包：

html
<!DOCTYPE html>
<html>
<head>
  <!-- 引入 Vue 3 -->
  <script src="https://unpkg.com/vue@next"></script>

  <!-- 引入 QXS-BNS 组件库样式 -->
  <link rel="stylesheet" href="https://unpkg.com/@qxs-bns/components/dist/index.css">

  <!-- 引入 QXS-BNS 组件库 -->
  <script src="https://unpkg.com/@qxs-bns/components/dist/index.umd.js"></script>

  <!-- 引入工具函数库 -->
  <script src="https://unpkg.com/@qxs-bns/utils/dist/index.umd.js"></script>
</head>
<body>
  <div id="app">
    <qxs-button type="primary">Hello QXS-BNS</qxs-button>
  </div>

  <script>
    const { createApp } = Vue
    const { QxsButton } = QxsComponents

    createApp({
      components: {
        QxsButton
      }
    }).mount('#app')
  </script>
</body>
</html>

🌍 浏览器支持 ​

QXS-BNS 支持所有现代浏览器：

浏览器版本要求说明
Chrome>= 64推荐使用最新版本
Firefox>= 63支持 ES6+ 特性
Safari>= 12支持 iOS Safari
Edge>= 79基于 Chromium

注意: 不支持 IE 浏览器

⚙️ 开发环境配置 ​

Vite 项目配置 ​

推荐的 Vite 配置：

typescript
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  optimizeDeps: {
    include: [
      '@qxs-bns/components',
      '@qxs-bns/utils',
      '@qxs-bns/hooks',
      '@qxs-bns/directives'
    ]
  },
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "@qxs-bns/theme-chalk/src/mixins/mixins.scss";`
      }
    }
  }
})

TypeScript 配置 ​

在 tsconfig.json 中添加类型支持：

json
{
  "compilerOptions": {
    "types": ["@qxs-bns/components/global"],
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  },
  "include": [
    "src/**/*",
    "node_modules/@qxs-bns/*/global.d.ts"
  ]
}

🚀 自动按需引入 ​

使用 unplugin-vue-components ​

推荐使用自动按需引入插件：

bash
pnpm add -D unplugin-vue-components unplugin-auto-import
typescript
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [
        // QXS-BNS 组件自动引入
        (componentName) => {
          if (componentName.startsWith('Qxs'))
            return { name: componentName, from: '@qxs-bns/components' }
        }
      ]
    }),
    AutoImport({
      imports: ['vue'],
      resolvers: [
        // QXS-BNS 工具函数自动引入
        (name) => {
          if (['ArgoLog', 'Storage', 'DateTransfer', 'Device'].includes(name))
            return { name, from: '@qxs-bns/utils' }
        }
      ]
    })
  ]
})

手动按需引入 ​

typescript
// main.ts
import { createApp } from 'vue'
import {
  QxsButton,
  QxsInput,
  QxsDataChart
} from '@qxs-bns/components'

const app = createApp(App)

// 注册组件
app.component('QxsButton', QxsButton)
app.component('QxsInput', QxsInput)
app.component('QxsDataChart', QxsDataChart)

app.mount('#app')

🎨 样式配置 ​

完整引入样式 ​

typescript
// main.ts
import '@qxs-bns/components/dist/index.css'

按需引入样式 ​

scss
// styles/main.scss

// 引入基础样式
@import '@qxs-bns/theme-chalk/src/base.scss';

// 引入组件样式
@import '@qxs-bns/theme-chalk/src/button.scss';
@import '@qxs-bns/theme-chalk/src/input.scss';

自定义主题 ​

scss
// styles/theme.scss

// 覆盖默认变量
:root {
  --qxs-color-primary: #409eff;
  --qxs-color-success: #67c23a;
  --qxs-color-warning: #e6a23c;
  --qxs-color-danger: #f56c6c;
}

// 引入组件样式
@import '@qxs-bns/components/dist/index.css';

✅ 验证安装 ​

创建测试页面验证安装：

vue
<!-- App.vue -->
<template>
  <div class="app">
    <h1>🎉 QXS-BNS 安装成功！</h1>

    <!-- 测试组件 -->
    <QxsButton type="primary" @click="handleClick">
      测试按钮
    </QxsButton>

    <!-- 测试工具函数 -->
    <p>当前时间: {{ currentTime }}</p>

    <!-- 测试指令 -->
    <button v-debounce="handleDebounce">
      防抖按钮
    </button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { QxsButton } from '@qxs-bns/components'
import { ArgoLog, DateTransfer } from '@qxs-bns/utils'
import { vDebounce } from '@qxs-bns/directives'

const currentTime = ref('')

const handleClick = () => {
  ArgoLog.info('按钮点击成功！')
}

const handleDebounce = () => {
  ArgoLog.info('防抖按钮点击')
}

onMounted(() => {
  currentTime.value = DateTransfer.format(new Date(), 'YYYY-MM-DD HH:mm:ss')
})
</script>

如果页面正常显示且功能正常，说明安装成功！

🔧 常见问题 ​

依赖冲突 ​

bash
# 清除包管理器缓存
pnpm store prune
# 或
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

TypeScript 类型错误 ​

bash
# 安装必要的类型定义
pnpm add -D @types/node @types/web

样式不生效 ​

检查样式引入顺序：

typescript
// 1. 先引入基础样式
import '@qxs-bns/components/dist/index.css'

// 2. 再引入自定义样式
import './styles/custom.css'

构建错误 ​

检查构建工具配置：

typescript
// vite.config.ts
export default defineConfig({
  build: {
    commonjsOptions: {
      include: [/@qxs-bns/, /node_modules/]
    }
  }
})

📚 下一步 ​

安装完成后，建议按以下顺序学习：

  1. 快速开始 - 5分钟上手指南
  2. 组件总览 - 浏览所有组件
  3. 开发指南 - 了解开发规范
  4. 特性介绍 - 深入了解特性

💬 获取帮助 ​

遇到问题？可以通过以下方式获取帮助：

Released under the MIT License.

Copyright © 2024-present The Muse Catcher