|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 |
# 跨端文本省略与动态排版 Skill 单行和多行省略经常在字号放大、字体加载或隐藏恢复后失效。这份 Skill 把运行时选型、真实排版、状态恢复和验收串成固定流程,适用于 Web、原生控件、小程序及自绘环境。遇到原生能力的实际缺口,再选择最小回退。 将下方完整内容保存为 `dynamic-text-ellipsis/SKILL.md`。 ```markdown --- name: dynamic-text-ellipsis description: 处理各端单行或多行文本省略、末字裁切、省略号覆盖正文,以及字号行高变化后截断失效的问题。适用于 Web、WebView、原生控件、小程序和自绘渲染器;当任务涉及行数限制、末行对齐或动态省略时使用。仅在明确要求时衔接缩字号流程,不用于独立的字号自适应实现。 --- # 跨端文本省略与动态排版 ## 确认输入与边界 - 确认运行时、实际渲染器及最低版本,不按框架名称推断底层能力。移动端无其他约定时,按 Android 7、iOS 10 核对;其他端遵循项目最低版本。 - 获取完整原文、最大行数、换行策略、对齐、文本方向、字体族、字重、字号、行高及尺寸约束。确认交互、全文入口和辅助功能契约。 - 确认是否允许脚本测量、独立省略号及字符串裁剪。复用已有组件,保持原字体与原文,不自行改变需求。 ## 选择目标端原生能力 - Web、H5、WebView 优先 CSS 省略。单行使用 white-space: nowrap、overflow: hidden、text-overflow: ellipsis;flex/grid 文本项核对 min-width: 0 和有效宽度。 - Web 多行在同一文本层组合 display: -webkit-box、-webkit-box-orient: vertical、-webkit-line-clamp: N 和隐藏溢出,并检查构建后声明。低版本不单独依赖无前缀 line-clamp,无需额外叠加 text-overflow。 - 原生移动端和桌面端使用平台文本控件、段落或文本布局引擎。跨平台框架核对实际落到 Web、原生控件还是自绘引擎;小程序先查平台组件与允许的布局查询,不预设 DOM。 - 自绘、图形和文档渲染使用对应排版器,让正文、省略号和裁切共享坐标、缩放与字体度量。服务端没有排版上下文时保留完整原文,另行明确字符、字素或字节限制,不承诺视觉行数。 - 分别验证行数、末字、省略号及所需对齐。justify 与原生省略按目标环境实测,不统一禁用;不依赖 text-align-last 覆盖 iOS 10。不未经复现就认定 break-all 或按钮必然致错。 ## 按实际布局判断溢出 1. 等待本端布局完成。不可见或尺寸为零时,等待可见性或布局事件,不据此截断。 2. 撤销本实现上一次拥有的临时高度、宽度、尾部占位及省略状态;记录覆盖归属,保留宿主样式,避免旧处理污染新判断。 3. 使用实际字体和有效尺寸,让本端排版器决定断行。字符数量不代表像素宽度,不为普通省略预先裁剪字符串。 4. 统一行高的纯文本可用“最大行数 × 实际行高”计算高度上限。混合字号、富文本或不同基线查看实际各行布局;字号放大后容纳真实文字范围,不沿用固定像素上限。 5. 独立尾部按实际尺寸预留空间,让正文避让,不能覆盖末字。只按撤销尾部后的原始布局判定溢出。 6. 只有明确要求先缩字号再省略时才执行该顺序,字号不低于约定下限。确需裁剪时,按字素边界与排版结果处理,不拆开多字节字符、代理对或组合字符;行尾按文本方向判断。 ## 复现后选择最小回退 先记录系统、渲染器版本、字体、尺寸、原文与异常证据,排查布局约束、继承样式和发布产物。原生能力仍不满足,且任务允许时,才采用本端最小测量或布局回退。不因担忧旧环境而提前替换原生方案,不通过改为左对齐、换字体或改写内容放宽验收。 Web 浮动占位仅用于支持浮动绕排的 Web 渲染器,且已复现原生问题、允许独立省略号和少量布局测量时: - 保留完整纯文本。容器内 DOM 顺序固定为“零宽侧向浮动占位 → 同侧浮动尾部 → 原文文本节点”,按文本方向选择侧向。左到右、右侧尾部时,两者 float: right,尾部 clear: right。 - 统一行高时,占位高度为(行数 − 1)× 实际行高,尾部高度为一行,容器上限为行数 × 实际行高并隐藏后续行。不要叠加原生 line-clamp 或绝对定位遮罩。 - 判溢出前取消尾部占位,再比较 scrollHeight 与 clientHeight;仅溢出时启用尾部。容器、占位和尾部几何同步更新。 - 字体探针放在容器滚动区域之外,只感知字体布局变化,避免空文本误判。实际行高结合计算样式和原文 Range 行内矩形核对,不逐字测宽,不复制全文做二分搜索。 - 对齐和内部字体承受页面字号变化,必要样式优先级只限组件内部。连续英文长串可能没有可分配间隙,不保证任意内容逐行满铺。 - 探针、占位和装饰省略号对辅助功能隐藏,保留完整可访问原文。 非 Web 端使用本端行布局、裁切和尾部省略。原生控件无法组合所需能力时,再评估本端行盒测量、尾部预留或受控绘制;不得要求 CSS 浮动、DOM 或浏览器观察器。核对字体回退、系统文字缩放与布局方向,沿用本端辅助功能语义。 ## 刷新与资源释放 - 内容、参数、字号、行高、容器、缩放、样式、资源加载及显隐变化后重算,保证放大再缩小、长文换短文时能出现和取消省略。 - Web 观察容器与字体探针尺寸,兼顾字体、祖先属性、样式注入或加载、可见性事件;不只监听宽度。各 API 特性检测,低版本接入本端回退或显式刷新。 - 将任务按帧或布局批次合并,过滤自身写入,避免观察器循环。不用持续轮询掩盖未知变化;旧环境无法观察的 CSSOM 等操作由宿主事件或显式刷新承接,不宣称监听全部外部操作。 - 点击控件与截断层分工。自定义 slot/SVG 检查最终文字层,硬裁切或末字截半不算成功。销毁时释放观察器、监听和待执行任务。 ## 验收与交付 - 覆盖空文本、未溢出、刚好容纳、超过限制;仅溢出时显示省略号。逐行核对行数、末字、尾部避让及对齐,短文本不异常拉伸。 - 覆盖本次支持的混排、长串、标点和文本方向;确认实际字体及回退。验证字号放大还原、独立行高变化、尺寸变化、内容更新和隐藏恢复。 - 在真实宿主及目标最低版本检查性能和资源释放。交付列出原始复现路径、实现或回退条件、框架与引擎、系统、设备或模拟器范围、各状态结果及未验证范围。 - 不将构建、类型检查、静态检查或某台设备成功推广为其他端兼容;仍有裁切、覆盖或对齐异常时不得宣称完成。 ``` ## 调用示例 **示例一** 使用 dynamic-text-ellipsis 检查摘要组件。要求两行省略并保持两端对齐,字号从 14px 改到 22px 后末行被裁切。保留现有字体和完整原文,先复现并检查原生方案,再决定是否需要回退。 **示例二** 使用 dynamic-text-ellipsis 修复卡片标题隐藏后重新显示时省略状态错误的问题。标题从长文更新为短文后,应取消省略号。请覆盖容器尺寸变化、字体加载和组件卸载,并列出真实宿主中的验证结果。 |