使用指南

基础使用

1. 引入组件库

import { createApp } from 'vue'
import ByComponentsV3 from '@weitutech/by-components-v3'
import 'by-components-v3/dist/style.css'

const app = createApp(App)
app.use(ByComponentsV3)
app.mount('#app')

2. 在模板中使用组件

<template>
  <div>
    <!-- 表单组件 -->
    <by-form :model="formData" :rules="rules">
      <by-form-item label="用户名" prop="username">
        <el-input v-model="formData.username" />
      </by-form-item>
    </by-form>

    <!-- 表格组件 -->
    <by-table :data="tableData" :columns="columns" />

    <!-- 分页组件 -->
    <by-pager :total="100" :current-page="1" :page-size="10" />
  </div>
</template>

<script setup>
import { reactive, ref } from 'vue'

const formData = reactive({
  username: '',
})

const rules = {
  username: [{ required: true, message: '请输入用户名', trigger: 'blur' }],
}

const tableData = ref([])
const columns = ref([])
</script>

组件组合使用

表单 + 表格 + 分页

<template>
  <div>
    <!-- 搜索表单 -->
    <by-form :model="searchForm" @submit="handleSearch">
      <by-form-item label="关键词" prop="keyword">
        <el-input v-model="searchForm.keyword" placeholder="请输入关键词" />
      </by-form-item>
      <by-form-item>
        <el-button type="primary" @click="handleSearch">搜索</el-button>
        <el-button @click="handleReset">重置</el-button>
      </by-form-item>
    </by-form>

    <!-- 数据表格 -->
    <by-table :data="tableData" :columns="columns" name="user-table" :auto-height="true" />

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

<script setup>
import { reactive, ref, onMounted } from 'vue'

const searchForm = reactive({
  keyword: '',
})

const tableData = ref([])
const columns = ref([
  { field: 'id', title: 'ID', width: 80 },
  { field: 'name', title: '姓名', width: 120 },
  { field: 'email', title: '邮箱', width: 200 },
  { field: 'createTime', title: '创建时间', width: 180 },
])

const pagination = reactive({
  currentPage: 1,
  pageSize: 10,
  total: 0,
})

const handleSearch = () => {
  pagination.currentPage = 1
  fetchData()
}

const handleReset = () => {
  searchForm.keyword = ''
  pagination.currentPage = 1
  fetchData()
}

const handlePageChange = (page) => {
  pagination.currentPage = page
  fetchData()
}

const handleSizeChange = (size) => {
  pagination.pageSize = size
  pagination.currentPage = 1
  fetchData()
}

const fetchData = async () => {
  // 模拟 API 调用
  const response = await mockApi({
    keyword: searchForm.keyword,
    page: pagination.currentPage,
    size: pagination.pageSize,
  })

  tableData.value = response.data
  pagination.total = response.total
}

onMounted(() => {
  fetchData()
})

// 模拟 API
const mockApi = (params) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({
        data: [
          { id: 1, name: '张三', email: 'zhangsan@example.com', createTime: '2024-01-01' },
          { id: 2, name: '李四', email: 'lisi@example.com', createTime: '2024-01-02' },
        ],
        total: 100,
      })
    }, 500)
  })
}
</script>

最佳实践

1. 组件命名规范

• 使用 by- 前缀区分自定义组件
• 表格组件建议设置唯一的 name 属性用于列宽缓存

2. 表单验证

const rules = {
  username: [
    { required: true, message: '请输入用户名', trigger: 'blur' },
    { min: 3, max: 20, message: '长度在 3 到 20 个字符', trigger: 'blur' },
  ],
  email: [
    { required: true, message: '请输入邮箱地址', trigger: 'blur' },
    { type: 'email', message: '请输入正确的邮箱地址', trigger: 'blur' },
  ],
}

3. 表格配置

const columns = [
  { field: 'id', title: 'ID', width: 80, fixed: 'left' },
  { field: 'name', title: '姓名', width: 120 },
  { field: 'email', title: '邮箱', width: 200 },
  {
    title: '操作',
    width: 120,
    fixed: 'right',
    slots: { default: 'operate' },
  },
]

4. 分页配置

const pagination = reactive({
  currentPage: 1,
  pageSize: 10,
  total: 0,
  pageSizes: [10, 20, 50, 100],
})

常见问题

Q: 如何自定义表格列？

A: 使用 customColumnConfig 配置和 @setColumn 事件。

Q: 如何实现表格行高自适应？

A: 设置 :auto-height="true" 属性。

Q: 如何缓存表格列宽？

A: 给表格组件设置唯一的 name 属性。

Q: 如何实现表单重置？

A: 使用表单的 resetFields() 方法或手动重置数据。

更多示例

查看 组件文档 获取更多使用示例和 API 说明。