# 功能变更 ID: Feature-20260317-0001

> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。

## 基本信息

- ID: Feature-20260317-0001
- 标题: TextBox 文本溢出截断
- 状态：已完成（历史记录；本次仅归档，未重新验证）
- 类型：修改
- 级别：L2 中等
- 模块: TextBox
- 版本 / 分支: v3.0.1 / master
- 环境: Windows / Visual Studio 2022 / Debug、Release / EasyX
- 负责人: Ysm-04（历史实现）

## 变更背景

- 背景: TextBox 原先只限制存储字符数，文本像素宽度仍可能超过控件可绘制区域。
- 目标: 绘制时根据实际像素宽度生成带省略号的显示文本，避免文字覆盖相邻控件，同时保持内部原文不变。
- 不做什么：[可选]
  - 不修改 `getText()` / `setText()` 的签名。
  - 不截断或覆盖 TextBox 内部保存的原始文本。
  - 不新增持久缓存或第三方依赖。

## 变更内容

- 变更摘要: `TextBox::draw()` 将存储文本或密码掩码复制到临时 `displayText`，超出可用宽度时逐步缩短并追加 `...`。
- 新增项：[可选]
  - 绘制期临时变量 `displayText`。
  - 绘制期截断状态 `isTextTruncated`（历史实现中仅作为局部标记，未形成公共状态）。
- 修改项：[可选]
  - 使用 `width - 20` 作为保留左右边距后的可用宽度。
  - 普通模式和密码模式统一通过 `displayText` 计算尺寸并绘制。
- 删除 / 废弃项：[可选]
  - 无。
- 受影响的文件 / 类 / 函数:
  - 历史路径：`src/textBox.cpp`
  - `TextBox::draw()`
- 对外 API / 属性变化：[可选]
  - 无；显示行为增强，`getText()` 仍返回完整原文。

## 行为对照

- 变更前: 文本字符数未超过 `maxCharLen` 时仍可能因字体或内容宽度过大而绘制到 TextBox 边界之外。
- 变更后: 正常宽度条件下，绘制文本会缩短到可用区域并追加省略号，内部原文不受影响。
- 兼容性说明：兼容
- 迁移说明：[可选]
  - 无需迁移；调用方如需完整内容，继续使用 `getText()`。

## 验证与落地

- 验证方式:
  - 普通文本、空文本、长文本、大字号和密码模式下检查显示边界。
  - 调整控件宽度，检查截断与恢复后的显示。
  - 对照 `getText()`，确认内部原文没有被截断。
- 验证结果:
  - PDF 描述了目标、算法和测试方向，但“验证证据”仍是待填占位内容，没有附带截图、日志或自动化报告。
  - 历史源码确认普通路径采用逐字节 `pop_back()` 并重复调用 `textwidth()`；因此不能仅凭原记录认定中文等多字节文本一定不会被截在半个字符上。
  - 当 `availableWidth <= 0` 时，历史条件不会进入截断分支，极小控件宽度也不能认定为已经正确覆盖。
  - 循环最多删除 n 个字节，但每轮重新测量字符串宽度；若宽度计算与字符串长度相关，最坏时间成本可能接近 O(n²)，而不是原记录笼统声称的 O(n)。
  - 本次归档未重新构建 v3.0.1，也未运行 GUI 用例。
- 关联 BUG / Fix：[可选]
- Commit:
  - 实现提交：`c66cad3423a46ec4ef902965baa4c1816d10148a`
  - 发布记录提交：`b765e54eff28ebcd0bd99a81dec80b3ac0769337`
- PR：[可选]
- 发布版本：[可选] v3.0.1
- 备注：[可选]
  - 资料来源：`StellarX功能_模块变更.pdf` 第 3-9 页，并以对应提交和历史 `CHANGELOG.md` 交叉核对。