小程序迁移静态页面完成！！！

2026-03-18 05:14:35 +08:00
parent 72bb11b34f
commit 075caf067f
124 changed files with 10407 additions and 2738 deletions
--- a/docs/miniprogram-dev/h5-migration/appendix/typography-dictionary.md
+++ b/docs/miniprogram-dev/h5-migration/appendix/typography-dictionary.md
@@ -0,0 +1,266 @@
+# 附录B：字体与文本字典 v3.1
+
+> 角色：文本层映射字典  
+> 用途：处理 Tailwind `text-*`、`leading-*`、`font-*`、文本对齐、省略、装饰、字距等  
+> 核心原则：**标准字号可表驱动；arbitrary 字号不得拍脑袋推导行高**  
+> **v3.1 更新**：补充微信小程序 text 组件的 line-height 设置规则
+
+---
+
+## B.1 使用边界
+
+### B.1.1 本附录可以直接用于
+
+- 标准 `text-xs/sm/base/lg/xl/2xl/3xl`
+- 标准 `font-normal / medium / semibold / bold`
+- `text-left / center / right`
+- `truncate`
+- `whitespace-nowrap`
+- `underline / line-through`
+- 常见 `leading-*`
+- 常见 `tracking-*`
+
+### B.1.2 本附录不能直接替代视觉提取的场景
+
+- arbitrary `text-[Npx]`
+- 多层嵌套文本组合
+- 特殊数字对齐
+- 自定义字体族
+- 同时依赖字重、字距、行高的标题排版
+- 富文本渲染
+
+---
+
+## B.2 核心规则
+
+### B.2.1 标准字号类：必须同时写字号与行高
+
+Tailwind 标准字号 utility 自带默认 `line-height`。  
+因此，迁移到 WXSS 时，**不能只写 `font-size`，遗漏 `line-height`**。
+
+### B.2.2 Arbitrary 字号：不允许按"1.2 倍"硬猜
+
+对 `text-[10px]`、`text-[11px]` 这类 arbitrary 字号：
+
+- 不允许在项目规范中统一假定其 `line-height = 1.2 × font-size`
+- 必须优先读取原型计算样式，或以页面实际视觉高度为准
+- 若确实拿不到计算样式，可先给"临时候选值"，但必须标记为待复核
+
+### B.2.3 微信小程序 text 组件的 line-height 设置规则 ⚠️
+
+**关键发现**：微信小程序的 `<text>` 组件不能直接设置 `line-height`，必须通过外层 `<view>` 设置。
+
+#### 正确做法
+
+**全局设置：**
+```wxss
+page {
+  line-height: 1.5; /* Tailwind 默认行高 */
+}
+
+view {
+  line-height: inherit; /* view 继承 page 的 line-height */
+}
+
+/* text 会自动继承外层 view 的 line-height，不需要额外设置 */
+```
+
+**局部覆盖：**
+```wxss
+.section-title {
+  font-size: 26rpx;
+  line-height: 36rpx; /* 在 view 的 class 上设置，text 会继承 */
+  font-weight: 600;
+}
+```
+
+```wxml
+<view class="section-title">
+  <text>标题文本</text>
+</view>
+```
+
+#### 错误做法
+
+```wxss
+/* ❌ 直接在 text 上设置 line-height 无效 */
+text {
+  line-height: 36rpx; /* 不会生效 */
+}
+
+/* ❌ 添加 display: inline-block 也无效 */
+text {
+  display: inline-block;
+  line-height: 36rpx; /* 仍然不会生效 */
+}
+```
+
+#### 原因
+
+- 微信小程序的 `<text>` 是特殊的内联组件
+- 直接在 `<text>` 上设置 `line-height` 不生效
+- 必须在外层 `<view>` 上设置，text 会自动继承
+- 这是平台限制，不是 CSS 问题
+
+#### 验证方法
+
+- 在开发者工具的 Computed 面板中，text 元素不会显示 `line-height` 属性
+- 但外层 view 的 `height` 值会包含行高效果
+- 以真机视觉效果为准
+
+---
+
+## B.3 标准字号 → WXSS 对照表
+
+> 以下表格可作为**硬映射白名单**使用。
+
+| Tailwind class | font-size | line-height | H5 px | WXSS 建议写法 | 备注 |
+|---|---:|---:|---:|---|---|
+| `text-xs` | `0.75rem` | `1rem` | 12 / 16 | `font-size: 22rpx; line-height: 29rpx;` | 可直接使用 |
+| `text-sm` | `0.875rem` | `1.25rem` | 14 / 20 | `font-size: 26rpx; line-height: 36rpx;` | 可直接使用 |
+| `text-base` | `1rem` | `1.5rem` | 16 / 24 | `font-size: 30rpx; line-height: 44rpx;` | 可直接使用 |
+| `text-lg` | `1.125rem` | `1.75rem` | 18 / 28 | `font-size: 33rpx; line-height: 51rpx;` | 可直接使用 |
+| `text-xl` | `1.25rem` | `1.75rem` | 20 / 28 | `font-size: 36rpx; line-height: 51rpx;` | 可直接使用 |
+| `text-2xl` | `1.5rem` | `2rem` | 24 / 32 | `font-size: 44rpx; line-height: 58rpx;` | 可直接使用 |
+| `text-3xl` | `1.875rem` | `2.25rem` | 30 / 36 | `font-size: 54rpx; line-height: 66rpx;` | 可直接使用 |
+
+**换算公式**：
+```
+font-size(rpx) = font-size(px) × 1.8204
+line-height(rpx) = line-height(px) × 1.8204
+```
+
+**示例**：
+- `text-sm` 的 font-size = 14px × 1.8204 = 25.49rpx ≈ **26rpx**
+- `text-sm` 的 line-height = 20px × 1.8204 = 36.41rpx ≈ **36rpx**
+
+---
+
+## B.4 Arbitrary 字号候选表（仅候选，不是硬规则）
+
+> 来源：旧桥文档中项目高频小字号总结。  
+> 这些值可用于**初始落地**，但必须经过真机视觉复核。
+
+| Tailwind class | font-size(px) | WXSS 候选 `font-size` | `line-height` 处理规则 | 风险级别 |
+|---|---:|---:|---|---|
+| `text-[9px]` | 9 | 16rpx | 禁止硬猜，需按原型提取或视觉校准 | 高 |
+| `text-[10px]` | 10 | 18rpx | 同上 | 高 |
+| `text-[11px]` | 11 | 20rpx | 同上 | 高 |
+| `text-[12px]` | 12 | 22rpx | 同上 | 高 |
+| `text-[13px]` | 13 | 24rpx | 同上 | 高 |
+
+### B.4.1 若拿不到原型计算样式时的临时占位策略
+
+仅用于**先产出页面、后做复核**的场景：
+
+- 单行文本：可先不显式写 `line-height`，由真实内容撑开后观察
+- 双行及以上文本：先给一个略宽松的 `line-height` 候选，再做真机校正
+- 一旦发现文本块高度、裁切、对齐异常，必须回到原型测量
+
+> 这条是应急策略，不是长期规范。
+
+---
+
+## B.5 Font Weight 映射表
+
+| Tailwind class | CSS font-weight | WXSS 写法 | 备注 |
+|---|---:|---|---|
+| `font-normal` | 400 | `font-weight: 400;` | 可直接使用 |
+| `font-medium` | 500 | `font-weight: 500;` | 注意不是 600 |
+| `font-semibold` | 600 | `font-weight: 600;` | 可直接使用 |
+| `font-bold` | 700 | `font-weight: 700;` | 可直接使用 |
+
+---
+
+## B.6 Font Family / 字体族处理规则
+
+| Tailwind class | 默认含义 | 小程序迁移建议 |
+|---|---|---|
+| `font-sans` | 系统无衬线字体栈 | 允许省略，交由系统默认字体；若页面强依赖，则单独定义字体栈 |
+| `font-serif` | 系统衬线字体栈 | 本项目一般不建议使用 |
+| `font-mono` | 等宽字体栈 | 仅在数字/代码块等特殊场景使用 |
+| `font-[...]` | 自定义字体族 | 必须单独评估是否可在小程序端稳定落地 |
+
+### 建议
+- 业务正文、列表、表单：优先使用系统默认字体策略
+- 若页面依赖特定数字对齐效果，再单独处理数字字体
+
+---
+
+## B.7 其他文本属性映射表
+
+### B.7.1 文本对齐
+
+| Tailwind class | WXSS |
+|---|---|
+| `text-left` | `text-align: left;` |
+| `text-center` | `text-align: center;` |
+| `text-right` | `text-align: right;` |
+
+### B.7.2 溢出与省略
+
+| Tailwind class | WXSS 建议写法 | 备注 |
+|---|---|---|
+| `truncate` | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;` | 可直接使用 |
+| `whitespace-nowrap` | `white-space: nowrap;` | 可直接使用 |
+| `line-clamp-2` | `display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden;` | 条件能力，需实测 |
+| `line-clamp-3` | 同上，`-webkit-line-clamp: 3` | 条件能力，需实测 |
+
+### B.7.3 Line-height 工具类
+
+| Tailwind class | CSS | WXSS |
+|---|---|---|
+| `leading-none` | `line-height: 1` | `line-height: 1;` |
+| `leading-tight` | `line-height: 1.25` | `line-height: 1.25;` |
+| `leading-snug` | `line-height: 1.375` | `line-height: 1.375;` |
+| `leading-normal` | `line-height: 1.5` | `line-height: 1.5;` |
+| `leading-relaxed` | `line-height: 1.625` | `line-height: 1.625;` |
+| `leading-loose` | `line-height: 2` | `line-height: 2;` |
+
+### B.7.4 Letter-spacing / 字距
+
+| Tailwind class | CSS | WXSS |
+|---|---|---|
+| `tracking-tight` | `letter-spacing: -0.025em` | `letter-spacing: -0.025em;` |
+| `tracking-normal` | `letter-spacing: 0` | `letter-spacing: 0;` |
+| `tracking-wide` | `letter-spacing: 0.025em` | `letter-spacing: 0.025em;` |
+| `tracking-wider` | `letter-spacing: 0.05em` | `letter-spacing: 0.05em;` |
+| `tracking-widest` | `letter-spacing: 0.1em` | `letter-spacing: 0.1em;` |
+
+### B.7.5 文本装饰
+
+| Tailwind class | WXSS |
+|---|---|
+| `underline` | `text-decoration: underline;` |
+| `line-through` | `text-decoration: line-through;` |
+| `italic` | `font-style: italic;` |
+| `not-italic` | `font-style: normal;` |
+
+### B.7.6 数字排版
+
+| Tailwind class | 处理建议 |
+|---|---|
+| `tabular-nums` | 若小程序端表现不稳定，不作为硬依赖；涉及金额/绩效表格时优先真机验证 |
+| `lining-nums` / `oldstyle-nums` | 同上，不建议直接作为项目硬规范 |
+
+---
+
+## B.8 文本层 AI 执行准则
+
+1. 标准字号表可直接用。  
+2. arbitrary 字号不许猜固定行高。  
+3. **line-height 必须在外层 view 上设置，不能直接在 text 上设置。**  
+4. 单行截断可直接迁移；多行截断需列入"条件能力"。  
+5. 文字高度不对时，优先检查：`line-height`、字重、padding、容器 `align-items`。  
+6. 小字号（9~13px）是本项目高频区，必须留足复核预算。
+
+---
+
+## B.9 附录结论
+
+本表最重要的价值是：
+
+- 让标准字号稳定落地
+- 避免 AI 漏掉 line-height
+- 防止 arbitrary 字号被机械"1.2 倍化"
+- **明确 text 组件的 line-height 设置规则，避免无效设置**