PTools 5.62.1 — TabBar 与渐变迁移说明

本版本面向 iOS 17+ / Swift 6+，把 TabBar 的安全区、选中背景和 Item 内容布局拆成独立职责，同时修复 UILabel / UIImageView 使用 backgroundGradient 时文字或图片被渐变子 Layer 遮挡的问题。

5.62.2 修正 / Correction / Corrección

中文：5.62.1 中 tabItemContentInsets 的“外围容器 Padding”描述已废止。自 5.62.2 起，它直接调整 Tab Item 的 content.view 实际尺寸；正值缩小内容，负值扩展内容，标题仍独立布局。

English: The 5.62.1 description of tabItemContentInsets as outer-container padding is superseded. Starting with 5.62.2, it changes the actual content.view size; positive values shrink content, negative values expand it, and the title remains independently laid out.

Español: Se reemplaza la descripción de 5.62.1 que trataba tabItemContentInsets como padding del contenedor exterior. Desde 5.62.2 modifica el tamaño real de content.view; los valores positivos reducen el contenido, los negativos lo amplían y el título conserva su layout independiente.

1. TabBar 配置拆分

中文

旧项目仍可继续使用 tabTopSpacing、tabBottomSpacing 和 tab26BottomSpacing。它们分别属于旧的 Item Slot / TabBar 容器 / 安全区布局语义，不建议再用来微调选中背景或 Icon 的视觉位置。

PTAppBaseConfig.share.tabSelectedMetail = true
PTAppBaseConfig.share.tabSelectedMetailInsets = UIEdgeInsets(
    top: 10,
    left: 6,
    bottom: 10,
    right: 6
)
PTAppBaseConfig.share.tabItemContentInsets = .zero
PTAppBaseConfig.share.tabItemContentOffset = .zero

tabSelectedMetailInsets 只改变选中背景的视觉 Frame，不参与 Icon / Title 尺寸计算。
tabItemContentInsets 直接调整 Icon / Lottie / 自定义内容 content.view 的实际尺寸；正值缩小，负值扩展，标题不参与该计算。
tabItemContentOffset 只平移 Icon + Title，不改变尺寸；例如向上 2pt 使用 UIOffset(horizontal: 0, vertical: -2)。
tabSelectedMetailLRSpacing 仍可编译和工作，但已弃用，迁移到 tabSelectedMetailInsets.left/right。

English

tabSelectedMetailInsets, tabItemContentInsets, and tabItemContentOffset have separate contracts. Selection insets never resize the icon or title. Starting with 5.62.2, content insets resize the actual media/custom content.view while leaving the title independent. Content offset translates the complete icon-and-title group without resizing it. The old tabSelectedMetailLRSpacing property remains as a deprecated compatibility alias.

Español

tabSelectedMetailInsets, tabItemContentInsets y tabItemContentOffset tienen contratos independientes. Los insets de selección nunca cambian el tamaño del icono o del título. Desde 5.62.2, los insets de contenido redimensionan el content.view multimedia/personalizado y dejan el título independiente. El offset de contenido traslada el grupo completo de icono y título sin redimensionarlo. La propiedad antigua tabSelectedMetailLRSpacing se conserva como alias compatible y obsoleto.

2. Per-item override

当不同图标或 Lottie 素材需要单独校正时，可以在 PTTabBarItemConfig 中覆写全局配置：

let config = PTTabBarItemConfig(
    title: "Home",
    content: imageContent,
    viewController: homeViewController,
    contentInsets: UIEdgeInsets(top: 2, left: 0, bottom: 0, right: 0),
    contentOffset: UIOffset(horizontal: 0, vertical: -1)
)

项目级配置优先于 PTAppBaseConfig 的全局配置；未提供覆写时使用当前 PTTabBarAppearance 快照。

3. Runtime 与兼容边界

外观在 TabBar 初始化时捕获为快照。初始化完成后直接修改 PTAppBaseConfig.share 不会偷偷改变旧实例；需要更新已有 TabBar 时，应通过现有的配置重建或明确外观应用入口完成。tab26BottomSpacing 继续只负责容器 / Safe Area，不应用到 Center Raised Button，也不作为 Item 内容 Offset。

4. 渐变背景修复

UILabel 和 UIImageView 的 backgroundGradient 现在基于当前 Bounds 生成 UIImage，再设置为 UIColor(patternImage:)。这样文本和图片仍由 UIKit 的 backing contents 在渐变之上绘制。

普通 UIView、UIButton 和自定义容器继续使用 PTSuperBg CAGradientLayer；渐变边框仍使用独立的 PTSuperBorder Layer。Bounds、动态颜色、圆角、胶囊和 Cell reuse 会重新应用或清理对应的背景。

label.backgroundGradient(
    type: .LeftToRight,
    colors: [.systemBlue, .systemPurple],
    radius: 12
)

imageView.backgroundGradient(
    type: .TopToBottom,
    colors: [.systemOrange, .systemRed],
    radius: 20
)

5. Demo 与验证

Example Demo Catalog 新增并更新：

TabBar Item Insets：Legacy、Selection-only、Content +、Content −、Vertical、Horizontal、Offset、 Combined、Per-item、Badge、Mini、Lottie，并直接显示 content.view 实际尺寸。
Gradient Rendering：Label / ImageView 内容型背景与普通容器 Layer 路径。

本地可执行源码解析、Package manifest、静态质量扫描和 git diff --check。完整 Xcode Simulator 构建必须在 Harbeth 所需的 Metal Toolchain 可用后复跑；当前环境缺失该外部工具链，不能将构建阻断伪装为源码通过。