# 附录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 一个**白名单映射表**
- 把高风险布局点提前分级
- 降低批量迁移时的误判率
