137 lines
6.3 KiB
Markdown
137 lines
6.3 KiB
Markdown
---
|
||
name: tree-component
|
||
overview: "依据 fms-vue 开发规范和 antdv-next 参考库，从零手写一个 Tree 组件，覆盖：树形展示与展开折叠、单选/多选、checkable 复选（含半选与父子联动）、异步懒加载，以及拖拽排序与搜索过滤两个进阶特性；节点支持 title 字段 + #title 插槽自定义。"
|
||
todos:
|
||
- id: explore-refs
|
||
content: 用 [skill:antdv-next] 与 code-explorer 对齐 Tree API 与相邻组件写法
|
||
status: completed
|
||
- id: add-tokens
|
||
content: 在 tokens.css 补充 tree 专属尺寸 token
|
||
status: completed
|
||
dependencies:
|
||
- explore-refs
|
||
- id: write-utils
|
||
content: 实现 tree/utils.js 纯函数（checked/halfChecked/展开路径/过滤/拖拽落点）
|
||
status: completed
|
||
dependencies:
|
||
- explore-refs
|
||
- id: write-tree
|
||
content: 实现 tree.vue 容器与递归节点（展开/选中/勾选/异步/拖拽/过滤/插槽/键盘）
|
||
status: completed
|
||
dependencies:
|
||
- write-utils
|
||
- add-tokens
|
||
- id: write-style
|
||
content: 编写 tree/index.scss 样式（缩进/hover/focus/disabled/半选/拖拽线/高亮/reduced-motion）
|
||
status: completed
|
||
dependencies:
|
||
- write-tree
|
||
- id: write-demo
|
||
content: 新增 tree/demo/tree-demo.vue 验证各模式用法
|
||
status: completed
|
||
dependencies:
|
||
- write-tree
|
||
- id: static-check
|
||
content: 运行 oxlint 静态检查并说明未构建未测试
|
||
status: completed
|
||
dependencies:
|
||
- write-style
|
||
- write-demo
|
||
---
|
||
|
||
## 用户需求
|
||
|
||
用户已实现 Grid（Row + Col 基础栅格，不含 xs~xxxl 响应式），但反馈"完全不行"，要求分析根因并修复。
|
||
|
||
## 产品概述
|
||
|
||
基于 24 栅格系统的布局组件（Row 容器 + Col 列），用于快速搭建页面结构。当前已实现但存在视觉错乱与范式问题，需修复使其达到与项目其他组件一致的可用状态。
|
||
|
||
## 核心特性（修复后应保持）
|
||
|
||
- Row：flex 行容器，支持 gutter（数字 / [水平, 垂直]）、align、justify、wrap。
|
||
- Col：列单元，支持 span、offset、order、push、pull、flex。
|
||
- 24 栅格百分比宽度 + gutter 负 margin 经典实现，纯 CSS、无 JS 断点监听。
|
||
|
||
## 技术栈
|
||
|
||
- Vue 3 `<script setup>` + scoped/全局 SCSS（与本项目一致）
|
||
- 纯 CSS 栅格，复用 `--fms-*` token，新增 `--fms-grid-gutter`
|
||
|
||
## 实现方案
|
||
|
||
### 策略
|
||
|
||
对照可正常工作的 `date` 组件（同为 `<script> import scss` 全局写法）与 `splitter`/`spin`（`<style scoped> @use` 写法），定位 Grid 的真实缺陷并修复。核心修正三类问题：Demo 容器嵌套 flex 导致栅格错乱、样式作用域双注入、SCSS 过时 API。
|
||
|
||
### 关键技术决策
|
||
|
||
1. **修正 Demo 嵌套 flex 主因**：`.demo-panel`（`demo.css`）是 `display:flex; flex-wrap:wrap`，Grid 的 `<Row>` 作为其子项默认 `flex:0 1 auto` 被压缩/拉伸，内部 Col 依赖 Row 的 flex 上下文因而错位。修复：在 `index.scss` 给 `.fms-row` 加 `width:100%`，并在 demo 里用块级 wrapper 包住 Row，隔离外层 flex。
|
||
2. **样式全局单例引入**：移除 row.vue/col.vue 各自 `import './index.scss'`（双注入、全局污染），改为在 `src/styles/index.css` 顶部 `@import '../components/ui/grid/index.scss';` 一次性全局引入（栅格为跨组件结构性样式，应全局单例，与 antd 一致）。
|
||
3. **消除 SCSS deprecation**：`@use 'sass:math'` + `math.percentage(math.div($n, $cols))` 替换 `percentage($n / $cols)`。
|
||
4. **健壮性**：`.fms-col` 加 `min-width:0` 防内容撑破（参照 splitter panel）。
|
||
5. **简化 push/pull 演示**：避免与 offset 混用语义冲突，移除易错乱的混用段。
|
||
|
||
### 性能与可靠性
|
||
|
||
- 静态 class + CSS 变量，无高频事件、无布局读取、无残留监听。
|
||
- 全局单例引入避免重复注入，构建产物更小、无 scoped 跨组件失效风险。
|
||
|
||
## 实现备注
|
||
|
||
- 复用现有 `.fms-<name>` 命名与 `@use`/`@import` 约定（参考 splitter/index.scss、date 写法）。
|
||
- 不创建 barrel index（规范 3）。
|
||
- 演示注册方式沿用现有 App.vue 的 demoMap（已完成，无需改）。
|
||
- 修复后跑一次 `vite build`（诊断性）确认无编译错误 / deprecation 阻断，并 oxlint。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
fms-vue/src/components/ui/grid/
|
||
row.vue # [MODIFY] 移除 `<script>` 中 `import './index.scss'`（改全局单例引入）。
|
||
col.vue # [MODIFY] 移除 `<script>` 中 `import './index.scss'`。
|
||
index.scss # [MODIFY] ①`@use 'sass:math'` 改写除法/percentage 消 deprecation；②`.fms-col` 加 `min-width:0`；③`.fms-row` 加 `width:100%`。
|
||
fms-vue/src/styles/index.css # [MODIFY] 顶部新增 `@import '../components/ui/grid/index.scss';` 全局单例引入栅格样式。
|
||
fms-vue/src/components/ui/demo/grid.vue # [MODIFY] ① 每个 Row 外包块级 wrapper 隔离 `.demo-panel` flex；② 简化 push/pull 演示段。
|
||
```
|
||
|
||
## 关键代码结构
|
||
|
||
```
|
||
// grid/index.scss 关键修正
|
||
@use 'sass:math';
|
||
|
||
.fms-row {
|
||
display: flex;
|
||
flex-flow: row wrap;
|
||
width: 100%; // 防止被外层 flex 容器压缩
|
||
// ...gutter 变量与负 margin 保持不变
|
||
}
|
||
|
||
.fms-col {
|
||
min-width: 0; // 防止内容撑破 flex 列
|
||
padding-left: calc(var(--fms-grid-gutter-h) / 2);
|
||
padding-right: calc(var(--fms-grid-gutter-h) / 2);
|
||
box-sizing: border-box;
|
||
}
|
||
|
||
// 24 栅格宽度（消 deprecation）
|
||
@for $n from 0 through 24 {
|
||
.fms-col-#{$n} {
|
||
@if $n == 0 { display: none; } @else { display: block; }
|
||
flex: 0 0 math.percentage(math.div($n, 24));
|
||
max-width: math.percentage(math.div($n, 24));
|
||
}
|
||
}
|
||
```
|
||
|
||
## Agent Extensions
|
||
|
||
### Skill
|
||
|
||
- **antdv-next**
|
||
- Purpose: 对照 antdv-next Grid 的官方实现（row.tsx/col.tsx/index.tsx）确认 gutter 负 margin、push/pull relative 实现、24 栅格 API 语义，确保 Vue 化移植的修复忠于原库交互。
|
||
- Expected outcome: 确认 Row/Col 的 props 集合、gutter 实现细节与 flex 解析规则，指导 Grid 修复方案不偏离原库设计。
|
||
- **agent-browser**
|
||
- Purpose: 在修复前后打开 http://localhost:5082 的 Grid 演示页截图，直观验证"完全不行"的具体现象（竖排/错位/出血）及修复后渲染是否正确。
|
||
- Expected outcome: 取得 Grid 演示区真实渲染截图，作为修复验证的客观证据（构建后可用）。 |