20260816220132
This commit is contained in:
oneao committed
1 parent
b6f9a4c912
commit
72993ecdcd
179 files changed
+20050
-633
No files matched your search
@@ -0,0 +1,146 @@
|
||||
---
|
||||
name: grid-component
|
||||
overview: 在 fms-vue 的 src/components/ui/grid 下新建基础 Grid 组件（Row + Col），仅支持 gutter/align/justify/wrap 与 span/offset/order/push/pull/flex，不含 xs~xxxl 响应式断点。纯 CSS + scoped SCSS，参考 antdv-next 设计并遵守开发规范。
|
||||
todos:
|
||||
- id: grid-tokens
|
||||
content: tokens.css :root 新增 --fms-grid-gutter 默认值
|
||||
status: completed
|
||||
- id: grid-style
|
||||
content: 创建 grid/index.scss：24 栅格类、offset/order/push/pull/flex 类与 gutter 变量
|
||||
status: completed
|
||||
dependencies:
|
||||
- grid-tokens
|
||||
- id: grid-row
|
||||
content: 创建 row.vue：flex 容器、gutter 负 margin/row-gap、align/justify/wrap 与 CSS 变量下传
|
||||
status: completed
|
||||
dependencies:
|
||||
- grid-style
|
||||
- id: grid-col
|
||||
content: 创建 col.vue：span/offset/order/push/pull/flex（数字 class + flex computed style）
|
||||
status: completed
|
||||
dependencies:
|
||||
- grid-style
|
||||
- id: grid-demo
|
||||
content: 创建 demo/grid.vue 并注册到 App.vue「布局」分类与 demoMap
|
||||
status: completed
|
||||
dependencies:
|
||||
- grid-row
|
||||
- grid-col
|
||||
- id: grid-verify
|
||||
content: oxlint 静态检查 grid 相关文件并汇报（不主动构建）
|
||||
status: completed
|
||||
dependencies:
|
||||
- grid-demo
|
||||
---
|
||||
|
||||
## 用户需求
|
||||
|
||||
参考 `fms-vue/开发规范.md` 与 `fms/参考组件库/antdv-next` 的 Grid 组件，在 `fms-vue` 组件库中新增 Grid 栅格组件。
|
||||
|
||||
## 产品概述
|
||||
|
||||
基于 24 栅格系统的布局组件，包含 `Row` 容器与 `Col` 列两个组件，用于快速搭建页面布局。参考 antdv-next 的 API 设计与交互语义，遵循本项目 Vue 3 + scoped SCSS + `--fms-*` token 的约定。**不包含响应式断点（xs/sm/md/lg/xl/xxl/xxxl）**，仅实现基础栅格能力。
|
||||
|
||||
## 核心特性
|
||||
|
||||
- Row：flex 行容器，支持 `gutter`（水平/垂直间距，数字或 `[h, v]` 数组）、`align`（top/middle/bottom/stretch）、`justify`（start/end/center/space-around/space-between/space-evenly）、`wrap` 控制换行。
|
||||
- Col：列单元，支持 `span`（0-24）、`offset`、`order`、`push`、`pull`、`flex`。
|
||||
- gutter 水平间距由 Row 负 margin 抵消、Col 对称 padding 实现；垂直间距由 Row `row-gap` 实现。
|
||||
- 间距默认值通过 `tokens.css` 新增 `--fms-grid-gutter`（默认 0），演示中传入具体值。
|
||||
- 提供演示页面，展示基础栅格、gutter、对齐、偏移等典型用法。
|
||||
|
||||
## 技术栈
|
||||
|
||||
- Vue 3 `<script setup>` + 类型化 props，scoped SCSS（`@use './index.scss'`）
|
||||
- 纯 CSS 栅格（24 栅格百分比宽度 + flex 布局），不引入新依赖、不依赖 JS 断点监听
|
||||
- 复用 `src/theme/tokens.css` 的 `--fms-*` token；新增 `--fms-grid-gutter`
|
||||
|
||||
## 实现方案
|
||||
|
||||
### 策略
|
||||
|
||||
参照 antdv-next `grid/` 的 API（row.tsx、col.tsx）做 Vue 化移植，仅保留基础栅格能力（去除响应式 xs~xxxl）。Row 负责 flex 容器与 gutter 负边距/row-gap，Col 负责 span/offset/order/push/pull/flex。
|
||||
|
||||
### 关键技术决策
|
||||
|
||||
1. **纯静态 CSS 类**：24 栅格类（`.fms-col-{n}`，`n∈0..24`）与 offset/order/push/pull/flex 类全部由 `index.scss` 静态生成，无 JS 计算、无 resize 监听、无定时器。
|
||||
2. **gutter 实现**：Row 水平 gutter 用负左右 margin（`-gutter/2`），Col 用对称左右 padding（`gutter/2`）；垂直 gutter 用 Row `row-gap`。gutter 支持数字或 `[h, v]` 数组，由 Row 以 CSS 变量 `--fms-grid-gutter-h/-v` 下传，Col 读取使用，避免每列重复计算。
|
||||
3. **Col 属性注入**：`span/offset/order/push/pull` 映射到预设 class；`flex` 通过 computed 生成 inline `style` 注入（`flex: parseFlex(flex)`）。
|
||||
4. **API 收敛**：仅实现需求明确的 props；枚举（`align`/`justify`）提供 `validator`；不提供 `size` 枚举（符合规范 7.1）；不实现 xs~xxxl（用户明确取消）。
|
||||
5. **组件命名**：`defineOptions({ name: 'FmsRow' })` / `'FmsCol'`，与现有 `FmsSpin` 模式一致。
|
||||
|
||||
### 性能与可靠性
|
||||
|
||||
- 静态 class + CSS 变量，无高频事件、无布局读取、无残留监听。
|
||||
- gutter 变量由 Row 计算一次（computed），Col 通过 CSS 变量继承。
|
||||
- 无需 `prefers-reduced-motion` 处理（Grid 无动画）。
|
||||
|
||||
## 实现备注
|
||||
|
||||
- 复用现有 `.fms-<name>` 命名与 `index.scss` 引入方式（参考 splitter/index.scss）。
|
||||
- 不创建 barrel index（规范 3）。
|
||||
- 演示注册到 `App.vue`「布局」分类与 demoMap，与现有 demo 注册方式一致。
|
||||
- 不主动执行 `pnpm build`，仅做 oxlint 静态检查（规范 2）。
|
||||
|
||||
## 架构设计
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[页面/示例] --> B[Row 容器]
|
||||
B --> C[Col 列]
|
||||
B -->|提供 gutter CSS 变量 --fms-grid-gutter-h/-v| C
|
||||
C -->|span/offset/order/push/pull/flex| D[SCSS 栅格类]
|
||||
B -->|align/justify/wrap| D
|
||||
```
|
||||
|
||||
Row 与 Col 通过 CSS 变量（`--fms-grid-gutter-h/-v`）传递间距，栅格类全部由 `index.scss` 静态生成。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
fms-vue/src/components/ui/grid/
|
||||
row.vue # [NEW] Row 容器组件。实现 flex 布局、gutter 负 margin/row-gap、align/justify/wrap；将 gutter 拆为 --fms-grid-gutter-h/-v CSS 变量下传。
|
||||
col.vue # [NEW] Col 列组件。实现 span/offset/order/push/pull/flex；读取 Row 下传的 gutter 变量，数字→class，flex→computed style。
|
||||
index.scss # [NEW] 栅格样式。24 栅格类、flex/order/offset/push/pull 类、gutter 变量使用说明。无 media query。
|
||||
fms-vue/src/theme/tokens.css # [MODIFY] :root 新增 --fms-grid-gutter（默认 0），不随主题变化。
|
||||
fms-vue/src/components/ui/demo/grid.vue # [NEW] 演示：基础栅格、gutter、对齐、偏移。
|
||||
fms-vue/src/App.vue # [MODIFY] 引入 grid demo，注册到「布局」分类，加入 demoMap。
|
||||
```
|
||||
|
||||
## 关键代码结构
|
||||
|
||||
```ts
|
||||
// col.vue props（节选）
|
||||
const props = defineProps({
|
||||
span: { type: [Number, String], default: undefined },
|
||||
offset: { type: [Number, String], default: undefined },
|
||||
order: { type: [Number, String], default: undefined },
|
||||
push: { type: [Number, String], default: undefined },
|
||||
pull: { type: [Number, String], default: undefined },
|
||||
flex: { type: [Number, String], default: undefined },
|
||||
})
|
||||
|
||||
// row.vue props（节选）
|
||||
const props = defineProps({
|
||||
gutter: { type: [Number, Array], default: 0 },
|
||||
align: {
|
||||
type: String,
|
||||
default: undefined,
|
||||
validator: (v) => ['top', 'middle', 'bottom', 'stretch'].includes(v),
|
||||
},
|
||||
justify: {
|
||||
type: String,
|
||||
default: undefined,
|
||||
validator: (v) => ['start', 'end', 'center', 'space-around', 'space-between', 'space-evenly'].includes(v),
|
||||
},
|
||||
wrap: { type: Boolean, default: true },
|
||||
})
|
||||
```
|
||||
|
||||
## Agent Extensions
|
||||
|
||||
### Skill
|
||||
|
||||
- **antdv-next**
|
||||
- Purpose: 获取 Grid 组件的 API、props/events/slots 定义与语义设计参考，确保移植忠于原库交互（去除响应式部分）。
|
||||
- Expected outcome: 确认 Row/Col 的 props 集合、gutter 实现细节与 flex 解析规则，指导 Vue 化实现。
|
||||
Reference in new issue
Block a user