组件

1.KFBtn //按钮组件
## 组件用法示例

### 1. KFBtn（按钮组件）

```vue
<template>
  <KFButton type="primary">主要按钮</KFButton>
  <KFButton type="danger">危险按钮</KFButton>
  <KFButton type="primary" :disabled="true">禁用按钮</KFButton>
</template>

2. KFDialog（对话框组件）

<template>
  <KFDialog v-model:visible="dialogVisible" title="标题">
    <div>内容区域</div>
    <template #footer>
      <KFButton @click="dialogVisible = false">取消</KFButton>
      <KFButton type="primary" @click="onConfirm">确定</KFButton>
    </template>
  </KFDialog>
  <KFButton @click="dialogVisible = true">打开对话框</KFButton>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const dialogVisible = ref(false)
const onConfirm = () => {
  dialogVisible.value = false
}
</script>

3. KFInput（输入框组件）

<template>
  <KFInput v-model="inputValue" width="300px" placeholder="请输入内容" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
const inputValue = ref('')
</script>

4. KFSelect（下拉选择组件）

<template>
  <KFSelect v-model="selectValue" :options="options" placeholder="请选择" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
const selectValue = ref('')
const options = [
  { label: '选项一', value: 1 },
  { label: '选项二', value: 2 }
]
</script>

5. KFTable（表格组件）

<template>
  <KFTable :columns="columns" :table-data="tableData" :pagination="true" />
</template>
<script setup lang="ts">
const columns = [
  { prop: 'name', label: '姓名' },
  { prop: 'age', label: '年龄' }
]
const tableData = [
  { name: '张三', age: 25 },
  { name: '李四', age: 30 }
]
</script>

Props 属性

| 属性名 | 说明 | 类型 | 默认值 | |---------------------|------------------------------|----------------------------------------|--------------| | loading | 表格加载中 | boolean | false | | allData | 是否全量数据（前端分页） | boolean | false | | defaultSort | 默认排序字段 | Record<string, string> | {} | | pageInfo | 分页信息 | {currentPage:number;pageSize:number;totalCount:number;} | {currentPage:1,pageSize:10,totalCount:0} | | rowKey | 行key字段 | string | '' | | sortChange | 自定义排序方法 | Function | () => {} | | tableData | 表格数据 | object[] | [] | | columns | 表格列配置 | any[] | [] | | currentPage | 当前页 | number | 1 | | totalCount | 总条数 | number | 0 | | params | 请求参数 | object | {} | | pagination | 是否显示分页器 | boolean | true | | showExpand | 是否显示展开行 | boolean | false | | showExpandTitle | 展开行标题 | string | '' | | showExpandProp | 展开行属性 | string | '' | | showExpandColWidth | 展开行列宽 | number | 100 | | children | 子表格字段 | string | '' | | hasChildren | 子表格是否有子级 | boolean | false | | filterMethod | 行过滤方法 | (row:object)=>boolean | ()=>true | | expandedRowKeys | 展开行key | number[] | string[] | [] | | defaultExpandAll | 是否默认展开所有 | boolean | false | | highlight | 是否高亮 | boolean | false | | searchValue | 搜索值 | string | '' | | highlightField | 高亮字段 | string | '' | | paginationLayout | 分页器配置 | string | 'total, sizes, prev, pager, next, jumper' | | filterDataMethod | 数据过滤方法 | (row:any)=>any | - | | getRowClass | 自定义行样式 | (row:object,rowIndex:number)=>string | ()=>'' |

columns 属性说明

| 属性名 | 说明 | 类型 | |---------------------|------------------------------|--------------| | prop | 字段名（必填） | string | | sortable | 是否可排序 | boolean | | label | 列名 | string | | align | 对齐方式 | string | | width | 列宽 | number|string| | fixed | 是否固定 | boolean | | resizable | 列宽是否可拖动 | boolean | | type | 类型 | string | | showOverflowTooltip | 超出隐藏并显示tooltip | boolean | | renderHTML | 自定义渲染 | Function | | renderAsync | 自定义异步渲染 | Function | | formatter | 自定义格式化 | Function |

事件

| 事件名 | 说明 | 回调参数 | |------------------|--------------------|-------------------------------| | getList | 获取数据 | (pageInfo) | | update:params | 更新请求参数 | (params) | | update:pageInfo | 更新分页信息 | (pageInfo) | | sort-change | 排序变化 | ({column, prop, order}) |

方法（ref调用）

const tableRef = ref()
tableRef.value.clearSort(column: string) // 清除指定列排序

插槽

• 默认插槽：自定义单元格内容
• expand：自定义展开行内容

<KFTable :columns="columns" :table-data="tableData">
  <template #default="{ row, column, $index }">
    <span>{{ row[column.prop] }}</span>
  </template>
  <template #expand="{ row }">
    <div>自定义展开内容：{{ row.name }}</div>
  </template>
</KFTable>

6. CustomCardTable（卡片式表格组件）

<template>
  <CustomCardTable
    v-model:items="tableItems"
    :column-num="3"
    :row-width="400"
  >
    <template #default="{ item, updateItem }">
      <span>{{ item.value }}</span>
    </template>
  </CustomCardTable>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const tableItems = ref([
  { label: '姓名', value: '张三' },
  { label: '年龄', value: '25' }
])
</script>

// 卡片式表格组件参数说明
interface TableItem {
  label: string;      // 标签名
  value?: string | number; // 值
  prop?: string;      // 属性名
  slot?: string;      // 自定义插槽名
}

interface Props {
  items: TableItem[];           // 表格数据，必填
  columnNum?: number;           // 列数，默认2
  rowWidth?: string | number;   // 单元格宽度，默认336px
}

<!-- 使用示例 -->
<template>
  <CustomCardTable
    v-model:items="tableItems"
    :column-num="3"
    :row-width="400"
  >
    <template #default="{ item, updateItem }">
      <span>{{ item.value }}</span>
    </template>
  </CustomCardTable>
</template>

插槽说明：

• 默认插槽可以自定义每个单元格的内容
• 插槽参数：
  • item: TableItem - 当前项数据
  • updateItem: (newItem: TableItem) => void - 更新当前项数据的方法

使用update-item方法示例：

<template>
  <CustomCardTable v-model:items="tableItems">
    <template #default="{ item, updateItem }">
      <!-- 使用DInput组件实现数据双向绑定 -->
      <DInput
        :model-value="item.value"
        @update:model-value="(newValue) => updateItem({ ...item, value: newValue })"
      />
      
      <!-- 或者使用原生输入框 -->
      <input
        :value="item.value"
        @input="(e) => updateItem({ ...item, value: e.target.value })"
      />
    </template>
  </CustomCardTable>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const tableItems = ref([
  { label: '姓名', value: '张三' },
  { label: '年龄', value: '25' }
])
</script>

说明：

1. updateItem方法用于更新单个表格项的数据
2. 需要通过v-model:items绑定数据以实现双向数据绑定

7. KFDrawer（抽屉组件）

<template>
  <KFDrawer v-model:visible="drawerVisible" title="抽屉标题" :width="600" :footer="true" :before-close="beforeClose">
    <div>抽屉内容</div>
    <template #footer-left>
      <span>自定义左侧内容</span>
    </template>
    <template #footer>
      <KFButton @click="drawerVisible = false">取消</KFButton>
      <KFButton type="primary" @click="onConfirm">确定</KFButton>
    </template>
  </KFDrawer>
  <KFButton @click="drawerVisible = true">打开抽屉</KFButton>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const drawerVisible = ref(false)
const beforeClose = () => {
  // 关闭前逻辑
}
const onConfirm = () => {
  drawerVisible.value = false
}
</script>

Props 属性

| 属性名 | 说明 | 类型 | 默认值 | |-------------|----------------|----------|----------| | visible | 是否显示抽屉 | boolean | false | | title | 抽屉标题 | string | '' | | beforeClose | 关闭前回调 | Function | () => {} | | width | 抽屉宽度(px) | number | 540 | | footer | 是否显示底部 | boolean | true |

事件

| 事件名 | 说明 | 回调参数 | |------------------|----------------|----------| | update:visible | 显隐切换 | (visible)|

插槽

• 默认插槽：抽屉内容
• footer-left：底部左侧自定义内容
• footer：底部自定义内容（覆盖默认按钮）

方法

const tableRef = ref()
tableRef.value.clearSort(column: string) // 清除指定列排序

插槽

• 默认插槽：自定义单元格内容
• expand：自定义展开行内容

<KFTable :columns="columns" :table-data="tableData">
  <template #default="{ row, column, $index }">
    <span>{{ row[column.prop] }}</span>
  </template>
  <template #expand="{ row }">
    <div>自定义展开内容：{{ row.name }}</div>
  </template>
</KFTable>

8. KFQuarterPicker（季度选择器）

<template>
  <KFQuarterPicker v-model="quarter" format="YYYY年第q季度" value-format="YYYYQQ" :placeholder="'请选择季度'" :width="240" :clearable="true" @change="onChange" :disabled-date="disabledQuarter" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
const quarter = ref('202401')
const onChange = (val) => {
  // 选中季度变化
}
const disabledQuarter = (year, quarterIndex) => {
  // 禁用某些季度
  return false
}
</script>

Props 属性

| 属性名 | 说明 | 类型 | 默认值 | |---------------|------------------------------|----------|----------------| | modelValue/v-model | 绑定值 | string/Date | - | | format | 显示格式（如YYYY年第q季度） | string | 'YYYY年第q季度'| | value-format | 绑定值格式（YYYYMM/QQ等） | string | - | | placeholder | 占位内容 | string | '请选择季度' | | width | 输入框宽度 | number | 240 | | clearable | 是否可清空 | boolean | true | | disabled-date | 禁用季度方法 | Function | - |

事件

| 事件名 | 说明 | 回调参数 | |----------|--------------|------------| | change | 选择变化 | (value) |

方法（ref调用）

| 方法名 | 说明 | 参数 | |----------------|--------------|--------------| | getPrevYear | 上一年 | - | | getNextYear | 下一年 | - |

插槽

• 默认插槽：自定义单元格内容
• expand：自定义展开行内容

<KFTable :columns="columns" :table-data="tableData">
  <template #default="{ row, column, $index }">
    <span>{{ row[column.prop] }}</span>
  </template>
  <template #expand="{ row }">
    <div>自定义展开内容：{{ row.name }}</div>
  </template>
</KFTable>

9. KFTimeComb（时间选择面板）

<template>
  <KFTimeComb v-model:currentTime="timeRange" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
const timeRange = ref([])
</script>

Props 属性

| 属性名 | 说明 | 类型 | 默认值 | |---------------|----------------|----------|----------| | currentTime | 当前时间范围 | array | [] |

事件

| 事件名 | 说明 | 回调参数 | |----------------------|----------------|------------| | update:currentTime | 时间变化 | (array) |

用法说明

• 支持日、周、月、年、季度等多种快捷时间选择。
• 通过v-model:currentTime获取选中的时间区间。

插槽

• 默认插槽：自定义单元格内容
• expand：自定义展开行内容

<KFTable :columns="columns" :table-data="tableData">
  <template #default="{ row, column, $index }">
    <span>{{ row[column.prop] }}</span>
  </template>
  <template #expand="{ row }">
    <div>自定义展开内容：{{ row.name }}</div>
  </template>
</KFTable>

10. KFEmpty（空状态组件）

<template>
  <KFEmpty tip="暂无数据">
    <div>可自定义内容</div>
  </KFEmpty>
</template>

Props 属性

| 属性名 | 说明 | 类型 | 默认值 | |--------|------------|--------|----------| | tip | 提示文字 | string | 暂无内容 |

插槽

• 默认插槽：自定义空状态内容

方法

const tableRef = ref()
tableRef.value.clearSort(column: string) // 清除指定列排序

插槽

• 默认插槽：自定义单元格内容
• expand：自定义展开行内容

<KFTable :columns="columns" :table-data="tableData">
  <template #default="{ row, column, $index }">
    <span>{{ row[column.prop] }}</span>
  </template>
  <template #expand="{ row }">
    <div>自定义展开内容：{{ row.name }}</div>
  </template>
</KFTable>

11. CustomCardTable（卡片式表格组件）

<template>
  <CustomCardTable
    v-model:items="tableItems"
    :column-num="3"
    :row-width="400"
  >
    <template #default="{ item, updateItem }">
      <span>{{ item.value }}</span>
    </template>
  </CustomCardTable>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const tableItems = ref([
  { label: '姓名', value: '张三' },
  { label: '年龄', value: '25' }
])
</script>

// 卡片式表格组件参数说明
interface TableItem {
  label: string;      // 标签名
  value?: string | number; // 值
  prop?: string;      // 属性名
  slot?: string;      // 自定义插槽名
}

interface Props {
  items: TableItem[];           // 表格数据，必填
  columnNum?: number;           // 列数，默认2
  rowWidth?: string | number;   // 单元格宽度，默认336px
}

<!-- 使用示例 -->
<template>
  <CustomCardTable
    v-model:items="tableItems"
    :column-num="3"
    :row-width="400"
  >
    <template #default="{ item, updateItem }">
      <span>{{ item.value }}</span>
    </template>
  </CustomCardTable>
</template>

插槽说明：

• 默认插槽可以自定义每个单元格的内容
• 插槽参数：
  • item: TableItem - 当前项数据
  • updateItem: (newItem: TableItem) => void - 更新当前项数据的方法

使用update-item方法示例：

<template>
  <CustomCardTable v-model:items="tableItems">
    <template #default="{ item, updateItem }">
      <!-- 使用DInput组件实现数据双向绑定 -->
      <DInput
        :model-value="item.value"
        @update:model-value="(newValue) => updateItem({ ...item, value: newValue })"
      />
      
      <!-- 或者使用原生输入框 -->
      <input
        :value="item.value"
        @input="(e) => updateItem({ ...item, value: e.target.value })"
      />
    </template>
  </CustomCardTable>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const tableItems = ref([
  { label: '姓名', value: '张三' },
  { label: '年龄', value: '25' }
])
</script>

### 12.
```vue

重要说明

1.使用yalc测试当前组件，需要先安装yalc

# 重要说明

## 1. 使用 yalc 测试当前组件库
### 步骤一：全局安装 yalc（如未安装可跳过此步）
```bash
npm install -g yalc

2. 必须打包后，使用yalc发布

npm run build-only
yalc publish

3. 必须在项目中安装yalc

yalc link @dang_8899/xl-ui // 首次安装
yalc update @dang_8899/xl-ui // 后续更新

如果更新组件库并没有生效，必须确认自己是否有重复上述操作，如没有，把node_modules删除,并重新安装，如果npm有安装过当前组件，需要删除，因为会和yalc的版本冲突，最后最后，重要提醒，一定要使用webstorm打包，因为vscode会有缓存，如果webstorm上有.vscode文件夹也有删除，因为会有缓存,.idea文件夹也删除

XL-UI 工具函数文档

目录

1. 数据处理
2. UI 交互
3. DOM 操作
4. 树形结构处理
5. 主题设置
6. 其他工具

1. 数据处理

getDataFunc

解构接口返回数据，自动处理标准接口格式。

import { getDataFunc } from '@dang_8899/xl-ui'

// 示例
const response = {
  data: {
    code: '00000',
    data: { name: 'xl' }
  }
}
const result = getDataFunc(response) // { name: 'xl' }

getEnumKeyByValue

根据枚举值获取枚举键名。

import { getEnumKeyByValue } from '@dang_8899/xl-ui'

// 示例
enum Status {
  Active = 1,
  Inactive = 0
}
const key = getEnumKeyByValue(Status, 1) // 'Active'

enumToOptions

将枚举对象转换为选项列表，常用于下拉选择框。

import { enumToOptions } from '@dang_8899/xl-ui'

// 示例
enum Status {
  Active = 1,
  Inactive = 0
}
const options = enumToOptions(Status)
// 结果：[
//   { label: 'Active', value: 1 },
//   { label: 'Inactive', value: 0 }
// ]

2. UI 交互

openVn

快捷消息提示。

import { openVn } from '@dang_8899/xl-ui'

// 示例
openVn('操作成功', 'success')
openVn('发生错误', 'error')

openFunc

确认对话框。

import { openFunc } from '@dang_8899/xl-ui'

// 示例
openFunc({
  title: '提示',
  content: '确定删除吗？',
  cb: () => {
    // 确认后的回调
    console.log('用户点击确定')
  }
})

commonOper

通用操作回调处理。

import { commonOper } from '@dang_8899/xl-ui'

// 示例
const visible = ref(true)
const getList = () => {
  // 刷新列表
}
commonOper(true, visible, getList)

3. DOM 操作

copyText

复制文本到剪贴板。

import { copyText } from '@dang_8899/xl-ui'

// 示例
const success = copyText('要复制的文本')
if (success) {
  console.log('复制成功')
}

getDownload

文件下载。

import { getDownload } from '@dang_8899/xl-ui'

// 示例
getDownload({
  url: 'https://example.com/file.pdf',
  fileName: 'document.pdf'
})

4. 树形结构处理

treeFilterNode

树节点过滤，支持关键字搜索。

import { treeFilterNode } from '@dang_8899/xl-ui'

// 示例
const treeData = [
  {
    orgId: 1,
    orgName: '总部',
    child: [
      { orgId: 2, orgName: '技术部' }
    ]
  }
]
const expandKeys: number[] = []
const filteredTree = treeFilterNode(treeData, '技术', expandKeys)

5. 主题设置

setThemeColor

设置主题色。

import { setThemeColor } from '@dang_8899/xl-ui'

// 示例
setThemeColor('#615DEE')

6. 其他工具

generateRandomId

生成随机ID。

import { generateRandomId } from '@dang_8899/xl-ui'

// 示例
const id = generateRandomId() // '1679012345_abc123def'

isAbsoluteUrl

判断是否为绝对路径URL。

import { isAbsoluteUrl } from '@dang_8899/xl-ui'

// 示例
isAbsoluteUrl('https://example.com') // true
isAbsoluteUrl('/path/to/file') // false

isOverflow

检测元素内容是否溢出。

import { isOverflow } from '@dang_8899/xl-ui'

// 示例
const element = document.querySelector('.some-element')
if (element && isOverflow(element)) {
  console.log('内容溢出')
}

注意事项

• 所有方法都经过 TypeScript 类型检查
• UI 相关方法依赖于 Element Plus
• 建议在使用前先查看对应方法的类型定义，以了解详细的参数要求