9.1 KiB
9.1 KiB
附录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 推荐实现顺序
- 首选：对子项显式加 class 或动态 class
- 次选：在
wx:for中通过index > 0加样式 - 末选：组合选择器实现，例如
.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 执行准则
- Flex 相关优先直接映射。
- Grid、sticky、vh、space-y 一律视为条件项。
- 映射失败时，优先结构改写，不要硬凑 CSS。
- 布局问题优先从 WXML 层级和滚动容器检查，不要只盯着样式。
- 任何需要依赖 DOM 关系链才能成立的 Tailwind 技巧，都不要默认当成稳态能力。
D.12 附录结论
本附录的目的不是证明“Tailwind 布局类都能 1:1 翻译”，而是：
- 给 AI 一个白名单映射表
- 把高风险布局点提前分级
- 降低批量迁移时的误判率