205 lines
9.1 KiB
Markdown
205 lines
9.1 KiB
Markdown
# 附录D：布局类映射字典 v3.0
|
||
|
||
> 角色：布局白名单映射表
|
||
> 用途：把 Tailwind 中与布局相关的 class 映射到 WXSS / WXML
|
||
> 核心原则：**分级映射，不做“浏览器 CSS 全等价”假设**
|
||
|
||
---
|
||
|
||
## D.1 分级说明
|
||
|
||
### A 类：可直接映射
|
||
在当前项目中，通常可直接从 Tailwind 写法转换到 WXSS。
|
||
|
||
### B 类：条件映射
|
||
可以用，但必须结合页面结构、滚动容器、设备表现或降级方案。
|
||
|
||
### C 类：禁止机械映射
|
||
不能把 H5 的做法直接搬过去，必须改成小程序的数据驱动实现或结构性改写。
|
||
|
||
---
|
||
|
||
## D.2 Flexbox 映射表（A 类）
|
||
|
||
| Tailwind class | CSS 含义 | WXSS / WXML 写法 | 级别 | 备注 |
|
||
|---|---|---|---|---|
|
||
| `flex` | `display: flex` | `display: flex;` | A | 可直接使用 |
|
||
| `inline-flex` | `display: inline-flex` | `display: inline-flex;` | A | 条件使用，视组件而定 |
|
||
| `flex-col` | `flex-direction: column` | `flex-direction: column;` | A | 可直接使用 |
|
||
| `flex-row` | `flex-direction: row` | 默认即可 / 显式写出 | A | 可直接使用 |
|
||
| `flex-1` | `flex: 1 1 0%` | `flex: 1;` | A | 项目中可简化 |
|
||
| `flex-[2]` | `flex: 2` | `flex: 2;` | A | arbitrary 数值可保留 |
|
||
| `flex-wrap` | `flex-wrap: wrap` | `flex-wrap: wrap;` | A | 可直接使用 |
|
||
| `flex-nowrap` | `flex-wrap: nowrap` | `flex-wrap: nowrap;` | A | 可直接使用 |
|
||
| `shrink-0` / `flex-shrink-0` | `flex-shrink: 0` | `flex-shrink: 0;` | A | 高频 |
|
||
| `grow` | `flex-grow: 1` | `flex-grow: 1;` | A | 若出现可直接映射 |
|
||
| `items-center` | `align-items: center` | `align-items: center;` | A | 高频 |
|
||
| `items-start` | `align-items: flex-start` | `align-items: flex-start;` | A | 可直接使用 |
|
||
| `items-end` | `align-items: flex-end` | `align-items: flex-end;` | A | 可直接使用 |
|
||
| `items-baseline` | `align-items: baseline` | `align-items: baseline;` | A | 需注意文本基线差异 |
|
||
| `justify-between` | `justify-content: space-between` | `justify-content: space-between;` | A | 高频 |
|
||
| `justify-center` | `justify-content: center` | `justify-content: center;` | A | 高频 |
|
||
| `justify-end` | `justify-content: flex-end` | `justify-content: flex-end;` | A | 可直接使用 |
|
||
| `justify-start` | `justify-content: flex-start` | `justify-content: flex-start;` | A | 可直接使用 |
|
||
|
||
---
|
||
|
||
## D.3 Grid 映射表（B 类）
|
||
|
||
| Tailwind class | CSS 含义 | WXSS 写法 | 级别 | 执行规则 |
|
||
|---|---|---|---|---|
|
||
| `grid` | `display: grid` | `display: grid;` | B | 必须真机验证 |
|
||
| `grid-cols-2` | `repeat(2, minmax(0, 1fr))` | `grid-template-columns: repeat(2, minmax(0, 1fr));` | B | 简单均分可用 |
|
||
| `grid-cols-3` | 同上三列 | 同上 | B | 简单均分可用 |
|
||
| `grid-cols-4` | 同上四列 | 同上 | B | 简单均分可用 |
|
||
| `col-span-*` | 跨列 | 条件实现 | B | 出现时单独验证 |
|
||
|
||
### D.3.1 Grid 使用限制
|
||
|
||
- 仅用于简单卡片宫格、图标宫格、均分布局
|
||
- 一旦出现复杂响应、自适应内容挤压、滚动嵌套，应优先改为 `flex + wrap`
|
||
- 不把 `grid` 写成项目硬依赖
|
||
|
||
---
|
||
|
||
## D.4 Gap 映射表（A/B 混合）
|
||
|
||
> `gap` 本身可映射，但在复杂容器和兼容边界上应视为条件项。
|
||
|
||
| Tailwind class | CSS | WXSS | 级别 | 备注 |
|
||
|---|---|---|---|---|
|
||
| `gap-0.5` | `gap: 2px` | `gap: 4rpx;` | A | 简单容器可用 |
|
||
| `gap-1` | `gap: 4px` | `gap: 8rpx;` | A | 可直接使用 |
|
||
| `gap-1.5` | `gap: 6px` | `gap: 12rpx;` | A | 可直接使用 |
|
||
| `gap-2` | `gap: 8px` | `gap: 14rpx;` | A | 可直接使用 |
|
||
| `gap-2.5` | `gap: 10px` | `gap: 18rpx;` | A | 可直接使用 |
|
||
| `gap-3` | `gap: 12px` | `gap: 22rpx;` | A | 可直接使用 |
|
||
| `gap-4` | `gap: 16px` | `gap: 30rpx;` | A | 高频 |
|
||
| `gap-5` | `gap: 20px` | `gap: 36rpx;` | A | 可直接使用 |
|
||
| `gap-6` | `gap: 24px` | `gap: 44rpx;` | A | 高频 |
|
||
| `gap-x-4` | `column-gap: 16px` | `column-gap: 30rpx;` | B | 需结合容器测试 |
|
||
| `gap-y-1` | `row-gap: 4px` | `row-gap: 8rpx;` | B | 需结合容器测试 |
|
||
|
||
---
|
||
|
||
## D.5 定位与层级（A/B 混合）
|
||
|
||
| Tailwind class | CSS | WXSS | 级别 | 备注 |
|
||
|---|---|---|---|---|
|
||
| `relative` | `position: relative` | `position: relative;` | A | 可直接使用 |
|
||
| `absolute` | `position: absolute` | `position: absolute;` | A | 可直接使用 |
|
||
| `fixed` | `position: fixed` | `position: fixed;` | A | 需关注安全区 |
|
||
| `sticky` | `position: sticky` | `position: sticky; top: ...` | B | 仅页面自然滚动中优先使用 |
|
||
| `inset-0` | `top/right/bottom/left: 0` | 拆成四个方向 | A | 直接拆写 |
|
||
| `top-0` / `right-0` / `bottom-0` / `left-0` | 0 定位 | 同名属性 | A | 可直接使用 |
|
||
| `top-1/2` / `left-1/2` | 50% 定位 | 保持百分比 | A | 不转 `rpx` |
|
||
| `-translate-x-1/2` | `transform: translateX(-50%)` | 同左 | A | 可直接使用 |
|
||
| `-translate-y-1/2` | `transform: translateY(-50%)` | 同左 | A | 可直接使用 |
|
||
| `z-10` / `z-20` / `z-50` / `z-[100]` | `z-index` | `z-index` | A | 可直接使用 |
|
||
|
||
### D.5.1 Sticky 额外规则
|
||
|
||
- 页面滚动优先于 `scroll-view`
|
||
- `scroll-view` 内 sticky 一律列为高风险
|
||
- 多层 sticky 不要叠加，优先保留最外层
|
||
|
||
---
|
||
|
||
## D.6 尺寸类映射（A/B 混合）
|
||
|
||
| Tailwind class | CSS | WXSS | 级别 | 备注 |
|
||
|---|---|---|---|---|
|
||
| `w-full` | `width: 100%` | `width: 100%;` | A | 可直接使用 |
|
||
| `h-full` | `height: 100%` | `height: 100%;` | A | 可直接使用 |
|
||
| `w-1/2` | `width: 50%` | `width: 50%;` | A | 可直接使用 |
|
||
| `min-w-0` | `min-width: 0` | `min-width: 0;` | A | 文本截断场景常用 |
|
||
| `min-h-screen` | `min-height: 100vh` | `min-height: 100vh;` | B | 条件能力，需考虑导航/安全区 |
|
||
| `max-w-sm` | `max-width: 384px` | `max-width: 700rpx;` | B | 仅限内容容器 |
|
||
| `max-w-xs` | `max-width: 320px` | `max-width: 582rpx;` | B | 仅限内容容器 |
|
||
|
||
> 其他固定尺寸参照《附录A：Spacing 与尺寸字典》。
|
||
|
||
---
|
||
|
||
## D.7 显示、隐藏与溢出（A/B 混合）
|
||
|
||
| Tailwind class | CSS | WXSS | 级别 | 备注 |
|
||
|---|---|---|---|---|
|
||
| `block` | `display: block` | `display: block;` | A | 可直接使用 |
|
||
| `inline-block` | `display: inline-block` | `display: inline-block;` | A | 可直接使用 |
|
||
| `hidden` | `display: none` | `display: none;` | A | 与 `wx:if` / `hidden` 结合使用 |
|
||
| `overflow-hidden` | `overflow: hidden` | `overflow: hidden;` | A | 可直接使用 |
|
||
| `overflow-x-auto` | `overflow-x: auto` | 条件使用 | B | 小程序组件层需实测 |
|
||
| `overflow-y-auto` | `overflow-y: auto` | 条件使用 | B | 整页滚动优先自然滚动 |
|
||
|
||
---
|
||
|
||
## D.8 `space-y-*` 映射（B 类）
|
||
|
||
> `space-y` 本质是对子元素间距的语法糖。
|
||
> Tailwind 官方也说明，它并不适合复杂 DOM 顺序、换行布局、网格混排等场景。
|
||
|
||
| Tailwind class | 视觉含义 | 默认迁移方式 | 级别 | 推荐顺序 |
|
||
|---|---|---|---|---|
|
||
| `space-y-0` | 相邻子元素无间距 | 子元素首项外其余 `margin-top: 0` | B | 子项显式 class 优先 |
|
||
| `space-y-1` | 4px | `margin-top: 8rpx` | B | 子项显式 class 优先 |
|
||
| `space-y-1.5` | 6px | `margin-top: 12rpx` | B | 同上 |
|
||
| `space-y-2` | 8px | `margin-top: 14rpx` | B | 同上 |
|
||
| `space-y-2.5` | 10px | `margin-top: 18rpx` | B | 同上 |
|
||
| `space-y-3` | 12px | `margin-top: 22rpx` | B | 同上 |
|
||
| `space-y-4` | 16px | `margin-top: 30rpx` | B | 同上 |
|
||
|
||
### D.8.1 推荐实现顺序
|
||
|
||
1. **首选**：对子项显式加 class 或动态 class
|
||
2. **次选**：在 `wx:for` 中通过 `index > 0` 加样式
|
||
3. **末选**：组合选择器实现，例如 `.parent > .item + .item`
|
||
|
||
### D.8.2 不推荐
|
||
|
||
- 默认写死 `.parent > view + view`
|
||
- 把 `space-y` 用在复杂组件树、条件渲染、混合节点类型场景中
|
||
|
||
---
|
||
|
||
## D.9 `divide-y` 映射（B 类）
|
||
|
||
| Tailwind class | 视觉含义 | 小程序实现 | 级别 | 备注 |
|
||
|---|---|---|---|---|
|
||
| `divide-y` | 子项之间有分割线 | 子项首项外其余加 `border-top` | B | 推荐在 item 上显式控制 |
|
||
| `divide-gray-100` | 浅灰分割线 | `border-color: #f3f4f6;` | B | 需结合颜色字典 |
|
||
|
||
---
|
||
|
||
## D.10 WXML 结构改写规则（C 类约束）
|
||
|
||
以下不是单纯 WXSS 问题，而是布局迁移时最容易出错的点：
|
||
|
||
| H5 写法 | 小程序处理 |
|
||
|---|---|
|
||
| 用 DOM 选择器动态插入 / 删除 class | 改为 `data` + 条件 class |
|
||
| 用 `innerHTML` 渲染布局块 | 改为 WXML 结构和数据驱动 |
|
||
| 用浏览器滚动容器联动布局 | 改为页面滚动 + `onPageScroll` / 查询 API |
|
||
| 用 `history.back()` 控制返回 | 改为 `wx.navigateBack()` |
|
||
| 用 `window.scrollTo()` 定位 | 改为页面滚动接口或锚点方案 |
|
||
|
||
---
|
||
|
||
## D.11 AI 执行准则
|
||
|
||
1. Flex 相关优先直接映射。
|
||
2. Grid、sticky、vh、space-y 一律视为条件项。
|
||
3. 映射失败时，优先结构改写，不要硬凑 CSS。
|
||
4. 布局问题优先从 WXML 层级和滚动容器检查，不要只盯着样式。
|
||
5. 任何需要依赖 DOM 关系链才能成立的 Tailwind 技巧，都不要默认当成稳态能力。
|
||
|
||
---
|
||
|
||
## D.12 附录结论
|
||
|
||
本附录的目的不是证明“Tailwind 布局类都能 1:1 翻译”，而是：
|
||
|
||
- 给 AI 一个**白名单映射表**
|
||
- 把高风险布局点提前分级
|
||
- 降低批量迁移时的误判率
|