KivaUI

Kiva 组件库 — Vue 2.x 组件集合（UMD 单文件打包）

一个面向大屏 / 可视化 / 后台管理场景的 Vue 2.x 组件库，全部组件打包为单个 UMD 文件，一次引入即可使用。

仅包含 Vue 组件。HTTP 请求 / 路由 / WebSocket / 跨窗口通讯 / Excel 导出 / Canvas 拓扑 等工具类已剥离，由外部项目按需单独引入。

在线演示台：https://lvminjie5201314.github.io/music/kiva-ui/

目录

• 安装
• 快速开始
• 声明式组件
  • kiva-button 按钮组件
  • kiva-switch 开关组件
  • kiva-odometer 数字滚动组件
  • kiva-load-more 滚动加载更多
  • kiva-select 下拉选择
  • kiva-table 表格
  • kiva-date-picker 日期选择器
  • kiva-time-picker 时间选择器
  • kiva-year-picker 年份选择器
  • kiva-month-picker 月份选择器
  • kiva-tree 树形控件
  • kiva-dialog 对话框
• 命令式组件
  • KivaLoading 全局 Loading
  • KivaMessage 全局消息提示
  • kivaDialog 命令式对话框
• 按需引入
• 外部依赖
• 构建

安装

npm install kiva-ui

peerDependencies: 需要项目已安装 Vue 2.6+ / 2.7。

快速开始

ES Module（推荐）

import Vue from 'vue';
import KivaUI from 'kiva-ui';

Vue.use(KivaUI);

CommonJS

const Vue = require('vue');
const KivaUI = require('kiva-ui');

Vue.use(KivaUI);

浏览器 <script> 引入

<!-- 必须先引入 Vue -->
<script src="https://unpkg.com/[email protected]/dist/vue.js"></script>
<!-- 引入 KivaUI（压缩版） -->
<script src="https://unpkg.com/kiva-ui/dist/kiva-ui.min.js"></script>
<!-- window.Vue 存在时会自动注册所有组件，window.KivaUI 可用 -->

注册后即可在模板中使用所有 kiva-* 组件：

<template>
  <kiva-button type="primary" @click="onClick">点击</kiva-button>
  <kiva-select v-model="val" :options="opts" />
</template>

重要：CDN 方式下，所有导出（组件定义、命令式 API）都挂在 window.KivaUI 对象上，不会作为顶层全局变量暴露。直接写 kivaDialog.show(...)、KivaMessage.success(...) 会报 ReferenceError: xxx is not defined。必须通过 window.KivaUI.xxx 访问，或先解构：

// ✅ 正确：从 window.KivaUI 解构
const { KivaLoading, KivaMessage, kivaDialog } = window.KivaUI;

KivaLoading.show('加载中...');
KivaMessage.success('保存成功');
kivaDialog.show({ title: '提示', content: '操作完成' });

// ❌ 错误：kivaDialog 未定义（ReferenceError）
// kivaDialog.show({ ... });

在 Vue.use(KivaUI) 之后，Vue 组件实例内还可通过原型方法访问：this.$kivaLoading、this.$kivaMessage。

声明式组件

kiva-button 按钮组件

基础按钮，支持多种类型、朴素/圆角/圆形、加载状态、禁用、图标。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | type | String | "default" | 类型：primary / success / warning / danger / info / default | | plain | Boolean | false | 朴素按钮（透明背景） | | round | Boolean | false | 圆角按钮 | | circle | Boolean | false | 圆形按钮 | | disabled | Boolean | false | 禁用 | | loading | Boolean | false | 加载中（显示旋转图标，禁用点击） | | icon | String | "" | 图标类名 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | click | event: Event | 点击时触发（disabled/loading 时不触发） |

Slots

| 插槽 | 说明 | |------|------| | default | 按钮文本 |

示例

<kiva-button type="primary">主要按钮</kiva-button>
<kiva-button type="success" plain>朴素成功</kiva-button>
<kiva-button type="danger" round>圆角危险</kiva-button>
<kiva-button type="primary" loading>加载中</kiva-button>
<kiva-button type="info" disabled>禁用</kiva-button>
<kiva-button type="primary" icon="kiva-icon-edit">编辑</kiva-button>

kiva-switch 开关组件

开关选择器，支持自定义颜色、尺寸、禁用。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | Boolean | false | 状态（v-model） | | disabled | Boolean | false | 禁用 | | width | Number | 34 | 宽度（px） | | height | Number | 18 | 高度（px） | | activeColor | String | "#42A3D6" | 激活背景色 | | inactiveColor | String | "#395E7C" | 未激活背景色 | | dotColor | String | "#ffffff" | 圆点颜色 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | input | value: Boolean | v-model 同步 | | change | value: Boolean | 状态变化 |

示例

<kiva-switch v-model="isOpen" />

<kiva-switch
  v-model="enabled"
  :active-color="'#00e5ff'"
  :inactive-color="'#333'"
  :width="40"
  :height="22"
/>

<kiva-switch v-model="locked" disabled />

kiva-odometer 数字滚动组件

数字滚动动画组件，依赖外部 Odometer 库。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | Number | 0 | 当前数值（变化时触发滚动动画） | | duration | Number | 1000 | 动画时长（ms） | | maxAnimations | Number | Infinity | 最大动画次数 | | unit | String | "" | 单位文本 | | unitSize | String | "inherit" | 单位字号 | | unitPosition | String | "right" | 单位位置：left / right |

Slots

| 插槽 | 说明 | |------|------| | unit-left | 左侧单位（覆盖 prop） | | unit-right | 右侧单位（覆盖 prop） |

示例

<!-- 需先引入 odometer 库（dist 目录已提供） -->
<link rel="stylesheet" href="./dist/odometer-theme-minimal.css" />
<script src="./dist/odometer.min.js"></script>

<kiva-odometer :value="count" :duration="1500" unit="kWh" unit-position="right" />

<kiva-odometer :value="price">
  <template #unit-left><span style="color:#ffd700">$</span></template>
</kiva-odometer>

kiva-load-more 滚动加载更多

基于 IntersectionObserver 的触底加载组件。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | loading | Boolean | false | 是否正在加载 | | finished | Boolean | false | 是否已加载完毕 | | distance | String | "0px" | 触发距离（rootMargin 底部） | | container | String | "" | 滚动容器选择器（空=视口） | | loadingText | String | "正在加载更多..." | 加载中文本 | | finishedText | String | "没有更多数据了" | 完成文本 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | load | 无 | 触底且非 loading/finished 时触发 |

示例

<div class="list-container" style="height:400px;overflow-y:auto;">
  <div v-for="item in list" :key="item.id">{{ item.name }}</div>
  <kiva-load-more
    :loading="loading"
    :finished="finished"
    container=".list-container"
    @load="loadMore"
  />
</div>

export default {
  data() {
    return { list: [], loading: false, finished: false, page: 1 };
  },
  methods: {
    async loadMore() {
      this.loading = true;
      const data = await fetch(`/api/list?page=${this.page++}`).then(r => r.json());
      this.list.push(...data);
      this.loading = false;
      if (data.length < 10) this.finished = true;
    }
  }
};

kiva-select 下拉选择

下拉选择器，支持清除、禁用项、iframe 跨窗口点击关闭。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | String | Number | "" | 当前值（v-model） | | options | Array | [] | 选项数组 { label, value, disabled? } | | placeholder | String | "请选择" | 占位文本 | | clearable | Boolean | true | 可清除 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | input | option: Object | "" | v-model 同步（清除时为 ""） | | change | option: Object | "" | 值变化 | | clear | 无 | 清除时触发 |

示例

<kiva-select v-model="selected" :options="opts" placeholder="请选择" clearable />

<script>
export default {
  data() {
    return {
      selected: '',
      opts: [
        { label: '选项一', value: '1' },
        { label: '选项二', value: '2' },
        { label: '禁用项', value: '3', disabled: true }
      ]
    };
  }
};
</script>

kiva-table 表格

数据表格，支持斑马纹、选择列、列排序、自定义单元格（作用域插槽）。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | data | Array | [] | 行数据 | | columns | Array | [] | 列配置 | | stripe | Boolean | true | 斑马纹 | | selection | Boolean | false | 显示选择列 |

columns 配置

| 字段 | 类型 | 说明 | |------|------|------| | label | String | 列标题 | | prop | String | 数据字段名 | | width | String|Number | 列宽 | | align | String | 对齐：left / center / right | | sortable | Boolean | 可排序 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | selection-change | rows: Array | 选择变化 | | sort-change | { prop, order } | 排序变化（order: asc/desc/""） |

Scoped Slots

| 插槽名 | 作用域 | 用途 | |--------|--------|------| | header-{prop} | { column } | 自定义表头 | | {prop} | { row, index } | 自定义单元格 |

示例

<kiva-table
  :data="tableData"
  :columns="columns"
  selection
  @selection-change="onSel"
  @sort-change="onSort"
>
  <template #status="{ row }">
    <span :style="{ color: row.status === '在线' ? '#0f0' : '#f00' }">{{ row.status }}</span>
  </template>
</kiva-table>

export default {
  data() {
    return {
      tableData: [
        { id: 1, name: '设备A', status: '在线' },
        { id: 2, name: '设备B', status: '离线' }
      ],
      columns: [
        { label: 'ID', prop: 'id', sortable: true, width: '80' },
        { label: '名称', prop: 'name' },
        { label: '状态', prop: 'status', align: 'center' }
      ]
    };
  },
  methods: {
    onSel(rows) { console.log('选中:', rows); },
    onSort({ prop, order }) { console.log('排序:', prop, order); }
  }
};

kiva-date-picker 日期选择器

日期/日期时间/范围选择器，支持单面板/双面板、时间选择、范围 hover 预览。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | String | Array | "" | 当前值（范围模式为数组） | | type | String | "date" | 类型，见下 | | rangeSeparator | String | "至" | 范围分隔符 | | singlePanel | Boolean | false | 范围模式单面板 |

type 取值

| type | 说明 | |------|------| | date | 单日期 | | datetime | 单日期+时间 | | daterange | 日期范围 | | datetimerange | 日期时间范围 | | datetimestartorend | 同一天起止时间 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | input | value | v-model 同步 | | confirm | value | 点「确定」时触发 |

示例

<!-- 单日期 -->
<kiva-date-picker v-model="date" type="date" />

<!-- 日期时间 -->
<kiva-date-picker v-model="datetime" type="datetime" />

<!-- 日期时间范围（双面板） -->
<kiva-date-picker v-model="range" type="datetimerange" />

<!-- 日期范围（单面板） -->
<kiva-date-picker v-model="range" type="daterange" :single-panel="true" />

kiva-time-picker 时间选择器

时间选择器（时:分），支持 24:00 特殊值。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | String | "00:00" | 时间 HH:mm（v-model） | | disabled | Boolean | false | 禁用 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | input | time: String | v-model 同步 | | change | time: String | 确认选择时触发 |

示例

<kiva-time-picker v-model="time" />

<kiva-time-picker v-model="endTime" disabled />

kiva-year-picker 年份选择器

年份/年份范围选择器。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | String | Array | "" | 当前值（范围模式为数组） | | yearRange | Number | 5 | 面板前后年份范围（共 yearRange*2+1 个） | | type | String | "year" | year / yearrange | | rangeSeparator | String | "至" | 范围分隔符 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | input | value | v-model 同步 | | confirm | value | 点「确定」时触发 | | change | value | 点「确定」时触发 |

示例

<kiva-year-picker v-model="year" type="year" />

<kiva-year-picker v-model="yearRange" type="yearrange" :year-range="5" />

kiva-month-picker 月份选择器

月份/月份范围选择器。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | value | String | Array | "" | 格式 YYYY-MM（范围模式为数组） | | type | String | "month" | month / monthrange | | rangeSeparator | String | "至" | 范围分隔符 | | singlePlaceholder | String | "请选择月份" | 单选占位符 | | startPlaceholder | String | "开始月份" | 范围起始占位符 | | endPlaceholder | String | "结束月份" | 范围结束占位符 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | input | value | v-model 同步 | | confirm | value | 点「确定」时触发 |

示例

<kiva-month-picker v-model="month" type="month" />

<kiva-month-picker v-model="monthRange" type="monthrange" />

kiva-tree 树形控件

递归树，支持节点选择、展开/折叠、三态复选框、过滤、勾选数量限制。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | data | Array | [] | 树形数据 | | selectedId | String | Number | null | 当前选中节点 ID | | defaultExpandAll | Boolean | false | 默认展开所有节点 | | showCheckbox | Boolean | false | 显示复选框 | | defaultCheckedKeys | Array | [] | 默认勾选的 key | | maxCheck | Number | 0 | 最多勾选叶子数（0=不限） | | filterNodeMethod | Function | null | 过滤方法 (text, node) => Boolean | | autoExpandOnFilter | Boolean | true | 过滤时自动展开匹配节点 |

节点数据结构

{
  id: String|Number,      // 必填
  label: String,          // 必填
  icon: String,           // 可选: 'folder'|'meter'|'data'|'device'|'default'
  expanded: Boolean,      // 可选: 初始展开
  children: Array         // 可选: 子节点
}

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | select | node: Object | 节点选中（showCheckbox 模式下不触发） | | toggle | { node, expanded } | 展开/折叠 | | check-change | { node, checked, indeterminate, checkedKeys, checkedNodes } | 复选框变化 | | max-check-exceeded | { max, actual } | 超过 maxCheck 限制 | | filter-change | text: String | 过滤文本变化 |

Methods（通过 ref 调用）

| 方法名 | 参数 | 返回值 | 说明 | |--------|------|--------|------| | filter | text: String | - | 过滤（会清空勾选） | | getCheckedKeys | - | Array | 获取勾选的 key | | setCheckedKeys | keys: Array | - | 设置勾选 | | getHalfCheckedKeys | - | Array | 获取半选 key |

示例

<kiva-tree
  ref="tree"
  :data="treeData"
  :selected-id="selectedId"
  show-checkbox
  :max-check="20"
  :filter-node-method="filterFn"
  @select="onSelect"
  @check-change="onCheck"
/>

<script>
export default {
  data() {
    return {
      treeData: [
        {
          id: 1, label: '根节点', icon: 'folder', children: [
            { id: 2, label: '子节点1', icon: 'meter' },
            { id: 3, label: '子节点2', icon: 'data' }
          ]
        }
      ],
      selectedId: null
    };
  },
  methods: {
    filterFn(text, node) {
      return node.label.includes(text);
    },
    onSelect(node) { console.log('选中:', node); },
    onCheck({ checkedKeys }) { console.log('勾选:', checkedKeys); },
    getChecked() {
      return this.$refs.tree.getCheckedKeys();
    }
  }
};
</script>

kiva-dialog 对话框

模态对话框，支持模板用法和命令式 API。

Props

| 名称 | 类型 | 默认值 | 说明 | |------|------|--------|------| | visible | Boolean | false | 是否显示（.sync） | | title | String | "提示" | 标题 | | content | String | "" | 内容文本（被默认插槽覆盖时无效） | | width | String | "44.32vmin" | 宽度 | | confirmText | String | "确定" | 确认按钮文本 | | cancelText | String | "取消" | 取消按钮文本 | | showCancel | Boolean | true | 显示取消按钮 | | showClose | Boolean | true | 显示关闭按钮 | | showFooter | Boolean | true | 显示底部按钮区 | | closeOnClickModal | Boolean | true | 点击遮罩关闭 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | update:visible | false | .sync 同步 | | close | - | 关闭 | | cancel | - | 取消 | | confirm | - | 确认（不自动关闭，由父级控制） |

Slots

| 插槽 | 说明 | |------|------| | default | 自定义主体内容 |

示例（模板用法）

<kiva-dialog :visible.sync="visible" title="编辑" @confirm="onConfirm">
  <p>自定义内容</p>
</kiva-dialog>

<script>
export default {
  data() { return { visible: false }; },
  methods: {
    onConfirm() {
      // 处理确认逻辑
      this.visible = false;
    }
  }
};
</script>

命令式用法见 kivaDialog 命令式对话框。

命令式组件

命令式组件无需在模板中声明，调用即弹出/显示；在 Vue.use(KivaUI) 后会同时注入到 Vue.prototype，组件内可用 this.$xxx 访问。

KivaLoading 全局 Loading

全局加载遮罩，支持单例、文本更新、过渡动画。

API

import { KivaLoading } from 'kiva-ui';

KivaLoading.show(options);  // 显示（字符串简写: show("加载中")）
KivaLoading.close();        // 关闭

show() 返回 instance 对象：

| 方法名 | 参数 | 说明 | |--------|------|------| | setText | text: String | 更新文本 | | close | - | 关闭 |

示例

// 浏览器全局
KivaLoading.show('加载中...');
await fetchData();
KivaLoading.close();

// Vue 组件内
this.$kivaLoading.show({ text: '提交中' });

// 更新文本
const inst = KivaLoading.show('处理中');
inst.setText('快好了');
inst.close();

KivaMessage 全局消息提示

全局消息提示，支持 info/success/warning/error 四种类型。

API

import { KivaMessage } from 'kiva-ui';

KivaMessage(options);              // 直接调用
KivaMessage("提示文本");            // 字符串简写
KivaMessage.success(options);      // 成功
KivaMessage.warning(options);      // 警告
KivaMessage.info(options);         // 信息
KivaMessage.error(options);        // 错误

options

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | type | String | "info" | info/success/warning/error | | message | String | "" | 文本 | | duration | Number | 2000 | 显示时长（ms），0=不自动关闭 |

示例

KivaMessage.success('保存成功');
KivaMessage.error({ message: '网络错误', duration: 5000 });
KivaMessage.warning('请注意');
KivaMessage.info('提示');

// Vue 组件内
this.$kivaMessage.error('出错了');

kivaDialog 命令式对话框

命令式对话框 API，无需在模板中声明，直接调用即可弹出。

API

import { kivaDialog } from 'kiva-ui';

kivaDialog.show(options);

options

| 字段 | 类型 | 说明 | |------|------|------| | title | String | 标题 | | content | String | 内容文本 | | width | String | 宽度 | | confirmText | String | 确认按钮文本 | | cancelText | String | 取消按钮文本 | | showCancel | Boolean | 显示取消按钮 | | showFooter | Boolean | 显示底部按钮区 | | closeOnClickModal | Boolean | 点击遮罩关闭 | | onConfirm | () => Promise<Boolean\|undefined> | 确认回调（返回 false 阻止关闭） | | onCancel | Function | 取消回调 |

示例

import { kivaDialog } from 'kiva-ui';

// 简单提示
kivaDialog.show({
  title: '提示',
  content: '操作成功'
});

// 确认删除
kivaDialog.show({
  title: '确认删除',
  content: '确定要删除这条记录吗？',
  confirmText: '删除',
  cancelText: '取消',
  onConfirm: async () => {
    await deleteRecord();
    // 返回 false 可阻止关闭
  },
  onCancel: () => console.log('cancelled')
});

按需引入

除了 Vue.use(KivaUI) 全量注册外，可以单独引入组件定义，手动注册：

// 组件定义对象（需手动注册）
import { kivaButton, KivaTree, kivaDialogComponent } from 'kiva-ui';

Vue.component('kiva-button', kivaButton);
Vue.component('kiva-tree', KivaTree);
Vue.component('kiva-dialog', kivaDialogComponent);

命令式组件也可按需引入：

import { KivaLoading, KivaMessage, kivaDialog } from 'kiva-ui';

KivaLoading.show('加载中...');
KivaMessage.success('保存成功');
kivaDialog.show({ title: '提示', content: '操作完成' });

注意：按需引入命令式组件时，this.$kivaLoading / this.$kivaMessage 原型方法不会自动注入，需 Vue.use(KivaUI) 或 Vue.prototype.$kivaLoading = KivaLoading 手动设置。

外部依赖

| 依赖 | 说明 | |------|------| | vue@^2.6.0 \|\| ^2.7.0 | peerDependency，必须由项目提供 | | Odometer | kiva-odometer 组件依赖，需在使用前引入 odometer 库全局脚本（dist 目录已提供 odometer.min.js 和 odometer-theme-minimal.css） |

浏览器原生 API（无需引入）：IntersectionObserver、requestAnimationFrame、localStorage（命令式组件可选）。

构建

# 安装依赖
npm install

# 构建（生成 src/kiva-ui.js + dist/kiva-ui.min.js）
npm run build

# 验证打包产物
npm run verify

目录结构

kiva-ui/
├── src/                    # 源文件
│   ├── kivaLoading.js       # 全局 Loading（命令式组件）
│   ├── kivaMessage.js       # 全局消息提示（命令式组件）
│   ├── kivaButton.js        # 按钮组件
│   ├── kivaSwitch.js        # 开关组件
│   ├── kivaOdometer.js      # 数字滚动组件
│   ├── kivaLoadMore.js      # 滚动加载更多
│   ├── kivaSelect.js        # 下拉选择
│   ├── kivaTable.js         # 表格
│   ├── kivaDate.js          # 日期选择器
│   ├── kivaTimePicker.js    # 时间选择器
│   ├── kivaYearPicker.min.js    # 年份选择器
│   ├── kivaMonthPicker.min.js   # 月份选择器
│   ├── kivaTree.min.js      # 树形控件
│   ├── kivaDialog.js        # 对话框（含命令式 API）
│   ├── kiva-ui.js           # 打包后的未压缩合并源文件（构建产物）
│   ├── odometer.min.js     # kiva-odometer 依赖（构建时复制到 dist）
│   ├── odometer-theme-minimal.css
│   ├── utils.js            # 以下为未打包进组件库的工具源文件（供其他项目单独引入）
│   ├── bus.js              # 跨窗口通讯总线
│   ├── request.js          # HTTP 请求封装
│   ├── router.js           # Hash 路由
│   ├── socket.js           # WebSocket 客户端
│   └── exportExcel.js      # Excel 导出
├── scripts/
│   ├── build.js            # 构建脚本
│   └── verify.js           # 验证脚本
├── dist/
│   ├── kiva-ui.min.js       # UMD 压缩（约 100 KB）
│   ├── odometer.min.js     # 外部依赖（kiva-odometer 使用）
│   └── odometer-theme-minimal.css
└── package.json

License

MIT