# Cosey

> 基于 Vue 3 + TypeScript + Element Plus 的中后台组件库与框架。
> 入口：`cosey` / `cosey/components` / `cosey/hooks` / `cosey/utils` / `cosey/store` / `cosey/locale/lang/*`。
> 全量文档：https://docs.cosey.wzt.zone/llms-full.txt

## 先读这几条

- 组件全局已注册，模板里直接写 `<co-xxx>`，不需要 import；TSX 里从 `cosey/components` 取。
- 中后台页面用 `co-card` / `co-container` 搭骨架，不要在视图里手写 div 拼卡片。
- 页签要放进卡片头部时用 `co-card-tabs` + `co-card-tab-panel`，不要用 `el-tabs`：它的导航和面板是同一个节点的两个子元素，塞不进卡片的头部和主体。
- 表格用 `useTable` + `<co-table>`。列的展示写 `renderer`（`text` / `date` / `datetime` / `tag` / `boolean` / `longtext` / `switch` / `click` / `media` / `usd` / `cny` / `cent`），别用 `format` 或插槽硬拼；`renderer` 与 `format` 同时写时 `format` 会完全接管，列的样式也会丢。
- 操作列用 `actionColumn: { actions: (row) => [...] }`，不要再开 `#action` 插槽手写 `<co-table-action>`。
- 日期范围要拆成两个接口参数时，给字段加 `split: ['startCreatedAt', 'endCreatedAt']`，此时不要再写 `prop`（拆分后的第一个键就是校验锚点）。
- 图标必须带前缀：`<co-icon name="co:xxx" />` 或 `bi bi-xxx`，漏了前缀会渲染成空图标。
- 写样式用 token：`css-var(color-primary)`、`css-var(padding)`，不要写死颜色和间距。

## 组件

- [组件总览](https://docs.cosey.wzt.zone/components/overview)
- [Async 异步状态](https://docs.cosey.wzt.zone/components/async): 把「加载中 / 空数据 / 出错 / 有数据」四种状态收在一处，省掉每个页面重复的 `v-loading`、`v-if="empty"` 和 `catch` 重试。默认带骨架屏、空状态和错误重试。
- [AudioCard 音频卡片](https://docs.cosey.wzt.zone/components/audio-card): 音频卡片容器，点击可以弹窗预览。
- [Card 卡片](https://docs.cosey.wzt.zone/components/card): 内容区块容器：标题、副标题、操作区、页脚与折叠能力，可选边框、阴影与浮起效果。
- [CardTabs 卡片页签](https://docs.cosey.wzt.zone/components/card-tabs): `CardTabs` 是「页签条放在卡片头部」的组合组件：内部就是一张 `co-card`，头部渲染导航、内容区渲染面板，省掉「卡片标题 + 内容区里再套一层 `el-tabs`」的两层留白。
- [Chart 图表](https://docs.cosey.wzt.zone/components/chart): `useEcharts` 的组件化封装：自动初始化、跟随容器尺寸、主题与暗色模式联动，另外补上加载态、空状态和导出图片。
- [CheckUpdates 版本更新检测](https://docs.cosey.wzt.zone/components/check-updates): 自动检测应用版本更新，当有新版本时弹出通知提醒用户刷新页面。每 60 秒轮询一次，页面隐藏时暂停检测。
- [Close 关闭按钮](https://docs.cosey.wzt.zone/components/close): 弹出框公用的关闭按钮。
- [ConfigProvider 全局配置](https://docs.cosey.wzt.zone/components/config-provider): 根全局配置是 Cosey 中必需的全局单例组件，用于进行全局配置。
- [Container 容器](https://docs.cosey.wzt.zone/components/container): 带内边距的页面容器：可挂标题区、返回按钮与底部操作区，高度可设为一屏或撑满父容器，并把「内容区可用高度」提供给子组件。
- [ContextMenu 上下文菜单](https://docs.cosey.wzt.zone/components/context-menu): 在指定区域右键（或左键点击）弹出的操作菜单，支持图标、禁用项、分隔线、多级子菜单、当前项高亮与整行自定义内容；也可以按坐标或某个锚点元素打开。
- [Copy 复制](https://docs.cosey.wzt.zone/components/copy): 点击复制文本的图标按钮，复制成功后图标变成绿色对勾（两个状态尺寸一致，不会引起布局跳动）。
- [Descriptions 描述列表](https://docs.cosey.wzt.zone/components/descriptions): 成组展示多个字段，常用于详情页、订单卡片等只需要「看」不需要「改」的场景：按列数自动排布、支持跨列、边框与纵向两种排布方式。
- [Dict 字典](https://docs.cosey.wzt.zone/components/dict): 用一份声明统一「表单选项、表格标签、详情文案」，避免状态文案和颜色散落在各处。字典可以同步注册，也可以异步拉取，全局共享且只加载一次。
- [DndSort 拖拽排序](https://docs.cosey.wzt.zone/components/dnd-sort): 允许用户通过鼠标拖拽改变数组元素位置。
- [Editor 编辑器](https://docs.cosey.wzt.zone/components/editor): 富文本编辑器，预设了常用样式与块级菜单，开箱即用。
- [FileCard 文件卡片](https://docs.cosey.wzt.zone/components/file-card): 文件容器。
- [Form 表单](https://docs.cosey.wzt.zone/components/form): 在原来的 `ElForm` 的基础上增加了一些语法糖和更多的布局设置，帮助我们快速地开发一个表单，同时添加了一些默认行为，让我们的表单默认好用。
- [FormDialog 对话框表单](https://docs.cosey.wzt.zone/components/form-dialog): `FormDialog` 是 `ElDialog` 组件的高阶组件，拥有相同的接口，用于配合 `Form` 组件使用，`Form` 表单的按钮会移到 `FormDialog` 的底部插槽位置。
- [FormDrawer 抽屉表单](https://docs.cosey.wzt.zone/components/form-drawer): `FormDrawer` 是 `ElDrawer` 组件的高阶组件，拥有相同的接口，用于配合 `Form` 组件使用，`Form` 表单的按钮会移到 `FormDrawer` 的底部插槽位置。
- [FormGroup 折叠表单组](https://docs.cosey.wzt.zone/components/form-group): `FormGroup` 是 `ElSpace` 的高阶组件，用于把表单字段分组 —— 可选带标题、边框和折叠。 有 `title` 时会渲染边框，`collapsible` 打开后点标题即可收起 / 展开。
- [FormList 表单列表](https://docs.cosey.wzt.zone/components/form-list): `FormList` 继承于 `FormItem` 组件，自带了新增、删除等操作按钮，用于处理数组结构的表单数据。
- [FormQuery 查询表单](https://docs.cosey.wzt.zone/components/form-query): `FormQuery` 是预设了栅格布局的 `Form` 组件，拥有相同的接口，并添加了折叠功能，通常和表格组件一起使用。
- [FormSteps 分步表单](https://docs.cosey.wzt.zone/components/form-steps): `FormSteps` 是 `ElSteps` 组件的高阶组件，拥有相同的接口，用于把过长的表单拆成几步填写。 步骤容器用 `FormStep`（对应 `ElStep`），`FormItem` 直接写在步骤里即可。
- [FormTabs 表单页签](https://docs.cosey.wzt.zone/components/form-tabs): `FormTabs` 是 `ElTabs` 组件的高阶组件，拥有相同的接口，用于配合 `Form` 组件把过长的表单按页签分组。 页签容器用 `FormTabPanel`（对应 `ElTabPane`），`FormItem` 直接写在页签里即可。
- [Grid 栅格](https://docs.cosey.wzt.zone/components/grid): 24 栅格系统，使用方式和接口同 [element-plus Layout](https://element-plus.org/zh-CN/component/layout.html)，但响应式断点是相对于容器宽度，而非视口大小。
- [Highlight 代码高亮](https://docs.cosey.wzt.zone/components/highlight): 把 [Prism](https://prismjs.com/) 封装成组件，内置复制按钮。支持 20 多种语言的语法着色、超长代码内部滚动，也可以把代码放进默认插槽。代码区字号固定 13px，不随外层字号变化。
- [HorizontalTree 水平树](https://docs.cosey.wzt.zone/components/horizontal-tree): 用于渲染一颗展开的，最后一级水平排列的树，可以勾选节点。
- [Icon 图标](https://docs.cosey.wzt.zone/components/icon): Cosey 中所有展示图标的地方都会使用 Icon 组件，包括标签栏、菜单栏和页面其他地方。
- [ImageCard 图片卡片](https://docs.cosey.wzt.zone/components/image-card): `ElImage` 的高阶组件，拥有相同的接口，定义了样式。
- [InputNumberRange 数字范围输入框](https://docs.cosey.wzt.zone/components/input-number-range): 两个数字输入框拼成的范围输入，值是 `[开始, 结束]` 数组。两端都填上才会产生值，清空任意一端回到 `undefined`；填反了（开始大于结束）会在离开组件时自动交换成「小 - 大」。在表单里用 `field-type="numberrange"`。
- [Mask 遮罩](https://docs.cosey.wzt.zone/components/mask): 弹出框公用的遮罩。
- [MediaCard 媒体卡片](https://docs.cosey.wzt.zone/components/media-card): 媒体容器，通过点击进行弹窗查看，支持的媒体有图片、视频、音频。
- [MediaCardGroup 媒体卡片组](https://docs.cosey.wzt.zone/components/media-card-group): 简介
- [MediaViewer 媒体查看器](https://docs.cosey.wzt.zone/components/media-viewer): 简介
- [NumberFormat 数字格式化](https://docs.cosey.wzt.zone/components/number-format): 将数字格式化为指定格式，例如千分位或货币。
- [OnlyChild 唯一子组件](https://docs.cosey.wzt.zone/components/only-child): 简介
- [RemoteSelect 远程选择器](https://docs.cosey.wzt.zone/components/remote-select): `ElSelect` 的远程版本，通过传递的接口和配置获取数据，并且组合了分页组件和查询表单组件，其功能相当于一个小型表格组件。
- [Ribbon 丝带角标](https://docs.cosey.wzt.zone/components/ribbon): 在容器的角落展示一些关键的状态、标签或提示信息，例如推荐、促销、新品等。
- [ScrollView 滚动视图](https://docs.cosey.wzt.zone/components/scroll-view): 自定义盒子的滚动条，使其绝对定位而不占用盒子内容宽度，且鼠标移上才显示，并且在滚动到非顶部或底部时显示遮罩。
- [SnugMenu 舒适菜单](https://docs.cosey.wzt.zone/components/snug-menu): 一种宽松风格的菜单，支持水平和垂直。
- [StackDialog 层叠对话框](https://docs.cosey.wzt.zone/components/stack-dialog): 是 `ElDialog` 的高阶组件，显示多个层叠对话框时，会显示堆叠效果。层叠对话框的高度随屏幕高度变化而变化，适合用来放置撑满屏幕高度的表格组件。
- [Table 表格](https://docs.cosey.wzt.zone/components/table): 在ElTable基础上，新增分页、查询表单、工具栏等功能，预设了默认的使用方式，简化样板代码。
- [TableSelect 表格选择器](https://docs.cosey.wzt.zone/components/table-select): 点击后打开弹窗，在表格里选择数据，确认后回填到输入框。
- [Transition 过渡](https://docs.cosey.wzt.zone/components/transition): 简介
- [TransitionGroup 过渡组](https://docs.cosey.wzt.zone/components/transition-group): `TransitionGroup` 是对 `vue transition-group` 的简单封装，预设了一些动画效果。
- [Typography 排版](https://docs.cosey.wzt.zone/components/typography): 一组文本排版组件：`co-typography-title` 标题、`co-typography-text` 行内文本、`co-typography-paragraph` 段落，以及不限定标签的 `co-typography`。支持语义色、禁用、加粗/斜体/下划线/删除线/标记底色/行内代码、一键复制，以及按行数省略——真的超出时才加省略号，`expandable` 还能就地展开看全文。
- [Upload 上传](https://docs.cosey.wzt.zone/components/upload): 通过点击上传文件，封装了上传逻辑、双向绑定和表单验证，使其像 ElInput 一样易用。
- [VideoCard 视频卡片](https://docs.cosey.wzt.zone/components/video-card): 视频卡片容器，点击可以弹窗预览。
- [WeekRangePicker 周范围选择器](https://docs.cosey.wzt.zone/components/week-range-picker): 按周选择连续区间。周固定为 **ISO 周（周一 00:00:00 ~ 周日 23:59:59.999）**，不随界面语言变化，`v-model` 即这两端的时间戳。

## 指南

- [关于 Cosey Admin](https://docs.cosey.wzt.zone/guide/intro)
- [0.x.x 升级到 1.x.x](https://docs.cosey.wzt.zone/guide/upgrade-to-1)
- [主题](https://docs.cosey.wzt.zone/guide/theme)
- [国际化](https://docs.cosey.wzt.zone/guide/i18n)
- [布局](https://docs.cosey.wzt.zone/guide/layout)
- [快速开始](https://docs.cosey.wzt.zone/guide/quick-start)
- [接口请求](https://docs.cosey.wzt.zone/guide/request)
- [插槽](https://docs.cosey.wzt.zone/guide/slots)
- [文件上传](https://docs.cosey.wzt.zone/guide/upload)
- [构建部署](https://docs.cosey.wzt.zone/guide/build)
- [样式](https://docs.cosey.wzt.zone/guide/style)
- [认证与授权](https://docs.cosey.wzt.zone/guide/auth)
- [路由与菜单](https://docs.cosey.wzt.zone/guide/route)