|
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 |
# 跨端自适应文本字号 Skill 卡片名称、表格单元格和窄导航,常有“先缩字号,到下限再省略”的需求。下面这份 Skill 把测量、字号恢复、动态刷新、性能和验收条件放在一起,供编程助手执行。它适用于明确要求缩字号的场景,保留各端原生排版能力,也约束字体、单位和无障碍边界。 将下方完整内容保存为 `auto-fit-text/SKILL.md`。 ```markdown --- name: auto-fit-text description: 当用户明确要求文本先缩小字号以完整显示、到最小字号仍溢出才省略,或要求修复此类组件的测量、恢复、动态刷新及性能问题时使用。适用于卡片、单元格、窄导航和数值展示;普通文本省略、正文换行及系统文字缩放不单独触发。 --- # 自适应字号文本 ## 确认边界与输入 1. 先识别目标语言、框架、实际渲染器及最低版本,检查现有组件与原生能力,优先复用。共享流程与验收目标,各端采用自身测量、单位及生命周期;仅 Web 使用下文 CSS、DOM、Range 和浏览器观察器。 2. 确认完整原文、宽度约束、字体族、字重、对齐、文本方向、换行策略与允许行数。不得换字体、改内容或放宽对齐要求来通过验收;无排版上下文的服务端不能按字符数保证视觉行数。 3. 明确 content/children、min、可选 max、lines(默认 1)、安全 tag 与属性、事件透传。继承宿主字体、字重、颜色和对齐,不加业务特例。纯文本默认转义;HTML 仅显式开启且已安全处理。 4. 明确 min/max 是设计 px 还是当前 CSS px。转 rem 时,前者按构建 rootValue,后者按当前根字号;不得混用设计 px 与 DOM CSS px。下限须满足可读性;正文优先换行,不用缩字抵消系统无障碍放大,必要时调整布局或提供可发现的全文入口。 ## 按顺序测量与恢复 1. 等本端布局及框架 DOM 更新完成。每轮先撤销本实现上次写入的临时字号、宽度、截断和省略状态,记录覆盖归属,只还原自身写入;从 max 或当前继承字号重新尝试。容纳则保留原字号,不能只缩不恢复。 2. 核对文本层有效宽度及收缩约束。Web 的 flex/grid 文本项检查 min-width: 0;使用浮点 DOMRect 读取真实分配宽度,结合父级扣除 border/padding 的内容宽度,取有效正值最小约束,不靠兄弟宽度反推。 3. 宽度为零时不缩字。帧级重试设置上限,之后等待真实尺寸或可见性变化。flex 文本项缩小后可能不随剩余空间增长,应观察父容器及相关兄弟的宽度变化;同宽更新不重复调度。 4. Web 单行用 Range.selectNodeContents 选取完整内容,再比较 DOMRect.width 与可用宽度。小容差只吸收取整误差,不能掩盖末字裁切。Canvas 仅可估算搜索起点,最终经真实 DOM 校验;不用 transform: scale 代替字号排版。 5. Web 多行先取消 line-clamp,再比较完整 scrollHeight 与计算行高乘以 lines;normal 无确定数值时用明确行高或经验证的回退。候选字号变化时同步核对行高,不错误缓存。混合字号、富文本和不同基线按实际行布局判断,测量后恢复截断。 6. 从最大字号逐级缩至 min,在 min 再次测量,仍溢出才省略。只有实测证明必要时才用二分,确保结果为可容纳的最大候选字号并进行 DOM 复测。 7. 省略优先使用本端原生能力,保留完整原文。Web 单行使用 white-space: nowrap、overflow: hidden、text-overflow: ellipsis;多行在同一文本层使用 display: -webkit-box、-webkit-box-orient: vertical、-webkit-line-clamp: N 与隐藏溢出,核对构建后声明仍在,不单独依赖无前缀 line-clamp,不额外叠加 text-overflow。 8. 分别检查截断、真实末行、可见末行、所需对齐和省略号位置。点击控件与截断层分工,自定义 slot/SVG 检查最终文字层;硬裁切或半个末字不算成功。行尾遵从文本方向。原生不足时先记录复现证据,再选择允许范围内的最小本端回退,不静默降低验收标准;独立尾部必须预留空间,确需裁剪字符串时按字素与实际排版处理。 ## 组织调度与动态刷新 - 使用框架无关测量内核、共享调度层和薄框架适配层;刷新 API 只提交任务,不暴露内部测量。 - 共享 Set 队列去重、一个 resize 监听与一个待执行 rAF;共享 ResizeObserver 只调度实际相关宽度变化的实例。合帧处理,密集更新按帧预算分批;循环外读取不随候选字号变化的约束。 - 先修正布局、减少无效实例、共享监听,再按实测优化缓存或搜索。缓存覆盖宽度、内容版本、选项、根字号和字体/样式失效标记,不只按文本缓存。 - 文本、选项、容器、视口、横竖屏、根字号、字体、样式、资源及显隐变化后重测;覆盖隐藏恢复和虚拟列表复用。按本端可观察事件刷新,不持续轮询未知变化。 - Web 的 ResizeObserver、document.fonts、fonts.ready/loadingdone 做特性检测;低版本采用 window.resize 回退,必要时提供显式刷新入口。过滤自身写入,避免观察器反馈循环。 - 卸载移除实例任务;最后实例退出时取消待执行帧,释放共享监听、字体事件和 Observer。保留完整可访问原文,内部测量辅助节点不重复暴露给辅助技术。 ## 验收与交付证据 - 验证空文本、短文本原字号、中等文本缩小完整显示、刚好容纳、超长文本在 min 省略;只有实际溢出才出现省略号。 - 覆盖支持的文字、混排、长串、标点、方向与字体回退;逐行检查数量、尾部避让和对齐,短文本不异常拉伸。 - 覆盖 flex/grid 窄宽、padding/border、小数像素及不同视口;变宽恢复字号,内容变短取消省略,根字号及字体加载后重算。 - 验证字号放大再还原、独立行高变化、初始零宽后显示、内容更新、复用与卸载;检查无残留任务、监听及可访问性退化。 - 在真实宿主、实际数据量与目标最低版本检查帧率、长任务、布局次数、抖动和回退。交付列明输入契约、实际验证的框架/引擎、系统版本、设备或模拟器、操作路径及结果;未验证范围与残留问题如实列出,不以类型检查、构建或单台设备成功代替跨端验收。 ``` ## 调用示例 **示例一**:请使用 auto-fit-text,处理卡片名称。单行展示,最大字号 16 CSS px,最小字号 12 CSS px,先缩字号,到下限仍放不下才省略。保留现有字体,容器变宽或名称变短后应恢复字号。先检查现有封装,再按真实页面验证。 **示例二**:请使用 auto-fit-text,修复表格单元格在隐藏后显示、字体加载及虚拟列表复用时字号不恢复的问题。沿用已有 min/max 和两行限制,不改变对齐与交互,检查共享调度和卸载清理,并给出目标 WebView 的实际验证结果。 |

