umy-ui 组件库使用指南

项目适配度自测

🔍 是否在开发 Vue 2.0 桌面端应用？
🔍 是否需要处理万级以上数据表格渲染？
🔍 是否需要高度可定制的表格交互功能？

说明：3个问题中至少2个回答"是"，则本组件库能显著提升开发效率。

一、核心功能解析

1.1 组件能力矩阵

组件名	核心能力	适用场景	性能优化
UTable	基础表格渲染、固定列、合并单元格	数据展示、常规编辑	虚拟滚动支持
UxGrid	大数据树形表格、行拖拽、列筛选	层级数据展示、高频编辑	懒加载子节点
Button	主题定制、状态切换	表单提交、操作触发	-
Icon	自定义图标库集成	按钮图标、状态标识	-

1.2 核心特性展示

📌 虚拟滚动技术
通过只渲染可视区域数据解决大数据渲染卡顿问题，支持10万+数据流畅滚动。

<!-- examples/pages/umycomponent/virtualScrolling.vue -->
<u-table 
  :data="bigData" 
  :use-virtual="true" 
  row-height="60" 
  height="500">
  <!-- 列定义 -->
</u-table>

💡 提示：启用虚拟滚动时必须指定height和row-height属性，否则会自动关闭优化。

二、快速上手流程

2.1 环境准备

🔍 安装步骤：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/umy/umy-ui

# 安装依赖
cd umy-ui && npm install

# 构建组件库
npm run lib

2.2 基础使用示例

📌 全局引入（main.js）

import Vue from 'vue'
import UmyUi from 'umy-ui'
import 'umy-ui/lib/theme-chalk/index.css'

Vue.use(UmyUi)

📌 按需引入（推荐）

import { UTable, UxGrid } from 'umy-ui'
import 'umy-ui/lib/theme-chalk/table.css'
import 'umy-ui/lib/theme-chalk/ux-grid.css'

export default {
  components: {
    UTable,
    UxGrid
  }
}

2.3 基础表格实现

<!-- 基础表格示例 -->
<template>
  <u-table :data="tableData" border>
    <u-table-column prop="name" label="姓名"></u-table-column>
    <u-table-column prop="age" label="年龄"></u-table-column>
    <u-table-column prop="address" label="地址"></u-table-column>
  </u-table>
</template>

<script>
export default {
  data() {
    return {
      tableData: [
        { name: '王小虎', age: 15, address: '上海市普陀区' },
        // 更多数据...
      ]
    }
  }
}
</script>

三、深度配置指南

3.1 表格配置（基础）

基础参数配置

参数名	默认值	适用场景	修改建议
data	[]	所有表格	大数据时使用函数返回
height	0	固定高度表格	设为500-600px获得最佳体验
border	true	数据密集表格	数据稀疏时设为false
use-virtual	false	数据量>200条	必须同时设置height

// 基础配置示例
{
  data: [],
  height: 500,
  border: true,
  useVirtual: true,
  rowHeight: 60
}

3.2 表格配置（进阶）

高级功能配置

树形表格配置

{
  treeConfig: {
    children: 'children', // 子节点字段名
    indent: 20, // 缩进像素
    expandAll: false, // 是否默认展开
    lazy: true, // 是否懒加载
    load: this.loadChildren // 加载函数
  }
}

编辑功能配置

{
  editConfig: {
    mode: 'cell', // cell/row
    trigger: 'click', // click/dblclick
    autoClear: true // 点击其他区域清除编辑状态
  }
}

3.3 主题定制（专家）

主题样式定制

📌 主题变量修改
修改theme/common/var.scss文件自定义主题：

// 主色调修改
$--color-primary: #1890ff;

// 表格行高
$--table-row-height: 60px;

🔍 重新构建主题：

npm run lib:theme

四、常见问题解决

4.1 配置文件问题

package.json

问题：安装依赖后运行报错
解决：删除node_modules和package-lock.json后重新安装

gulpfile.js

问题：主题构建失败
解决：检查Node版本是否≥10.0.0，安装gulp-cli：npm install -g gulp-cli

4.2 排错指南

1. 表格不显示数据
   → 检查data格式是否为数组，确认prop与数据字段匹配

2. 虚拟滚动失效
   → 确认同时设置了height和use-virtual: true

3. 树形表格加载异常
   → 检查tree-config中的children字段是否正确

4. 样式错乱
   → 确认只引入了一个版本的组件样式

5. 编辑后数据不更新
   → 检查是否使用reloadData方法更新表格

五、扩展与生态

5.1 自定义组件开发

📌 组件扩展路径：packages/目录下创建新组件，参考现有组件结构

// 组件入口文件示例 packages/custom-component/index.js
import component from './src/component.vue'

component.install = function(Vue) {
  Vue.component(component.name, component)
}

export default component

5.2 社区资源

• 示例项目：examples/目录包含30+表格使用场景
• API文档：examples/components/u-table-component/apiConfig/目录下
• 主题定制：支持与ElementUI主题无缝融合

附录：文件结构速查

umy-ui/
├── packages/        # 组件源码
├── theme/           # 样式主题
├── examples/        # 使用示例
├── index.js         # 入口文件
└── gulpfile.js      # 构建配置