vue3-low-req/README.en.md

前端js 组件库，快捷开发、组件封装

Vue3 Low Req 组件库使用文档
Vue3 Low Req 是一个基于 Vue 3 的组件库，主要用于快速构建具有数据请求和分页功能的列表组件。
安装
bash
npm install vue3-low-req
快速开始
全局注册
javascript
import { createApp } from 'vue'
import App from './App.vue'
import Vue3LowReq from 'vue3-low-req'
import 'vue3-low-req/dist/style.css'
const app = createApp(App)
app.use(Vue3LowReq)
app.mount('#app')

使用前先初始化
javascript
import {queryList,queryBox,initRequest}from 'vue3-low-req'

//最好在项目初始化完毕就调用此方法
initRequest(null,(data)=>{  // 请求拦截 例如 success 就把data放入 返回 这里是放入queryList的数据，
    //注意 return 的 数据结构最好是这样 {data:[] ,total:0}  可以不包含 total 但是必须要data
    return data //{data:[] ,total:0}  
},{  //这个参数为config 参数可选  不填直接有默认

// 配置  分页字段名 ， 下面是默认的  ， 可自定义
    pageFieldName:{
        pageNumber:'pageNumber',
        pageSize:'pageSize',
        total:'total',
        data:'data'
    },
    isAutoBotomPageSelect:true,  //是否默认开启底部分页选择 组件 ， 默认true 就是 如果数据带 total 分页总条数 就会自动开启分页

})

局部导入
javascript
import { low-queryList, low-queryParent, low-pagination, low-queryBox } from 'vue3-low-req'
import 'vue3-low-req/dist/style.css'


组件说明

1.low-queryParent 组件
queryParent 组件是query 的父组件 提供了数据请求和分页的核心功能。
基本用法
vue
<template>
  <low-queryParent req-url="/api/data">
    <template #default="{ data, page, changePage, changePageSize }">
      <!-- 使用获取到的数据 -->
      <div v-if="Array.isArray(data)">
        <div v-for="item in data" :key="item.id">
          {{ item }}
        </div>
      </div>
    </template>
    
    <!-- 自定义分页 -->
    <template #pagination="{ pagination, changePage, changePageSize }">
      <div class="custom-pagination">
        <button @click="changePage(pagination.currentPage - 1)">上一页</button>
        <span>第 {{ pagination.currentPage }} 页</span>
        <button @click="changePage(pagination.currentPage + 1)">下一页</button>
      </div>
    </template>
  </low-queryParent>
</template>
<script setup>

</script>
Props
暂时无法在飞书文档外展示此内容
Events
暂时无法在飞书文档外展示此内容

Ref调用
暂时无法在飞书文档外展示此内容
//一般例如 需要修改 data 里面数据 只需要这样 ， 即可自动 双向绑定刷新到 template 里面
const data = queryBoxRef.value.parent.getRespData()
data.collect_task_status = "2"
                   
Slots
default
默认插槽，提供以下作用域属性：
- data: 从请求获取的数据
- page: 分页信息对象
- changePage(page): 切换页面的方法
- changePageSize(size): 更改每页显示数量的方法
pagination
分页插槽，提供以下作用域属性：
- pagination: 分页信息对象
- changePage(page): 切换页面的方法
- changePageSize(size): 更改每页显示数量的方法
- 
2. low-queryList 组件
queryList 组件是一个完整的列表组件，提供了数据请求、分页和列表展示功能。
基本用法
vue
<template>
  <low-queryList 
    req-url="/api/users" 
    req-method="get"
    :req-data="{ status: 'active' }" />
</template>
<script setup>
import { lowQueryList } from 'vue3-low-req'
</script>
自定义列表项
vue
<template>
  <low-queryList req-url="/api/users">
    <template #default="{ item, data, index }">
      <div class="custom-item">
        <h3>{{ item.name }}</h3>
        <p>{{ item.email }}</p>
      </div>
    </template>
  </low-queryList>
</template>
Props
拥有 low-queryParent 的全部参数功能， 其他参数 转到 low-queryParent 组件查看
暂时无法在飞书文档外展示此内容
Slots
default
默认插槽，提供以下作用域属性：
- item: 当前列表项数据
- data: 完整的响应数据
- index: 当前项索引
ref使用父组件
ref.value.parent.函数()
3. low-queryBox 组件
queryBox 组件是一个通用的数据容器组件，适用于展示卡片式数据。card-class参数不传即普通div ， 参数参考样式说明里面的 .card 的css
基本用法
vue
<template>
  <low-queryBox 
    req-url="/api/data"
    card-class="card-base"
    @get-data="handleData">
    <template #default="{ data }">
      <div class="card-header">标题</div>
      <div class="card-body">{{ data }}</div>
    </template>
  </low-queryBox>
</template>
<script setup>

const handleData = (data, pagination) => {
  console.log('获取到数据:', data, pagination)
}
</script>
Props

拥有 low-queryParent 的全部参数功能， 其他参数 转到 queryParent 组件
暂时无法在飞书文档外展示此内容
Events
暂时无法在飞书文档外展示此内容
ref使用父组件
ref.value.parent.函数()
Slots
default
默认插槽，提供以下作用域属性：
- data: 从请求获取的数据


4. low-dataDic 数据字典组件
概述
LowDataDic 是一个用于显示数据字典值的 Vue 组件。它可以根据传入的字典代码和值，异步获取并显示对应的字典名称。
使用前 需要初始化

 /**
   * 初始化数据字典
   */
  initDataDic(async (code)=>{
          const resp = await asynDataDicItems(code)
          console.log('initDataDic',resp)
          return resp  
          //return的数据结构如下 为数组
          // [{name:'0',value:'1'},{name:'1',value:'2'}]
  })
使用方法
vue
<template>
  <lowDataDic code="dict_code" value="dict_value" />
</template>
<script setup>
import { lowDataDic } from 'path/to/component'
</script>
Props
暂时无法在飞书文档外展示此内容
示例
基础用法
vue
<template>
  <div>
    <!-- 显示性别为1对应的名称（如"男"） -->
    <lowDataDic code="gender" value="1" />
    
    <!-- 显示状态为0对应的名称（如"禁用"） -->
    <lowDataDic code="status" value="0" />
  </div>
</template>
在列表中使用
vue
<template>
  <div v-for="item in userList" :key="item.id">
    <p>用户名: {{ item.name }}</p>
    <p>性别: <lowDataDic code="gender" :value="item.gender" /></p>
    <p>状态: <lowDataDic code="user_status" :value="item.status" /></p>
  </div>
</template>
工作原理
1. 组件接收 code 和 value 两个参数
2. 在组件挂载时，调用 dataDic.getDataDicName(code, value) 方法获取字典名称
3. 异步获取到名称后，将其显示在组件中
注意事项
1. 该组件依赖于 ../js/dataDic 模块，确保该模块正确配置并可访问
2. 字典数据的获取是异步的，组件会在数据加载完成后自动更新显示
3. 如果传入的字典代码或值不存在，组件可能显示空字符串或默认值


5. low-pagination 组件（默认应用上面组件有分页时自动出现，一般不单独使用因为网上一大把）
Pagination 组件是一个独立的分页控件。
基本用法
vue
<template>
  <low-pagination 
    :pagination="paginationData"
    :change-page="handleChangePage"
    :change-page-size="handleChangePageSize" />
</template>
<script setup>
import { reactive } from 'vue'

const paginationData = reactive({
  currentPage: 1,
  pageSize: 10,
  total: 100,
  totalPages: 10
})

const handleChangePage = (page) => {
  console.log('切换到第', page, '页')
}

const handleChangePageSize = (size) => {
  console.log('每页显示', size, '条')
}
</script>
Props
暂时无法在飞书文档外展示此内容
高级用法(必选)
自定义请求处理
如果需要自定义请求处理，可以使用提供的请求工具函数：
javascript
import { initRequest, setRequest, setRequestConfig } from 'vue3-low-req'

// 设置请求配置  如自定义的axios  Request 请忽略这一步
setRequestConfig('https://api.example.com', {
  timeout: 10000
})

// 初始化请求配置 可自定义request 也就是 axios对象 反之 使用默认的 需要设置 config
initRequest(customRequest, (data) => {
  // 数据过滤处理
  return data.result
})

数据过滤函数
可以使用 dataFilterFunc 属性对请求返回的数据进行处理：
vue
<template>
  <queryParent 
    req-url="/api/data"
    :data-filter-func="filterData">
    <template #default="{ data }">
      {{ data }}
    </template>
  </queryParent>
</template>
<script setup>
import { queryParent } from 'vue3-low-req'

const filterData = (responseData) => {
  // 对响应数据进行处理
  return responseData.items || []
}
</script>
完整示例
vue
<template>
  <div class="vue3-low-req">
    <h2>用户列表</h2>
    <queryList req-url="/api/users" req-method="get" :req-data="{ department: 'IT' }">
      <template #default="{ item, index }">
        <div class="user-card">
          <img :src="item.avatar" :alt="item.name" />
          <div class="user-info">
            <h3>{{ item.name }}</h3>
            <p>{{ item.email }}</p>
            <p>{{ item.department }}</p>
          </div>
        </div>
      </template>
    </queryList>
    
    <queryBox req-url="/api/statistics" card-class="card-base mt-10" @get-data="handleStats">
      <template #default="{ data }">
        <div class="card-header">统计信息</div>
        <div class="card-body">
          <div class="stats-grid">
            <div class="stat-item">
              <div class="stat-value">{{ data.userCount }}</div>
              <div class="stat-label">用户总数</div>
            </div>
            <div class="stat-item">
              <div class="stat-value">{{ data.activeCount }}</div>
              <div class="stat-label">活跃用户</div>
            </div>
          </div>
        </div>
      </template>
    </queryBox>
  </div>
</template>
<script setup>
import { queryList, queryBox } from 'vue3-low-req'

const handleStats = (data, pagination) => {
  console.log('统计信息:', data)
}
</script>
<style scoped>
.user-card {
  display: flex;
  border: 1px solid #eee;
  padding: 16px;
  margin-bottom: 16px;
  border-radius: 8px;
}

.user-card img {
  width: 50px;
  height: 50px;
  border-radius: 50%;
  margin-right: 16px;
}

.user-info h3 {
  margin: 0 0 8px 0;
}

.stats-grid {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 20px;
}

.stat-item {
  text-align: center;
}

.stat-value {
  font-size: 24px;
  font-weight: bold;
  color: #4f628c;
}

.stat-label {
  font-size: 14px;
  color: #666;
}
</style>
注意事项
1. 仅支持 GET 和 POST 请求方法
2. 确保请求返回的数据格式兼容组件要求
3. 如果需要自定义样式，可以覆盖默认的 CSS 类名
常见问题
如何处理请求错误？
组件会自动显示错误信息，您也可以通过插槽自定义错误显示方式。
如何自定义分页样式？
通过 pagination 插槽可以完全自定义分页控件的外观和行为。
如何在请求中添加认证信息？
可以通过自定义请求处理函数来添加认证头信息：
javascript
import { initRequest } from 'vue3-low-req'
import axios from 'axios'
const customRequest = axios.create({
  baseURL: 'https://api.example.com',
  headers: {
    'Authorization': `Bearer ${getToken()}`
  }
})
initRequest(customRequest)

//在手机端上有时会遇到下滑滚动 加载更多的 场景 这样即可解决
<template>
<low-queryBox
        req-url="/ebss/collectTask/appList"
        :defPageSize="5"
        isPage
        :req-data="query"
        ref="queryBoxAppListRef"
        @getData="e=>{listData.push(...e.data)}"
        @pageLastNotice="toast('已经到底')"
></low-queryBox>
<div class="item" v-for="(item,index) in listData">
{{item}}
</div>

</template>

<script setup>
import {ref} from 'vue'
const listData = ref([])
</script>