@guoyg578/k-ui

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 飞出 / 选中项左侧品牌色竖条 activeBar，路由无关，@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）

本库不依赖任何路由库。KBreadcrumb 的链接项渲染为原生 <a href>，点击派发 item-click 事件，由宿主自行导航（如 router.push）。

排错速查

备注

• 文案中文硬编码（「搜索」「确定」「暂无数据」等），需 i18n 自行替换。
• CSS 类与设计令牌统一用 k- 前缀（k-input / --k-surface …），与宿主项目自有样式一般不冲突。