@guoyg578/k-ui
v0.1.10
Published
可复用的 Vue 3 组件库 (K 前缀)，基于 reka-ui (headless) + Tailwind v4 设计令牌。
Maintainers
guoyg578Readme
k-ui
一套可复用的 Vue 3 组件库（K 前缀），基于 reka-ui（headless）+ Tailwind v4 设计令牌。
安装
pnpm add @guoyg578/k-ui
# 必需 peer 依赖
pnpm add vue reka-ui @lucide/vue
# 可选：仅用到 KDatePicker 时
pnpm add @vuepic/vue-datepicker date-fns需要 Tailwind v4：组件大量使用工具类（
bg-ink-200/text-brand-500/size-4…），这些类必须由你项目自己的 Tailwind 生成。
引入样式 ⚠️ 最关键
在全局 CSS 入口（即 @import "tailwindcss" 所在文件）：
@import "tailwindcss";
/* 设计令牌 + 组件基础类（含 @theme / @layer，必须交给 Tailwind 处理）*/
@import "@guoyg578/k-ui/styles/tokens.css";
@import "@guoyg578/k-ui/styles/components.css";
/* 已编译的组件作用域样式（纯 CSS，含弹层 menu / 日期选择器样式）*/
@import "@guoyg578/k-ui/css";
/* ⚠️ 让 Tailwind 扫描 k-ui 产物里出现的工具类，否则颜色/间距全部散架。
路径相对本 CSS 文件，按你的目录层级调整到 node_modules。 */
@source "../../node_modules/@guoyg578/k-ui/dist";
- Tailwind v4 默认不扫描 node_modules，
@source那一行必不可少。- 暗色模式：
tokens.css自带:root[data-theme="dark"]覆盖，设<html data-theme="dark">即生效；不设则保持亮色。
快速上手
<script setup lang="ts">
import { KButton, KDialog, KMessage } from '@guoyg578/k-ui'
import { ref } from 'vue'
const open = ref(false)
</script>
<template>
<KButton type="primary" @click="open = true">打开</KButton>
<KDialog v-model:open="open" title="示例" footer @confirm="KMessage.success('done')">
Hello from k-ui.
</KDialog>
</template>KConfirmDialog（配useConfirm）：在根组件挂一次<KConfirmDialog />。v-reveal/v-spotlight指令：import { installDirectives } from '@guoyg578/k-ui'后installDirectives(app)。KMessage（函数式 toast）开箱即用，首次调用自动挂载容器。
组件清单（70+ 常用组件）
- 通用 / 输入：
KButton(+KButtonGroup) ·KInput·KTextarea·KInputNumber·KSearchBar·KTag·KText·KTime·KSpace - 选择：
KSelect·KCombobox（可搜索+多选）·KAutoComplete·KCascader·KTreeSelect·KDatePicker·KTimePicker - 表单：
KSwitch·KCheckbox(+KCheckboxGroup) ·KRadio(+KRadioGroup，含button分段态) ·KForm·KFormField·KRate·KDynamicTags·KDynamicInput·KTransfer·KMention - 反馈 / 弹层：
KConfirmDialog·KDialog·KDrawer·KTooltip·KPopover·KPopconfirm·KDropdown·KAlert·KMessage（函数式 toast）·KNotification - 数据展示：
KDataTable·KPagination·KEmpty·KLoadingOverlay·KRefetchOverlay·KProgress·KSpin·KAvatar(+KAvatarGroup) ·KBadge·KStatistic·KCollapse(+KCollapseItem) ·KTimeline(+KTimelineItem) ·KList(+KListItem) ·KCalendar·KCode·KDescriptions - 骨架屏：
KSkeleton·KListSkeleton·KGridSkeleton - 布局：
KLayout(+KLayoutHeader/KLayoutContent/KLayoutSider) ·KDivider·KGrid(+KGridItem) - 导航：
KTabs·KBreadcrumb·KMenu（侧边菜单，含子菜单 / 折叠 hover 飞出，路由无关，@select驱动导航） - 容器：
KCard·KResult·KSteps·KTypography（原生 HTML 文章排版） - 媒体：
KImage·KImageViewer·KCarousel·KUpload(+KUploadDragger) - 页面辅助：
KBackTop·KAffix·KAnchor·KWatermark·KNumberAnimation·KCountdown - 高级：
KCommandPalette（Cmd+K）·KVirtualList·KResizablePanel·KTreeView·KDiff（LCS 文本对比） - 主题：
KThemeToggleButton（无状态，v-model:mode，状态由宿主管理） - 指令：
v-reveal（滚动入场）/v-spotlight（鼠标跟随光晕），需installDirectives(app)
辅助导出：useConfirm()、KMessage、installDirectives、类型 ConfirmOptions / ThemeMode / FormRule / FormFieldRef / TreeNode / CmdItem / UploadFile / MessageOptions。
依赖（peer dependencies）
| 依赖 | 用途 |
|---|---|
| vue ^3.5 | 运行时 |
| reka-ui ^2 | 大量 headless 组件（Dialog / Select / Tooltip / Tabs …） |
| @lucide/vue ^1 | 图标 |
| Tailwind v4 | 工具类 + 设计令牌（tokens.css / components.css） |
| @vuepic/vue-datepicker + date-fns | 可选 —— 仅 KDatePicker 用到（v13 依赖 date-fns 的 zhCN locale） |
本库不依赖任何路由库。
KBreadcrumb的链接项渲染为原生<a href>，点击派发item-click事件，由宿主自行导航（如router.push）。
排错速查
| 现象 | 原因 | 解决 |
|---|---|---|
| 颜色全是默认 / 输入框无边框 / 骨架屏不动 | 漏了引入样式 | 引入 tokens.css + components.css + css |
| 工具类（size-4、rounded-lg）不生效 | 缺 @source，或项目不是 Tailwind v4 | 加 @source ".../@guoyg578/k-ui/dist"，接入 Tailwind v4 |
| 切换主题按钮点了没反应 | KThemeToggleButton 无状态 | 接 v-model:mode 并自行应用 data-theme |
| 暗色模式不生效 | 没设 <html data-theme="dark"> | 自己控制该属性 |
| KConfirmDialog 不弹出 | 没在根组件挂载，或挂了多个 | 全局只挂一个 <KConfirmDialog /> |
| 图标不显示 | 没装 @lucide/vue | pnpm add @lucide/vue |
备注
- 文案中文硬编码（「搜索」「确定」「暂无数据」等），需 i18n 自行替换。
- CSS 类与设计令牌统一用
k-前缀（k-input/--k-surface…），与宿主项目自有样式一般不冲突。