安装与使用

安装组件库

# npm
npm i @yoka-ui/ui

# 或 pnpm
pnpm add @yoka-ui/ui

（推荐）配置 Cursor / IDE 规则

在项目的 Cursor rules 中创建文件 yoka-ui.mdc，用于约束导入方式与文档入口（导出清单、LLM 索引等）：

---
description: 使用 @yoka-ui/ui 时的导入与文档约定
globs: "**/*.{ts,tsx}"
alwaysApply: false
---

# @yoka-ui/ui

- **导入**：仅从 `@yoka-ui/ui` 做**具名** `import`，勿使用未在导出表中出现的符号。
- **导出清单（权威）**：以安装包内 `node_modules/@yoka-ui/ui/@Docs-yoka/exports.generated.md` 为准，与发布产物类型一致；该文件由 yoka-ui 在导出变更后重新生成。
- **LLM / 助手入口**：同目录 `node_modules/@yoka-ui/ui/@Docs-yoka/llms.txt`（索引、外链与使用规则摘要）。
- **API**：不确定 props 时查组件库 Storybook / 源码示例或 README，勿臆造 API；原生 antd 行为对照 [Ant Design 文档](https://ant.design)。
- **全局样式**：业务入口按需引入，常见为 `import '@yoka-ui/ui/dist/index.less'`（以 `@yoka-ui/ui` 的 README 与当前产物路径为准）。

基础用法

import { YkButton, YkCard } from "@yoka-ui/ui";
import "@yoka-ui/ui/dist/index.less"; // 引入样式

function App() {
  return (
    <YkCard title="示例">
      <YkButton type="primary">点击我</YkButton>
    </YkCard>
  );
}

导入约定（重要）

// 仅从包入口做“具名导入”
import { YkPorjectSelect } from "@yoka-ui/ui";

// 具体有哪些符号可用，以 @Docs-yoka/exports.generated.md 为准
// node_modules/@yoka-ui/ui/@Docs-yoka/exports.generated.md

组件列表

UI 基础组件 (src/ui/)

| 组件 | 说明 | | ----------------- | ------------------------------------------- | | YkButton | 按钮组件 | | YkCard | 卡片组件 | | YkCheckbox | 复选框 | | YkDescriptions | 描述列表 | | YkPagination | 分页器 | | YkRadio | 单选框 | | YkRadioBtnSpecial | 异形单选按钮组 | | YkSegmented | 分段控制器 | | YkSelect | 选择器 | | YkSpin | 加载中 | | YkStatistic | 统计数值 | | YkSwitch | 开关 | | YkTabs | 标签页（items 支持 icon，图标在标题左侧） | | YkTooltip | 文字提示 | | LabelSelect | 标签选择器 | | LogicOperator | 逻辑运算符 |

主题组件 (src/Themes/)

为 Ant Design 输入/表格等提供统一主题包装的 ConfigProvider 封装。

| 组件 | 说明 | | ---------- | ---------------------------------- | | InputTheme | 输入类组件主题（禁用背景、圆角等） | | TableTheme | 表格主题样式封装 |

布局组件 (src/layout/)

| 组件 | 说明 | | ----------- | --------------------------------------------------------------------------------- | | FlexGrid | 响应式栅格（antd Row/Col + Flex）：大屏每行 4 格，变窄为 3/2/1 | | YkContainer | 页面容器（sticky 页头 + 内容区留白） | | YkDrawer | 抽屉：四向 placement；默认点遮罩不关闭（maskClosable: false）；上下内置关闭偏右 |

创意组件 (src/creative/)

| 组件 | 说明 | | ------------------- | ------------------------------------ | | ButtonRadioWithInfo | 带说明信息的按钮式单选组合 | | ButtonWithProgress | 带进度条动画的按钮，支持进度与副标题 |

功能组件 (src/components/)

| 组件 | 说明 | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Clock | 倒计时时钟 | | DebounceInput | 防抖输入框 | | MultipleSelect | 多选组件 | | NumericInput | 数字输入框 | | RefreshButton | 刷新按钮 | | SearchWithHistory | 带历史的搜索 | | TextWithInput | 可编辑文本 | | TextWithToolTip | 带提示的文本 | | TreeTransfer | 树形穿梭框 | | YkDateRangePicker | 带「紧凑预设 tag」与「完整 RangePicker」双模式切换的日期范围选择器；8 个内置快捷预设；受控组件；仅允许过去 7 天 | | YkRangeDateWithVS | 主时间区间 + 可选「日期对比」（日/周/月 Tab、里程碑、节假日、rangeDisplayLabel 等）；内置 ConfigProvider 中文 locale 与 dayjs zh-cn（周一起算） | | YkRangeTimeWithRecent | 时间范围 + 「最近 N 天/周/月」动态语义（Popover + RangePicker）；内置中文 locale 与 dayjs zh-cn；触发区依赖全局 iconfont（如 icon-date） |

业务组件 (src/business/)

| 组件 | 说明 | | --------------- | -------------------------------------------------------------------- | | DrawerPageInfo | 抽屉页面信息 | | Editor | 富文本编辑器 | | Empty | 空状态 | | ModCommonFilter | 通用筛选器 | | YkLoginModule | 登录组件（当前支持：扫码 / 短信验证码；Tabs 由 tabs 配置） | | YkPorjectSelect | 项目选择器（搜索、关注、在营/关服 Tab、最近访问等） | | YkSqlEdit | SQL 编辑器（CodeMirror 6：动态参数 {{...}} 高亮、关键词/函数补全） |

导出说明：业务项目里 import { ... } from '@yoka-ui/ui' 可用的符号以 [src/index.tsx](src/index.tsx) 为准。若某组件已在源码目录中实现但尚未在入口文件中 export，需先在组件库补齐导出并发布后，再在业务侧引用。

LLM / 助手文档（@Docs-yoka）

• 入口索引：@Docs-yoka/llms.txt（导航 + 使用约定，结构对齐仓库内 Ant Design @Docs/llms.txt 思路）。
• 具名导出表：@Docs-yoka/exports.generated.md 由脚本根据 src/index.tsx 自动生成；修改导出后请执行

  pnpm run generate:yoka-llms

  （发版时 prepack 会执行一次以保证包内为最新）。
• 安装 npm 包后路径示例：node_modules/@yoka-ui/ui/@Docs-yoka/llms.txt（需 package.json 的 files 包含 @Docs-yoka）。