## 1.4.0（2026-08-18）

### Added

- **容器模式顶栏高度配置**：四端 `TencentQianWebViewConfig`（Android Kotlin / Java、iOS Swift / Objective-C `TQWebViewConfig`、HarmonyOS）新增可选字段 `topBarHeight`（Android `Int?` / Java `Integer`，单位 dp；iOS Swift `CGFloat?` / Objective-C `NSNumber *`，单位 pt；鸿蒙 `number | null`，单位 vp）。`null` 走各端默认高度（Android / 鸿蒙 48、iOS 44），显式传值时覆盖顶栏高度；仅容器模式生效（组件模式 / 配置模式顶栏由客户自绘，忽略此字段）

### Changed

- **Android（Kotlin / Java）全版本统一启用 Edge-to-Edge 布局**：容器模式内容区改为全屏绘制，状态栏 / 导航栏 / 挖孔区域由 SDK 基于 WindowInsets 自动避让（叠加到根布局 padding，底部取系统栏与键盘高度较大值），软键盘弹出时自动顶起内容、不再遮挡 H5 输入框，不再依赖系统自动 resize 与 XML `fitsSystemWindows`（Android 15+ 已强制忽略）；同时清零下发给 WebView 的系统栏 / 挖孔 inset，使 H5 页面 CSS `env(safe-area-inset-*)` 归零、避让自动失效，消除与 SDK 避让叠加产生的双重 padding（底部灰带）。容器模式自动生效、客户零改动；配置 / 组件模式由宿主持有布局，SDK 不主动修改（避免与宿主自身 E2E 处理叠加出双 padding），可按 Demo 示范调用 `applyEdgeToEdgeInsets` 一行接入同款避让，浅色界面建议同时配置 `windowLightStatusBar`
- **关闭确认弹窗按钮文案调整与自定义**：五端默认文案统一由「离开 / 继续」改为「仍要离开 / 留在本页」（结果导向，消除"继续离开还是继续流程""离开对话框还是离开页面"歧义）；按钮位置与点击语义不变，升级后未配置的客户将自动使用新文案。同时 `TencentQianWebViewConfig` / `TQWebViewConfig` 新增可选字段 `confirmLeaveText` / `confirmStayText`（默认空，空则使用新默认文案），承载非签署类 H5 流程时可自定义按钮文案，与既有 `confirmCloseTitle` / `confirmCloseMessage` 语义对齐；如需保留旧文案，可通过 `confirmLeaveText = "离开"` / `confirmStayText = "继续"` 显式还原。仅容器模式生效
- **三端容器模式顶栏返回/关闭图标统一为 `chevron_left` 形态**：Android 用 vector、鸿蒙用 SVG；iOS（Swift / Objective-C）由 SF Symbol（需 iOS 13+、视觉偏大）改为手写 `UIBezierPath` 内置矢量，复刻 Material Icons 24×24 路径，三端像素级对齐且兼容 iOS 11+；新增公开 `TencentQianWebViewIcon` / `TQWebViewIcon`，容器模式与组件模式 Demo 共用，消除 `#available` 分支与文字 fallback

### Fixed
- **Android（Kotlin / Java）修复 Android 5（API 21-22）状态栏文字不可见**：深色状态栏文字（`StatusBarStyle.DARK_CONTENT`，默认）为 Android 6.0（API 23）新增能力，Android 5 系统状态栏文字恒为白色，落在默认浅色背景上不可见；修复后 Android 5 上自动为状态栏叠加半透明深色底衬，保证文字可读。`LIGHT_CONTENT`（白色文字）为 Android 5 系统原生行为，不受影响；容器模式自动生效、客户零改动

## 1.3.0（2026-08-11）

### Added

- **Android（Kotlin / Java）组件模式（嵌入形态）**：新增 `TencentQianWebViewComponent`（自定义 View + DSL 工厂），宿主在自定义布局中嵌入完整配置的签署 WebView，镜像鸿蒙嵌入模式，补齐第三种集成形态（容器模式 / 组件模式 / 配置模式）：
  - DSL 参数：`url` / `config` / `onSignResult` / `onSdkEvent` / `onTitleChanged` / `onProgressChanged` / `onRenderUnrecoverable` / `controller` / `reusePrewarmPool`
  - 感知回调：`onTitleChanged`（标题 + 可后退快照，供自绘顶栏）/ `onProgressChanged`（进度 + 可见性门控，SPA 软路由不误显示）/ `onRenderUnrecoverable`（渲染崩溃终态，供自绘错误页 + 重试）
  - 控制能力：新增 `TencentQianWebViewController`，宿主可主动 `canGoBack()` / `goBack()` / `handleBack()`（逐级后退 H5 历史，覆盖 SPA 软路由）/ `reload()`（配合不可恢复回调做「重试」）
  - `TencentQianWebViewConfigurator.apply()` 末尾追加可选参数 `onTitleChanged`（`@JvmOverloads`，默认 `null`）；其余参数（含 `progressListener`）不变，现有调用零改动
  - ActivityResult 依赖新增基于 `ActivityResultRegistry` 的注册路径（`RuntimePermissionRequester` / `FileChooserLauncher`），组件可在 View 创建后（Activity 已过 `onCreate`）随时初始化，绕开 `registerForActivityResult` 的「onCreate 前注册」约束；原 `register(activity)` / `register(fragment)` 路径保留
  - 渲染进程崩溃恢复逻辑从容器 Activity 抽取为 internal 共享状态机（计数 / 30s 冷却窗口 / 上限 3 / 门控清零），容器与组件共用同一实现；组件模式在放弃恢复时触发 `onRenderUnrecoverable`
  - 组件默认自建自管（`reusePrewarmPool` 默认 `false`）：生命周期由宿主 UI 树掌控（视图移除 ≠ 签署结束），`onDetachedFromWindow` 仅暂停渲染，显式 `release()` 才归还池 / 销毁 WebView 并复位命令对象
  - **Android（Java）**：`android-java` 模块 1:1 对齐（`TencentQianWebViewComponent.Builder` 链式 setter + `@FunctionalInterface` 回调 + `apply()` 重载追加 `OnTitleChanged` 末参），参数面 / 回调时序 / 崩溃恢复与终态重试语义与 Kotlin 版完全一致，全部公开 API 保持 Java 8 / minSdk 21 可调用

- **iOS（Swift / Objective-C）组件模式（嵌入形态）**：新增 `TencentQianWebViewComponent`（`UIView` 子类），宿主在自定义布局中嵌入完整配置的签署 WebView，与 Android / HarmonyOS 组件模式对齐，iOS 补齐第三种集成形态（容器模式 / 组件模式 / 配置模式）：
  - 参数面：`url` / `config` / `hostController`（可选，缺省 responder chain 解析）/ `onSignResult` / `onSdkEvent` / `onTitleChanged` / `onProgressChanged` / `onRenderUnrecoverable` / `controller`；**无 `reusePrewarmPool`**（iOS 预热池实例永不复用到页面，与容器模式一致）
  - 感知回调：`onTitleChanged`（`pageFinished` 标题 + 可后退快照，SPA 软路由不刷新）、`onProgressChanged`（0~100 + 可见性门控）、`onRenderUnrecoverable`（连续崩溃终态，供宿主自绘错误页 + 重试）
  - 控制能力：嵌套命令对象 `TencentQianWebViewComponent.Controller`（`TencentQianWebViewController` 已被容器模式占用），`canGoBack()` / `goBack()` / `handleBack()` / `reload()` 语义与 Android / HarmonyOS 一致
  - 崩溃恢复复用容器模式内核：iOS WebContent 进程被杀后 WKWebView 实例仍有效，原地 `load(URLRequest)` 恢复（与鸿蒙同语义，非 Android 销毁重建）；超限放弃时触发 `onRenderUnrecoverable`
  - `TencentQianWebViewConfigurator.Handle` 新增可写属性 `onRenderUnrecoverable`（默认 `nil`），`apply()` 签名不变，现有调用零改动
  - `release()` 显式收口（幂等）：解绑 delegate + 销毁 WebView + 命令对象复位 no-op
  - Demo 新增组件模式示例页（自绘顶栏 / 进度条 / 错误覆盖层重试）
  - **iOS（Objective-C）**：`ios-objective-c` 模块 1:1 对齐（`TQWebViewComponent` + block typedef 回调（`TQUiCallbacks.h`）+ 独立 `TQWebViewComponentController`；显式收口命名 `invalidate`，同 `NSTimer.invalidate`；`TQWebViewHandle` 同步新增可写属性 `onRenderUnrecoverable`），`Demo/` 与 `DemoSwift/` 均含组件模式示例页

### Changed

- **客户回调异常隔离（Android Kotlin / Java、HarmonyOS、iOS-OC）**：客户回调（`onSignResult` / `onSdkEvent` / `onTitleChanged` / `onProgressChanged` / `onRenderUnrecoverable` 等）实现抛出未捕获异常时，SDK 仅记 warning 日志并继续运行，不再穿透崩溃整个进程；容器模式收尾不受影响（客户 `onSignResult` 抛异常时容器照常关闭，协议结果不丢）。**iOS-Swift 例外**：Swift 运行时错误为 runtime trap，语言层面无法被 SDK 捕获，请保证回调实现自身健壮。纯防御性增强，API 与派发语义零变化

### Fixed

- **iOS（Swift / Objective-C）URL 入口校验**：修复无 scheme 输入（如 `www.qq.com`）裸 `URL(string:)` 判 nil 漏过（得到相对 URL）、加载后 WebKit 报 `WebKitErrorDomain 101 (Cannot show URL)` 的问题。新增 SDK 内部统一校验（http/https scheme + 非空 host 确定性判定，不依赖 `URL(string:)` 的版本解析差异；OC 版为 `TQSignURLValidator`），非法 URL 加载前即拦截并通过 `onSdkEvent` 上报 `loadError`（`errorCode = NSURLErrorBadURL`）；容器模式由「静默 dismiss」改为「先上报再 dismiss」，宿主可感知
- **iOS（Swift / Objective-C）detach 后误加载**：修复 `detach` / `detachAndDestroy` 后内核 delegate 仍被强持、常驻 `didBecomeActive` 监听残留，App 下次激活时白屏自检可能向已解绑 / 已销毁的 WebView 重新发起旧签署 URL 加载的问题；detach 现在先对内核 delegate 做幂等失效（移除监听 / 取消网络监测 / 解绑白屏自检）
- **iOS（Swift / Objective-C）容器模式崩溃终态永久白屏**：修复渲染进程连续崩溃超限、SDK 放弃自动恢复后容器既不关页也不提示、用户停留永久白屏的问题；容器现在经 `Handle.onRenderUnrecoverable` 接终态回调自动关页，对齐 Android 容器超限 `finish()` / 鸿蒙容器 `doClose()` 语义（终态前的每次崩溃事件 `webContentProcessTerminated` 仍照常上报，宿主埋点不受影响）
- **鸿蒙 `onTitleChanged` 标题归一化**：SDK 将「空 / 等于当前页 URL / 为去 scheme 的当前页 URL 且落在 path 边界」的标题统一归一化为空串（与 Android `normalizePageTitle` 规则镜像一致），Page 模式顶栏 / 组件模式 `onTitleChanged` 统一受益，宿主 `title.length > 0 ? title : 默认标题` 即可稳定兜底；纯空白标题原样透传，由宿主决定是否兜底；真实标题恰为域名前缀不再被误判为无标题

### Security

- **iOS（Swift / Objective-C）下载 Cookie 同步过滤**：非 https 下载链接不再携带 `Secure` 标记的 Cookie（对齐浏览器行为），消除 http 下载时安全 Cookie 被明文发出的风险

## 1.2.0（2026-07-31）

### Added

- **WebView 预热能力（五端统一）**：新增 `TencentQianWebViewPrewarmer`（OC 版 `TQWebViewPrewarmer`）统一入口，纯新增、不改任何已放开 API。两个正交维度——**网络预热**（省网络加载时间）+ **WebView 复用池**（省实例创建 100–300ms）。
  - 意图三档 `PrewarmLevel { MINIMAL, LIGHT, HEAVY }`：MINIMAL = 纯 DNS 预解析（无需 bizType）；LIGHT = 内核/进程首次初始化（鸿蒙 `initializeWebEngine` + `prepareForPageLoad`、Android/iOS 离屏预建空实例）；HEAVY = 池实例加载 `warmup.html` 网络热身。SDK 内部按档位叠加补做低档动作，单调去重不允许降级重热。
  - 多环境 `PrewarmEnvironment { PROD, BETA }`（默认 PROD）+ `manifestUrl` 覆盖；在线 `warmup-manifest.json` 为唯一数据源。
  - manifest `configure` 后台拉 + `prewarm` 懒兜底 + stale-while-revalidate，TTL 读自响应头 `Cache-Control: max-age`（默认 300s）；manifest `version` 变化整体重置去重状态。
  - WebView 复用池：容器模式 `open()` 透明复用预热态实例。Android + 鸿蒙 = 跨流程借还池（归还 `about:blank` + `clearHistory` 不销毁，客户主动 `release`/`releaseAll` 释放）；iOS = 单流程一次性（无 `clearHistory`，关闭销毁，靠共享 `WKProcessPool` + `.default()` DataStore 复用）。池容量固定为 1。
  - `open(url)` 环境错配检测（仅 3 个已知 `quick.*` 环境搭错才告警，非 quick 域名不告警，不阻断）。
  - `getMenuBizTypes(callback)`（五端对齐）：异步返回 manifest 可用于菜单展示的业务列表，manifest 新增可选 `menuBizTypes` 字段（精选子集，缺省回退全量 `bizTypes` keys）。
  - `PrewarmConfig` 新增 `preferredLanguage`（语言偏好；L4 拼 `&lang=` 委托 warmup.html、L3 按 `i18nAutoDetect` 门控）、`injectUserAgent` + `userAgentExtra`（池实例按 UA 创建，复用门控改为预热 UA == open config UA）。
  - 鸿蒙 `TencentQianWebViewComponent`（嵌入模式）新增 `reusePrewarmPool` 开关（默认 false），开启后复用预热池。
  - 平台能力：HarmonyOS = L1 DNS + L2 预连接 + HEAVY NodeContainer 离屏池；Android = L1 + 借还池 + L4(`warmup.html`)；iOS = L1 + 一次性池 + L4（共享 `.default()` DataStore 磁盘缓存跨实例复用）。
  - 全程 best-effort：任何预热失败静默降级，绝不阻塞 / 影响 `open()` 主流程；容器模式池复用对客户透明。
- **鸿蒙嵌入模式（`TencentQianWebViewComponent`）宿主联动能力补齐**：此前嵌入模式仅暴露 `onSignResult` / `onSdkEvent`，宿主自绘顶栏 / 进度条 / 错误处理时缺少必要的联动与控制手段（Page 模式已内置）。本次对齐补齐两类能力，全部可选、向后兼容：
  - 感知回调：新增 `onTitleChanged`（H5 标题 + 可后退快照，供自绘顶栏）、`onProgressChanged`（加载进度，供自绘进度条）、`onRenderUnrecoverable`（渲染进程连续崩溃且 SDK 放弃自动恢复的终态，供显示错误页 / 返回 / 重试；与 `RenderProcessGoneEvent` 的「每次崩溃」语义互补）。
  - 控制能力：新增 `TencentQianWebViewController`（供 `TencentQianWebViewComponent` 使用），宿主可主动 `canGoBack()` / `goBack()` / `handleBack()`（逐级后退 H5 历史，覆盖 SPA 软路由）/ `reload()`（配合不可恢复回调做「重试」），修正此前宿主返回按钮只能直接退出、绕过 H5 多级历史的问题。
- **渲染进程崩溃恢复（三端对齐）**：池实例在预热/借出/归还三态的渲染进程崩溃回调均正确善后。Android 走"销毁 + 新建"（崩溃实例永久失效，精准回退崩溃前页面）；iOS / 鸿蒙走"原地重载"（实例仍有效：iOS `load(URLRequest(lastProvisionalURL))`、鸿蒙 `loadUrl` 优先 `refresh` 兜底）；重试上限 3 + 冷却窗口 30s + 延迟恢复（防必崩页面死循环 / 二次崩溃）；鸿蒙借出态崩溃"脱池不销毁活节点"原地恢复。对客户透明，不新增公开 API。

### Changed

- **Android 最低系统要求降至 Android 5.0（API 21）**：`minSdk` 从 24 降至 21，Java 编译目标降至 1.8（`sourceCompatibility`/`targetCompatibility = 1.8`，Kotlin `jvmTarget = 1.8`）。SDK 源码改用 `androidx.core.util.Consumer`/`Supplier` 替代 `java.util.function.*`，`"UTF-8"` 字符串替代 `StandardCharsets`，不引入 core library desugaring，AAR / 源码集成客户无需额外配置。JDK 17 仍为构建工具链，源码不使用任何 JDK 9+ 语法或标准库 API，兼容客户的 Java 8 编译目标
- **iOS 最低部署目标降至 iOS 11.0**：Deployment Target 从 14.3 降至 11.0。SDK 对 iOS 13+/14+ API（`WKWebpagePreferences`、`os.Logger`、UIColor 系统颜色、SF Symbols、`UIStatusBarStyle.darkContent`、`HTTPURLResponse.value(forHTTPHeaderField:)`）增加 `#available`/`@available` 版本分支与兼容层，iOS 11-12 降级为旧 API / 静态颜色 / 文字符号（返回 `‹`、关闭 `✕`）/ `NSLog`。`safeAreaLayoutGuide` 与 `httpCookieStore` 恰为 iOS 11，无需改动
- **WebRTC / getUserMedia 系统门槛不变**：仍需 Android 7.0+（API 24）/ iOS 14.3+，由系统 WebView 内核决定。低版本系统（Android 5.0~6.x / iOS 11~14.2）走 `<input type="file" capture>` 系统相机录制/拍照上传路径，本次改造确保该路径在 minSdk 21 / iOS 11 正常工作

### Fixed

- 修复 iOS 渲染进程崩溃恢复白屏隐患：容器 `webViewWebContentProcessDidTerminate` 从 `reload()` 改为以保存的 `lastProvisionalURL` 原地 `load(URLRequest)` 恢复（进程被杀后 `webView.url` 常为 nil，`reload()` 变 no-op 导致持久白屏）
- 修复 iOS（Swift + OC）下载文件名路径穿越：新增 `sanitizedFilename` 归一化文件名，防服务器返回含 `../` 或 `/` 的恶意文件名写入任意目录
- 修复鸿蒙下载文件名路径穿越：`DownloadHandler` 文件名 sanitize 加固，防 `../` 路径穿越写入任意目录

## 1.1.0（2026-07-17）

### Added

- iOS SPM（Swift Package Manager）本地源码包集成支持：新增 `ios-swift/Package.swift`（`TencentQianWebViewSDK` module）与 `ios-objective-c/Package.swift`（`TencentQianWebView` module），Swift / Objective-C 客户均可通过 Xcode「File → Add Packages → Add Local…」一键引入源码集成，Xcode 自动编译、自动处理架构、保留模块边界
- iOS xcframework 二进制分发：`scripts/build-ios-swift.sh` 与 `scripts/build-ios-objectivec.sh` 新增 `xcframework` 子命令，合成含 `ios-arm64` + `ios-arm64_x86_64-simulator` 双 slice 的 `.xcframework`，解决 Apple Silicon Mac 模拟器 arm64 架构冲突（传统 fat framework 在 Apple Silicon 上直接编译报错的硬伤）
- iOS SPM + xcframework 集成验证脚本 `scripts/verify-ios-integration.sh`：覆盖 SPM Add Local / xcframework 两种集成方式 × Swift 版 + OC 版 × simulator + device 的全量验证矩阵，全程无需开发者证书
- iOS Objective-C 工程：新增 `DemoSwift` target，作为纯 Swift 应用通过 framework module 消费 OC 版 `TencentQianWebView` 的集成范本，适用于 Swift 主语言存量客户接入 OC 版 SDK

### Changed

- 更新 Android 端混淆规则说明
- 收拢 ios-objective-c 公共头文件到 `Public/` 目录，使 SPM 单 `publicHeadersPath` 约束可满足，并简化 `project.yml` 头文件可见性配置
- 更新 iOS 集成文档（usage-guide / integration-checklist / troubleshooting）：明确集成方式优先级（SPM 源码包 > xcframework 二进制 > 源文件直拖），补充 Apple Silicon arm64 冲突排错
- 更新 qianuni UniApp web-view 接入指南
- UA 版本号固定在源码中，方便多种集成方式使用

## 1.0.5（2026-06-25）

### Changed

- 文档补齐 HarmonyOS 接入自检清单、协议常量、排错决策树与三端下载行为对照，同步修正 iOS 权限文案与 HarmonyOS module.json5 权限配置

## 1.0.4（2026-06-18）

### Fixed

- Android 与 鸿蒙 SPA 路由切换导致进度条误显示且无法关闭

## 1.0.3（2026-06-12）

### Fixed

- 鸿蒙端手动关闭容器不回调 EMPTY，与其他端对齐

## 1.0.2（2026-06-12）

### Fixed

- 修复 SignResult.EMPTY 共享 Map 污染、关闭流程双回调、Component 网络监听泄漏，并补齐外部 scheme 失败上报与下载文件名路径穿越防御


## 1.0.1（2026-06-12）

### Changed

- 优化版本号管理

## 1.0.0（2026-06-11）

### Added

- Android Kotlin SDK：容器模式 `TencentQianWebView.open` 与配置模式 `TencentQianWebViewConfigurator.apply`
- Android Java SDK：与 Kotlin 版功能与 API 对等的纯 Java 实现（`Builder` 模式 Config、`abstract class` + `static final` 子类替代 sealed class），适用于不引入 Kotlin 运行时的存量工程
- iOS Swift SDK：容器模式 `TencentQianWebView.open` 与配置模式 `TencentQianWebViewConfigurator.apply`
- iOS Objective-C SDK：与 Swift 版 1:1 对齐的纯 OC 实现（ARC），适用于 100% Objective-C 代码库存量客户
- HarmonyOS ArkTS SDK：基于 ArkWeb 的容器模式 `TencentQianWebView.open` 与配置模式 `TencentQianWebViewConfigurator.apply`
- `qianapp://` 协议解析：跨端一致的 `SignResult` 结构（`action` / `result` / `flowId` / `from` / `extras`）
- 三端 UA 注入 `qianwv/<version>` 标识，便于 H5 侧识别 SDK 容器
- 文件下载兼容（Android `DownloadListener`、iOS `URLSession + 分享 sheet`、HarmonyOS `request.downloadFile + DocumentViewPicker`）
- 文件选择器、JS 弹窗、`getUserMedia` 权限链路、SSL 错误处理、渲染进程崩溃恢复等三端兼容性适配
- 接入指南、`qianapp://` 协议规范、自检清单、排错决策树 + 常见问题
