Back to Blog

Ikun UI AI 专用核心参考手册

Archive

露出鸡脚

Published on 12/18/2025

IKun UI 是一款基于 Svelte.js 和 UnoCSS 的 UI 库,其核心特性是高度依赖 UnoCSS 预设和原子化样式。本手册旨在为 AI 提供一个精简、以 API 为中心的参考指南,使其能够理解组件的配置方式和主题定制能力。


Ⅰ. 框架与主题配置核心 (Preset & Theme Configuration)

Ikun UI 的核心设计理念是样式原子化和 UnoCSS 预设。组件样式是通过 ikun-ui/preset 中的 Shortcuts(快捷方式)和 Rules(规则)组合而成的。

配置项目描述用途/自定义方式来源引用
UnoCSS Preset@ikun-ui/preset 内置了一套基于 UnoCSS 的预设,。提供了组件所需的基本原子化样式,可以帮助用户快速引用 ikun-ui。,
Shortcuts为每个组件使用快捷方式功能组合必要的原子样式。用户可以通过覆盖 ikunShortcuts 的内容来实现自定义快捷方式,。,
Rules除了快捷方式外,预设还自定义了一些规则,用于实现组件的部分动画和阴影效果。用户可以自定义内容来覆盖默认规则,如 ikunRules,。,
主题定制可以通过简单的属性或完全自定义主题来更改样式。更改主题色只需要简单的配置。完全自定义可以修改颜色变量、快捷方式和规则。,
颜色变量预设内置了可供使用的颜色变量。用户可暴露的颜色变量 ikunColors,可以添加或覆盖默认颜色变量。,
图标借助 UnoCSS 的能力,支持使用 Iconify 中的任意图标,。图标的类名应遵循 UnoCSS 标准。

关键 API/配置项

名称类型描述
presetIkunfunction返回一个 unocss 预设。
getSafeListfunction返回 ikun-ui 快捷方式列表,通常用于避免组件样式被 Vite 错误地摇树优化 (tree-shaking)。
getCSSPreflightsfunction根据传入的颜色变量,返回颜色变量字符串,通常用于 unocss 配置的 preflights 选项。
ikunThemeobject默认主题,定义了颜色变量,用户可以覆盖或添加新的颜色变量。
ikunShortcutslist默认快捷方式列表,用户可以覆盖内容来实现自定义快捷方式。
ikunRuleslist默认规则,包含动画和阴影规则,可供用户自定义覆盖。

Ⅱ. 组件 API 参考

组件名描述核心属性 (Props)核心事件 (Events)核心插槽 (Slots)
KAffix将元素固定在目标滚动位置。top, triggerTop, bottom, triggerBottom (触发固定点距离), positionOption (fixed/absolute), listenTo (监听滚动元素)。default (自定义默认内容)。
KAlert显示重要的警告消息。type (success/error/warning/info), title, description (描述文本), showIcon, closable (是否可关闭), closeIcon (自定义关闭图标)。close (关闭时触发)。default (描述内容), title (标题内容), icon, close
KAutoComplete根据当前输入获取推荐提示。size, value (绑定值), clearable, placeholder, append/prepend (按钮图标类名), fetchSuggestions (建议回调方法)。updateValue (选择建议后), enter, search (按下 Enter 或点击按钮时触发)。default (自定义选项内容), prefix, suffix
KAvatar用于表示人或物(支持图像、图标或字符)。icon (图标类名), src (图像源), size, radius, fit (图像如何适应容器,如 fill/contain/cover 等)。error (图像加载错误时触发)。default (自定义默认内容)。
KBacktop返回顶部的按钮。right, bottom (距离屏幕右侧和底部的距离), showHeight (显示组件的滚动高度), duration (返回顶部耗时)。clickdefault (自定义默认内容)。
KBadge按钮和图标上的数字或状态标记。value (显示值,数字/字符串), max (最大值), isDot (显示为点标记), type (primary/success/error/warning/info)。default (自定义默认内容)。
KBreadcrumb显示当前页面的位置。separator (分隔符字符), separatorIcon (分隔符图标类名)。default (自定义默认内容)。
KButton常用按钮。type, size (sm/md/lg), icon, to (链接), plain (朴素), ghost (幽灵), disabled, circleclickdefault (自定义默认内容)。
KCalendar以日历形式显示数据的容器。mode (month/year), value (当前选择日期), fullscreen, validRange (有效范围), disabledDate (不可选日期函数)。select (选择日期时), panelChange (面板更改时)。header, monthFullCell/monthCell, dateFullCell/dateCell
KCard在卡片容器中整合信息。title, shadow (always/hover/never)。header (页眉内容), default (内容)。
KCarousel轮播组件。height, count (轮播数量,必需), arrow (always/hover/never), loop, direction (horizontal/vertical), autoplay, interval (自动翻页间隔)。change (发生翻页时)。default, indicators (自定义指示器), arrow (自定义箭头)。
KCheckbox用于多项选择的选项组。value (绑定值), uid (唯一值,用于 KCheckboxGroup), size (sm/md/lg), disabled, indeterminate (中间状态)。updateValuedefault (自定义标签内容)。
KCollapse用于存储内容。title, content, show (展开状态), showClose (是否显示关闭图标), uid (用于手风琴模式)。change (展开状态更改时)。title, content, closeIcon
KColorPicker提供颜色选择的组件。value (颜色值), format (rgb/hsv/hex), allowClear, disabledAlpha (禁用 Alpha), placement, trigger (manual/click/hover), presets (预设颜色)。change (值更改时), changeComplete (选择结束), openChange (打开/关闭)。default (自定义触发元素), title, text, preset
KContextmenu右键菜单组件。KContextmenu: disabledKContextItem: divider (显示为分割线), disabledchange (显示/关闭), contextmenu (右键点击时)。default (传入 KContextmenuKContextSubmenu)。
KCountdown倒计时组件。format (格式化显示), value (目标时间), prefix, suffix, titlechange (时间差变化), finish (倒计时结束)。prefix, title, suffix
KDescriptions以列表形式显示多个字段。title, extra, border, column (每行项目数), direction (horizontal/vertical), sizetitle, extra, default (内容)。
KDivider分隔内容的分割线。direction (horizontal/vertical), borderColor, borderStyle (dotted/dashed/solid等), contentPosition (left/center/right)。default (分隔线上的自定义内容)。
KDrawer打开一个抽屉来显示数据或表单。placement (right/left), value (打开状态), closeOnClickMaskclosedefault (自定义抽屉内容)。
KDropdown用于显示链接和操作列表的可切换菜单。placement, trigger (manual/click/hover), disabled, hideOnClick (点击项目后是否隐藏)。change (显示状态更改), command (点击下拉项目时)。default (触发器内容), dropdown (下拉菜单内容)。
KEllipsis在一定程度上省略文本。content (Tooltip 显示的文本), text (需要缩写的文本), num (省略的字符数), lineClamp (最大行数), placement
KEmpty空状态的占位符提示。image (图片 URL), imageSize, emptyDescription (描述文本)。default (底部内容), image (自定义图片), description
KFlexFlex 布局组件。vertical (垂直方向), wrap, justify, align (遵循 tailwindcss 的值), gap, elm (自定义元素标签)。default (Flex 组件内容)。
KForm用于收集、验证和提交数据。rules (验证规则), initValue (初始值), size, disabled, manualValidate (是否手动验证), labelAlign, labelPositionvalidate (触发表单验证时)。default (传入 KFormItem)。
KInput使用键盘输入数据。size, type (text/password/textarea), value, iconPrefix/iconSuffix, append/prepend (按钮图标), clearable, search (启用搜索回调), rows/autosize (Textarea 属性)。input, enter, search, triggerPrepend/triggerAppendprefix, suffix, append, prepend
KInputNumber输入数值,可定制范围。size, value, max/min, step, precision, disabled, controls (是否启用控制按钮)。input, change (值更改时), blur, focusappend, prepend
KLink文本超链接。type, underline (是否有下划线), disabled, href, icondefault, icon
KMenu用于导航的多功能菜单。mode (vertical/horizontal/inline), inlineCollapsed (内联模式下是否折叠), theme (light/dark), selectable, multiple, triggerSubMenuAction (hover/click)。click, openChange (子菜单展开/关闭), select (选中菜单项), deSelectlabel, icon, expandIcon, item (覆盖所有)。
KMessage (API)显示全局消息。(Options) placement, close, autoClose, duration, onClose, type (info/warning/error/success), offset, title/content (可为 Svelte 组件)。(通过 API 调用)(title/content 可以通过 Svelte 组件插槽渲染)。
KMessageBox (API)模拟系统消息框的模态框。(Options) type (confirm/alert/prompt), emoType, title/content, cancelBtnText/confirmBtnText, onConfirm/onCancel, inputValidator (输入验证)。(通过 API 调用)(可自定义 title 和 content)。
KModal模态对话框。title, footer (显示底部按钮), show (打开状态), layout (footer 按钮布局)。cancel, confirm, close (模态框关闭时)。default (内容), header, footer
KNotification (API)显示全局通知消息。(Options) placement, close, autoClose, duration, onClose, type, offset, title/content(通过 API 调用)(title/content 可以通过 Svelte 组件插槽渲染)。
KPageHeader用于简单页面路径导航。icon (图标类名), title, contentback (点击右侧时触发)。default (主要内容), title, icon, content, extra (附加操作), breadcrumb
KPagination将长列表分为多个页面。total, pagerCount, pageSize, currentPage, layout (控制显示顺序的数组), infinite (无限分页), size, isBg, prevIcon/nextIconcurrentChange (页码变化), sizeChange (每页大小变化)。
KPopconfirm浮动确认卡片。icon, type, cancelBtnText/confirmBtnText, placement, trigger, asyncClose (异步关闭)。confirm, cancel, change (显示状态更改)。default (触发器内容), title, content, footer
KProgress显示当前操作的进度。percentage, status, type (line/circle/dashboard), strokeWidth, textInside, format (自定义文本格式)。default (自定义内容)。
KRadio多选项中的单项选择。label, disabled, value (绑定值), uid (用于 KRadioGroup), sizeupdateValue
KRate用于评分。max, value, allowHalf (允许半星), showScore/showText, icons/colors (图标/颜色), readonly, clearable, sizeupdateValue
KSegmented用于显示多个选项并选择单个选项。value, size, block (适应父级宽度)。change (状态更改时)。default (分段组件内容)。
KSelect从选项中选择值的组件 (基于虚拟列表),。value, dataList, iconPrefix/iconSuffix, placeholder, maxHeight, labelKey/valueKey/key (对象绑定所需), clearable, sizeupdateValue (选择时)。prefix, suffix, default (自定义选项内容)。
KSkeleton内容加载时的占位符。loading (是否显示), size, active (显示动画), round, title/paragraph/avatar (是否显示/自定义属性)。default (内容), skeleton (自定义骨架屏内容)。
KSlider在固定范围内拖动滑块。value, vertical (垂直模式), min/max, step, showStop (显示断点), disabled, sizechange (释放鼠标时), input (实时触发)。buttonRender (自定义滑块按钮内容)。
KSpin加载数据时显示动画。show, text (加载文本), fullScreen (全屏), background (背景色), spinner (UnoCSS 类名)。
KSteps指导用户完成任务步骤的导航栏。active (当前激活步骤), direction (vertical/horizontal), labelPlacement, dot (点状样式), navigation (导航样式), canClick (是否可点击)。change (点击步骤时,如果 canClick 为 true)。default (传入 KStep), icon, title, subTitle, description (KStep 的插槽),。
KSwitch切换开关。value (绑定值), unCheckedValue/checkedValue, unCheckedColor/checkedColor, size, loading, disabledclick, updateValue, changeunCheckedRender, checkedRender (自定义开关内容)。
KTabs分隔数据集合的选项卡。value (uid), navOptions (选项卡配置), type (card/border), editable (可动态添加), closeable (可关闭), beforeLeave (切换前的钩子)。click, remove, add, edit, changedefault (传入 KTabsPane), addIcon
KTag用于分类或标记的标签。type, bgColor/textColor (自定义颜色), icon, border, closable (可移除), closeIconclick, close (移除时)。default (自定义默认内容)。
KTimeline垂直时间线。mode (left/alternate), reverse (反转节点), pending (最后幽灵节点内容或显示状态), itemsdot, pendingDot, children (内容), pending, label
KTooltip简单的文本弹出提示。placement, trigger (manual/click/hover), mouseEnterDelay/mouseLeaveDelay, contenttriggerEl (触发元素)。
KTour用于引导用户的弹出组件。mask (是否启用遮罩), prevBtnText/nextBtnText, placement, open, closeIcon, current (当前步骤), steps (步骤配置)。close, finish, change (步骤更改)。title, closeIcon, description, footer, indicators (指标), prevButton, nextButton,。
KVirtualList用于渲染大量数据的虚拟列表。data (列表源), key (唯一键), keeps (渲染的项目数), estimateSize (预估大小), isHorizontal (水平滚动), start/offsetscroll, top (滚动条到达顶部), bottom (滚动条到达底部)。default (项目内容), footer, header
KWatermark向页面添加文本或图片水印。width/height, rotate (旋转角度), zIndex, image (图片源), content (水印文本,字符串/数组), gap (水印间距), offsetdefault (水印内容)。