# @cldemo/library 组件目录

> 这是 @cldemo/library 的完整组件索引。生成 UI 代码时，先在本文件中查找合适组件，再读取对应详细文档。

## 使用指引

### 组件

- 所有组件使用 `cl-` 前缀，如 `<cl-input>`、`<cl-button>`
- 组件支持三种引入方式，根据项目需要选择

#### 方式一：全局注册

一次性注册所有组件，任何页面可直接使用标签：

```ts
// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import { install as ClLibs } from '@cldemo/library'

const app = createApp(App)
app.use(ClLibs)
app.mount('#app')
```

#### 方式二：页面单独引用

在需要的页面中手动 import 组件：

```vue
<script setup lang="ts">
import { ClButton, ClInput } from '@cldemo/library'
</script>

<template>
  <cl-button>按钮</cl-button>
  <cl-input placeholder="输入框" />
</template>
```

#### 方式三：unplugin-vue-components 自动按需

配置后在模板中直接使用标签，构建时自动按组件级别引入，未使用的组件（及其依赖如 echarts）不会进入项目。

```bash
npm install @cldemo/library unplugin-vue-components
```

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import { clResolver } from '@cldemo/library/resolver'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [clResolver],
      directives: true, // 使用 cl-highlight、cl-waves 等指令时需要开启
    }),
  ],
})
```

### 指令与注入

指令（Directive）和注入（Provide）与组件一样支持按需引入，从 `@cldemo/library` 导入后在 `main.ts` 注册：

```ts
// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import {
  ClHighlight, ClTooltip, ClWaves, // 指令 — namespace 导入
  ClAlert, ClProClipboard, ClLanguagePack, ClProLoadScreen, ClNotify, ClPreview, // 注入 — default 导入
} from '@cldemo/library'

const app = createApp(App)

// 注册指令
app.directive(ClHighlight.name, ClHighlight.directive())
app.directive(ClTooltip.name, ClTooltip.directive())
app.directive(ClWaves.name, ClWaves.directive())

// 注册注入
app.provide('$ClGlobals', {
  alert: ClAlert(),
  clipboard: ClProClipboard(),
  languagePack: ClLanguagePack(),
  loadScreen: ClProLoadScreen(),
  notify: ClNotify(),
  preview: ClPreview(),
})

app.mount('#app')
```

> **提示：** 如果不需要按需引入，直接 `import { install } from '@cldemo/library'` 然后 `app.use(install)` 一键注册全部组件 + 指令 + 注入。

| 类型 | 导出名 | 说明 |
|------|--------|------|
| 指令 | `ClHighlight` | 代码高亮指令，支持多种语言语法高亮，模板中使用 `v-cl-highlight` |
| 指令 | `ClTooltip` | 提示框组件（指令式），支持多种主题、位置和触发方式，模板中使用 `v-cl-tooltip` |
| 指令 | `ClWaves` | 波纹动画指令，点击元素产生波纹扩散效果，模板中使用 `v-cl-waves` |
| 注入 | `ClAlert` | 警告提示组件，支持多种类型（success/warning/error/info）和可关闭，组件中 `inject('$ClGlobals').alert` |
| 注入 | `ClProClipboard` | 剪贴板复制组件，一键复制文本到剪贴板，组件中 `inject('$ClGlobals').clipboard` |
| 注入 | `ClLanguagePack` | 语言包管理，提供国际化语言切换，组件中 `inject('$ClGlobals').languagePack` |
| 注入 | `ClProLoadScreen` | 全屏加载组件，提供全局 loading 遮盖层，组件中 `inject('$ClGlobals').loadScreen` |
| 注入 | `ClNotify` | 通知组件（函数式调用），支持多种位置和类型的通知消息，组件中 `inject('$ClGlobals').notify` |
| 注入 | `ClPreview` | 大图预览组件，支持图片放大查看、旋转、切换，组件中 `inject('$ClGlobals').preview` |


### 工具函数

- 所有工具函数从 `@cldemo/library/common` 引入
- 详见下方[工具函数](#工具函数-common)区域

## 通用组件 (Element)

| 组件 | 标签 | 说明 | 文档 |
|------|------|------|------|
| ClAnchorNav | `<cl-anchor-nav>` | 锚点导航组件，页面内快速定位导航 | [详细文档](./docs/components/Element/AnchorNav.md) |
| ClBadge | `<cl-badge>` | 徽章组件，显示数字标记或状态圆点 | [详细文档](./docs/components/Element/Badge.md) |
| ClButton | `<cl-button>` | 按钮组件，支持多种颜色主题、尺寸、loading 状态、图标和文字组合 | [详细文档](./docs/components/Element/Button.md) |
| ClCheckbox | `<cl-checkbox>` | 复选框组件，支持多选、全选、半选状态 | [详细文档](./docs/components/Element/Checkbox.md) |
| ClClipboard | `<cl-clipboard>` | 剪贴板复制组件，一键复制文本到剪贴板 | [详细文档](./docs/components/Element/Clipboard.md) |
| ClCountup | `<cl-countup>` | 数字动画组件，数字递增/递减动画效果 | [详细文档](./docs/components/Element/Countup.md) |
| ClCropper | `<cl-cropper>` | 图片裁剪组件，支持拖拽裁剪和缩放 | [详细文档](./docs/components/Element/Cropper.md) |
| ClDarg | `<cl-darg>` | 拖拽排序组件，支持列表项拖拽重排 | [详细文档](./docs/components/Element/Darg.md) |
| ClEllipsis | `<cl-ellipsis>` | 文本省略组件，超长文本自动省略并支持 tooltip 查看 | [详细文档](./docs/components/Element/Ellipsis.md) |
| ClForm | `<cl-form>` | 表单组件，支持表单验证和提交 | [详细文档](./docs/components/Element/Form.md) |
| ClFormGroup | `<cl-form-group>` | 表单组组件，管理多个表单项的布局和校验 | [详细文档](./docs/components/Element/FormGroup.md) |
| ClIconFont | `<cl-icon-font>` | 图标组件，用于显示图标字体 | [详细文档](./docs/components/Element/IconFont.md) |
| ClImage | `<cl-image>` | 图片组件，支持懒加载和占位图 | [详细文档](./docs/components/Element/Image.md) |
| ClInput | `<cl-input>` | 输入框组件，支持文本/数字/密码/千分位/清除按钮，支持 prepend/append 插槽 | [详细文档](./docs/components/Element/Input.md) |
| ClInputCaptcha | `<cl-input-captcha>` | 验证码输入框，集成发送验证码倒计时功能 | [详细文档](./docs/components/Element/InputCaptcha.md) |
| ClInputNumber | `<cl-input-number>` | 数字输入框，支持加减按钮、小数位数、千分位格式化 | [详细文档](./docs/components/Element/InputNumber.md) |
| ClInputSearch | `<cl-input-search>` | 搜索输入框，支持搜索图标和清除按钮 | [详细文档](./docs/components/Element/InputSearch.md) |
| ClInputTextarea | `<cl-input-textarea>` | 文本域输入框，支持多行文本输入 | [详细文档](./docs/components/Element/InputTextarea.md) |
| ClLink | `<cl-link>` | 链接组件，支持 href 跳转和点击事件 | [详细文档](./docs/components/Element/Link.md) |
| ClLoad | `<cl-load>` | 加载动画组件，支持多种加载主题和尺寸 | [详细文档](./docs/components/Element/Load.md) |
| ClLoadScreen | `<cl-load-screen>` | 全屏加载组件，提供全局 loading 遮盖层 | [详细文档](./docs/components/Element/LoadScreen.md) |
| ClModal | `<cl-modal>` | 弹窗组件，支持拖拽、自定义头部/底部、提交/取消按钮、全屏模式 | [详细文档](./docs/components/Element/Modal.md) |
| ClProgress | `<cl-progress>` | 进度条组件，支持百分比显示和动画 | [详细文档](./docs/components/Element/Progress.md) |
| ClRadio | `<cl-radio>` | 单选框组件，支持单选切换 | [详细文档](./docs/components/Element/Radio.md) |
| ClSlider | `<cl-slider>` | 滑块组件，支持范围选择和步长设置 | [详细文档](./docs/components/Element/Slider.md) |
| ClSwitchery | `<cl-switchery>` | 开关组件，支持切换状态 | [详细文档](./docs/components/Element/Switchery.md) |
| ClTags | `<cl-tags>` | 标签组件，支持多标签展示和删除 | [详细文档](./docs/components/Element/Tags.md) |
| ClWaterfall | `<cl-waterfall>` | 瀑布流布局组件，支持图片瀑布流排列 | [详细文档](./docs/components/Element/Waterfall.md) |

## Web 组件

| 组件 | 标签 | 说明 | 文档 |
|------|------|------|------|
| ClBreadcrumb | `<cl-breadcrumb>` | 面包屑导航组件，显示当前页面路径 | [详细文档](./docs/components/Web/Breadcrumb.md) |
| ClCalendar | `<cl-calendar>` | 日历组件，支持日期选择、农历显示、日程标记 | [详细文档](./docs/components/Web/Calendar.md) |
| ClCard | `<cl-card>` | 卡片容器组件，提供统一的卡片布局 | [详细文档](./docs/components/Web/Card.md) |
| ClCardLegend | `<cl-card-legend>` | 图例卡片组件，用于代码演示和文档展示 | [详细文档](./docs/components/Web/CardLegend.md) |
| ClCollapse | `<cl-collapse>` | 折叠面板组件，支持手风琴模式和多层嵌套 | [详细文档](./docs/components/Web/Collapse.md) |
| ClColorpicker | `<cl-colorpicker>` | 颜色选择器组件，支持取色和预设颜色 | [详细文档](./docs/components/Web/Colorpicker.md) |
| ClCropperPreview | `<cl-cropper-preview>` | 图片裁剪预览组件，预览裁剪后的图片效果 | [详细文档](./docs/components/Web/CropperPreview.md) |
| ClDatetime | `<cl-datetime>` | 日期时间选择器，支持日期和时间的选择 | [详细文档](./docs/components/Web/Datetime.md) |
| ClDropdownmenu | `<cl-dropdownmenu>` | 下拉菜单组件，支持多级菜单和图标 | [详细文档](./docs/components/Web/Dropdownmenu.md) |
| ClDropdownpopup | `<cl-dropdownpopup>` | 下拉弹出层组件，弹出任意自定义内容 | [详细文档](./docs/components/Web/Dropdownpopup.md) |
| ClEcharts | `<cl-echarts>` | 图表组件，基于 ECharts 封装，支持多种图表类型 | [详细文档](./docs/components/Web/Echarts.md) |
| ClFileupload | `<cl-fileupload>` | 文件上传组件，支持拖拽上传、多文件上传、进度显示 | [详细文档](./docs/components/Web/Fileupload.md) |
| ClInputTag | `<cl-input-tag>` | 标签输入框，支持输入后生成标签 | [详细文档](./docs/components/Web/InputTag.md) |
| ClPaginate | `<cl-paginate>` | 分页组件，支持页码切换和每页条数设置 | [详细文档](./docs/components/Web/Paginate.md) |
| ClPortlet | `<cl-portlet>` | 面板组件，支持折叠/展开、刷新、关闭操作 | [详细文档](./docs/components/Web/Portlet.md) |
| ClPreview | `<cl-preview>` | 大图预览组件，支持图片放大查看、旋转、切换 | [详细文档](./docs/components/Web/Preview.md) |
| ClPreviewexample | `<cl-previewexample>` | 预览示例组件，用于文档展示图片预览效果 | [详细文档](./docs/components/Web/Previewexample.md) |
| ClScrollXFence | `<cl-scroll-xfence>` | 横向滚动栅栏，表格列固定时的横向滚动容器 | [详细文档](./docs/components/Web/ScrollXFence.md) |
| ClSelect | `<cl-select>` | 下拉选择器，支持单选/多选、搜索、远程加载、标签模式 | [详细文档](./docs/components/Web/Select.md) |
| ClSelectCascade | `<cl-select-cascade>` | 级联选择器，支持多级联动选择 | [详细文档](./docs/components/Web/SelectCascade.md) |
| ClSelectmove | `<cl-selectmove>` | 穿梭框选择器，支持左右列表数据穿梭 | [详细文档](./docs/components/Web/Selectmove.md) |
| ClSelectTag | `<cl-select-tag>` | 标签选择器，以标签形式展示选中项 | [详细文档](./docs/components/Web/SelectTag.md) |
| ClSelectTree | `<cl-select-tree>` | 树形选择器，支持树形结构的下拉选择 | [详细文档](./docs/components/Web/SelectTree.md) |
| ClSidemenu | `<cl-sidemenu>` | 侧边菜单组件，支持多级菜单和折叠模式 | [详细文档](./docs/components/Web/Sidemenu.md) |
| ClTable | `<cl-table>` | 数据表格组件，支持排序、筛选、固定列、合计行、行展开、单选/多选 | [详细文档](./docs/components/Web/Table.md) |
| ClTabs | `<cl-tabs>` | 标签页组件，支持选项卡切换 | [详细文档](./docs/components/Web/Tabs.md) |
| ClTree | `<cl-tree>` | 树形组件，支持展开/折叠、勾选、拖拽排序 | [详细文档](./docs/components/Web/Tree.md) |
| ClWeekhour | `<cl-weekhour>` | 周小时选择器，按周和小时维度选择时间段 | [详细文档](./docs/components/Web/Weekhour.md) |
| ClXeditable | `<cl-xeditable>` | 行内编辑组件，点击文本直接编辑 | [详细文档](./docs/components/Web/Xeditable.md) |

## 移动端组件 (Mobile)

| 组件 | 标签 | 说明 | 文档 |
|------|------|------|------|
| ClCell | `<cl-cell>` | Cell 组件 | [详细文档](./docs/components/Mobile/Cell.md) |
| ClPullToRefresh | `<cl-pull-to-refresh>` | PullToRefresh 组件 | [详细文档](./docs/components/Mobile/PullToRefresh.md) |

## 工具函数 (Common)

> 以下工具函数从 `@cldemo/library/common` 引入。AI 生成页面代码时，优先使用这些已封装的工具函数。

| 模块 | 引入 | 说明 | 文档 |
|------|------|------|------|
| CommonBase | `import { CommonBase } from '@cldemo/library/common'` | 基础工具类：类型判断、JSON操作、数组/字符串格式化 | [详细文档](./docs/tools/CommonBase.md) |
| CommonAxios | `import { CommonAxios } from '@cldemo/library/common'` | HTTP 请求封装：自动取消重复请求、超时重试 | [详细文档](./docs/tools/CommonAxios.md) |
| CommonDay | `import { CommonDay } from '@cldemo/library/common'` | 日期时间工具：格式化、时区、农历、时间运算 | [详细文档](./docs/tools/CommonDay.md) |
| CommonPromise | `import { CommonPromise } from '@cldemo/library/common'` | Promise 辅助：并行执行、结果收集 | [详细文档](./docs/tools/CommonPromise.md) |
| CommonEchart | `import { CommonEchart } from '@cldemo/library/common'` | ECharts 图表辅助：线图/柱状图/散点图配置 | [详细文档](./docs/tools/CommonEchart.md) |
| CommonTooltip | `import { CommonTooltip } from '@cldemo/library/common'` | 浮层提示：基于 Popper.js，多种触发方式 | [详细文档](./docs/tools/CommonTooltip.md) |
| CommonElement | `import { CommonElement } from '@cldemo/library/common'` | DOM 工具：位置计算、样式操作、事件绑定 | [详细文档](./docs/tools/CommonElement.md) |
| CommonTools | `import { CommonTools } from '@cldemo/library/common'` | Cookie/LocalStorage/高精度计算/防抖函数 | [详细文档](./docs/tools/CommonTools.md) |
| CommonElementEvent | `import { CommonElementEvent } from '@cldemo/library/common'` | 拖拽/缩放事件封装 | [详细文档](./docs/tools/CommonElementEvent.md) |
| CommonI18n | `import { CommonI18n } from '@cldemo/library/common'` | 国际化语言包管理，中英文切换 | [详细文档](./docs/tools/CommonI18n.md) |
