110 lines
3.9 KiB
Markdown
110 lines
3.9 KiB
Markdown
# overflow-fallback（技术计划）
|
||
|
||
## 1. 计划目标
|
||
|
||
实现统一的“溢出与兜底”策略模块，用于在以下情况给出确定性且可解释的返回：
|
||
|
||
- 搜索器无法在 `<=maxLines` 覆盖到结束边界 `N`
|
||
- `lineMode=FIXED` 需要刚好 `maxLines` 但无解
|
||
- 测量不可用或失败导致无法执行宽度派约束（尤其 Widget）
|
||
|
||
支持三种模式：
|
||
|
||
- `ELLIPSIS`：最后一行加省略号并保证不超宽（必要时回退移除 token 再加）
|
||
- `CLIP`：截断到 `maxLines`（不加省略号）
|
||
- `SYSTEM_DEFAULT`：算法层不插入换行，交给系统排版（仅在 meta 标记）
|
||
|
||
## 2. 对外输入/输出（与 spec 对齐）
|
||
|
||
### 2.1 输入
|
||
|
||
- `tokens: Token[]`
|
||
- `partialLayout?: { breaks: number[]; lines: Array<{ start; end; text? }> }`
|
||
- 若提供：表示搜索器的 best-effort（可能未覆盖到 N）
|
||
- `overflowMode: 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT'`
|
||
- `availableWidth: number`
|
||
- `maxLines: number`
|
||
- `lang: 'TC' | 'EN'`
|
||
- `context: 'APP' | 'WIDGET'`
|
||
- `ellipsisToken: string`（推荐 `"…"`，配置化）
|
||
- `measure?: { contextProfile; fontSpec; measureWidthImpl; widgetEnableMeasure? }`（用于“加省略号后再测量”）
|
||
- `reason: 'NO_CANDIDATE' | 'WIDTH_UNKNOWN' | 'TOO_LONG' | 'WIDOW' | 'PARTICLE' | string`
|
||
|
||
### 2.2 输出
|
||
|
||
统一返回：
|
||
|
||
- `result: { lines: string[]; wrappedText: string; meta: { fallback_type; overflow_type; reason } }`
|
||
|
||
其中：
|
||
|
||
- `fallback_type`: `NONE | RELAX_RULES | SYSTEM_DEFAULT`
|
||
- `overflow_type`: `NONE | ELLIPSIS | CLIP`
|
||
|
||
## 3. 核心行为细则（对应文档 12.x）
|
||
|
||
### 3.1 overflow 判定
|
||
|
||
在本模块内不重新跑搜索，仅基于输入判断：
|
||
|
||
- 若 `partialLayout` 覆盖到 `N`（即最后一行 `end==N`），则 overflow_type=NONE
|
||
- 否则为 overflow，按 overflowMode 执行
|
||
|
||
### 3.2 SYSTEM_DEFAULT（12.4A）
|
||
|
||
- 返回 `lines=[原文单行]`，`wrappedText=原文`
|
||
- `meta.fallback_type='SYSTEM_DEFAULT'`
|
||
- `meta.overflow_type='NONE'`（因为不再输出算法换行；由 UI 决定是否完全交给系统）
|
||
- `meta.reason=输入 reason`
|
||
|
||
### 3.3 CLIP
|
||
|
||
- 若 `partialLayout` 有 lines：取前 `maxLines` 行，重组 `wrappedText=lines.join('\n')`
|
||
- 若无：返回单行原文
|
||
- `meta.overflow_type='CLIP'`，`fallback_type='NONE'`，`reason=输入 reason`
|
||
|
||
### 3.4 ELLIPSIS（12.3/12.5）
|
||
|
||
仅处理最后一行：
|
||
|
||
1. 选取 baseLines：
|
||
- 优先使用 `partialLayout.lines`（若为空则把全文当单行）
|
||
- 截断到 `maxLines`（只在最后一行做 ellipsis）
|
||
2. 清理规则（固定，确定性）：
|
||
- 不输出 `" …"`：最后一行末尾空白先 trim
|
||
- 不输出 `"，…"/"。…"`：若最后一行末尾是常见 TC 标点（`，。！？；：、`），则移除该标点再加 ellipsis
|
||
3. 宽度检查（12.3）：
|
||
- 若提供测量能力且启用：
|
||
- 重新测量 `lastLine+ellipsisToken`
|
||
- 若超宽：按语言回退单位移除 token 再加省略号并重测
|
||
- EN：按整词（token）
|
||
- TC：按 grapheme（token）
|
||
- 若测量不可用：不做重测，直接输出（meta.reason 仍保留）
|
||
|
||
> 说明：首版不做“避免截断 emotionPhrase 的整段前移/整段省略”，该策略可在后续结合 scoring 决策升级，但必须保持确定性。
|
||
|
||
## 4. 代码落位（客户端）
|
||
|
||
- `client/src/features/textWrap/overflow/`
|
||
- `types.ts`
|
||
- `ellipsis.ts`
|
||
- `fallback.ts`（入口：applyOverflowFallback）
|
||
- `index.ts`
|
||
- `__tests__/overflowFallback.test.ts`
|
||
|
||
## 5. 测试计划（Vitest）
|
||
|
||
- SYSTEM_DEFAULT：lines 单行，meta.fallback_type=SYSTEM_DEFAULT
|
||
- CLIP：超过 maxLines 时截断行数
|
||
- ELLIPSIS：
|
||
- 末尾空白去除，不输出 `" …"`
|
||
- 末尾 TC 标点去除，不输出 `"，…"`
|
||
- 测量超宽时按 token 回退直到不超宽（用 mock measureWidthImpl）
|
||
|
||
## 6. 完成定义（DoD）
|
||
|
||
- 三种 overflowMode 行为稳定且可解释
|
||
- ELLIPSIS 的清理与回退测量实现完毕（可测）
|
||
- 输出 meta 字段满足文档 12/14 的治理需求
|
||
|