# ltd-components

**Repository Path**: ltd_1/ltd-components

## Basic Information

- **Project Name**: ltd-components
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Xy UI Kit

基于 Vue3 + Element Plus + SCSS 的 SaaS 平台前端组件开发库，采用**源码级「复制即用」分发**：每个组件是一个自包含文件夹，复制进宿主项目即可直接使用，无 npm 发包、无 lib 打包产物。

## 核心特性

- **组件四件套**：每个组件文件夹内含 `index.js`（带 install）+ `XyX.vue` + `xy-x.scss` + `README.md`，文件夹即完整交付单元，复制即用
- **`xy-` 三级前缀防冲突**：CSS 类名 `.xy-*`（BEM）、SCSS 变量 `$xy-*`、CSS 自定义属性 `--xy-*`，复制进宿主项目不与既有样式冲突
- **主题跟随 Element Plus**：组件样式只引用 `--el-*` CSS 变量，宿主项目换主题零成本，天然兼容 EP 暗色模式
- **构建器无关**：组件代码不使用任何 Vite 特有语法（`import.meta.glob` 等），webpack / vue-cli 项目同样可用

## 组件路线图（Element Plus 生态补位）

专注封装 Element Plus 没有的高价值组件。四批共 12 个，**已全部落地**：

| 组件 | 场景 | 实现路线 | 状态 |
|---|---|---|---|
| XyKanban 看板 | 列间卡片拖拽流转 | HTML5 拖拽自研（零依赖） | 已落地 |
| XyCountTo 数字动画 | 指标卡数值滚动 | 纯自研（零依赖） | 已落地 |
| XyWatermark 水印 | 防泄密页面水印 | Canvas 纯自研（零依赖） | 已落地 |
| XyCharts 图表 | 折线 / 柱状 / 饼图，配置驱动 | ECharts 封装（peer 依赖 `echarts >= 5.4`） | 已落地 |
| XyGantt 甘特图 | 任务排期、依赖关系、拖拽调期 | SVG 自研（零依赖） | 已落地 |
| XyMindMap 思维导图 | 节点树、展开折叠、导出图片 | SVG 自研（零依赖） | 已落地 |
| XyOrgChart 组织架构图 | 层级树 + 人员卡片 | 自研（零依赖） | 已落地 |
| XyFlow 流程设计器 | 审批流可视化编排 | SVG 自研（零依赖） | 已落地 |
| XyEditor 富文本 | 所见即所得编辑 | wangEditor 封装（peer 依赖 `@wangeditor/editor`） | 已落地 |
| XyCron 表达式 | 定时任务可视化配置 | 纯自研（零依赖） | 已落地 |
| XyPersonSelect 选人 | 组织树选人回显 | el-tree 封装（零依赖） | 已落地 |
| XySplit 分栏 | 拖拽调整宽高分栏 | 纯自研（零依赖） | 已落地 |

> 落地一个注册一个：示例站菜单 + 文档站侧边栏 + 本表状态同步更新。
> 引擎类依赖政策见 [ADR-003](docs/decisions/ADR-003-peer-dependencies.md)：允许 peer 依赖，README 首行注明；零依赖优先。

## 下一批候选组件（规划中 · 四批共 13 个）

路线图完结后，按「EP 空缺 + SaaS 高频 + 零依赖优先」继续扩编，分四批推进：

| 批次 | 组件 | 实现路线 | 状态 |
|---|---|---|---|
| 第五批·零依赖高频 | XyVirtualList 虚拟滚动、XySignature 电子签名、XyScrollBoard 滚动看板 | 纯自研（零依赖） | 已落地 |
| 第六批·零依赖 + 1 | XyColorPickerPlus 颜色增强、XyCalendarRange 区间日历、XyStepsPlus 步骤增强、XyQrCode 二维码（peer `qrcode`） | 自研 / `qrcode` peer | 规划中 |
| 第七批·零依赖补位 | XyDescriptionPlus 描述列表增强、XyPrint 打印导出 | 纯自研（零依赖） | 规划中 |
| 第八批·peer 引擎 | XyExcelGrid（luckysheet/handsontable）、XyPdf（pdf.js）、XyVideo（video.js）、XyMap（高德/leaflet） | 引擎封装 peer 依赖 | 规划中 |

> XyQrCode 因 QR 编码算法（Reed-Solomon / 掩码）复杂，按 ADR-003 定为 peer 依赖纯 JS 小包 `qrcode`，组件只写封装层，引擎由宿主安装。
> XyMap 涉及地图底图，上线前须过中国地图合规校验（geo-map-compliance-guard）。

## 快速开始（复制三步法）

前置条件：宿主项目已安装 `vue@3` + `element-plus` + `sass`。

1. **复制**：把 `src/components/<XyComponent>/`（任意组件）整个文件夹复制到你项目的 `src/components/` 下
2. **引入**：`import XyComponent from '@/components/<XyComponent>'`——样式已随 `index.js` 副作用导入自动引入
3. **使用**：`app.use(XyComponent)` 全局注册，或局部注册后模板使用 `<xy-component>`

## 本仓库结构

```
src/components/   # 可复制组件库（核心资产，每个组件四件套）
src/demo/         # SaaS 风格示例站（含组件源文件下载能力）
src/styles/       # 全局设计 Token（$xy-* → --el-* 主题桥接）
docs/             # VitePress 文档站（include 组件 README 单一事实来源）
SPEC.md           # 架构契约（目录/命名/范式/验收）
```

## 脚本

| 命令 | 说明 |
|---|---|
| `npm run dev` | 启动组件示例站（端口 5188），可在线预览并下载组件源文件 |
| `npm run build` / `preview` | 构建 / 预览示例站产物 |
| `npm run docs:dev` / `docs:build` | 启动 / 构建 VitePress 文档站 |
| `npm run lint` / `format` | ESLint 检查 / Prettier 格式化 |

## 约定（对组件开发者的硬规则）

1. 组件 `.vue` 内禁止 import `@/styles/**`、`@/demo/**`
2. 组件 `.scss` 只允许使用 `var(--el-*)`、局部 `$xy-*` 变量与 `#fff`/`#000`，不得 `@use` 任何仓库内全局文件
3. `import.meta.glob` 等 Vite 特有语法只允许出现在 `src/demo/**` 与 `docs/**`
4. 图标唯一来源 `@element-plus/icons-vue`，组件内局部 import，禁用 emoji 图标

完整规则见 [SPEC.md](SPEC.md) 第 7 章。

## 许可证

本项目基于 MIT 许可证开源。