tmui-cli 5.3.1 → 5.3.3

package/data/uni-app-x-docs/api/bluetooth-le-central.md

@@ -0,0 +1,376 @@
+::: warning 注意事项
+
+使用前，需先按[蓝牙-通用](./bluetooth-general.md)中的流程初始化适配器并发现目标设备。建立连接后，先发现服务和特征值，再进行读写或开启通知；断开连接后需重新连接并重新发现服务与特征值。
+
+:::
+
+## 模块介绍
+
+蓝牙低功耗（BLE）中心设备相关接口，用于与蓝牙设备建立连接、发现其服务与特征值，并对特征值进行读写、订阅通知等操作。
+
+- **服务**：设备对外提供的一组功能，由 UUID 标识，可包含一个或多个特征值；
+- **特征值**：服务下的数据点，由 UUID 标识，其 `properties` 描述支持的操作，如 read、write、notify、indicate 等；
+- **UUID**：用于标识服务和特征值。调用接口时，使用 uni.getBLEDeviceServices 和 uni.getBLEDeviceCharacteristics 返回的 UUID。
+
+本文负责连接与数据通信，[蓝牙-通用](./bluetooth-general.md)负责适配器管理与设备发现。各接口及参数的支持范围以对应的兼容性表为准。
+
+## 使用流程
+
+<a href="../static/bluetooth-le-central-flow.svg" target="_blank" rel="noopener"><img src="../static/bluetooth-le-central-flow.svg" alt="BLE 中心设备流程：连接设备、发现服务和特征值、按属性收发数据并清理连接" width="400"></a>
+
+1. 注册 [uni.onBLEConnectionStateChange](#onbleconnectionstatechange) 和 [uni.onBLECharacteristicValueChange](#onblecharacteristicvaluechange)，分别接收连接状态变化和特征值数据。
+2. 使用扫描返回的 `deviceId`，调用 [uni.createBLEConnection](#createbleconnection) 连接目标设备。
+3. 连接成功后，调用 [uni.getBLEDeviceServices](#getbledeviceservices) 发现服务，再调用 [uni.getBLEDeviceCharacteristics](#getbledevicecharacteristics) 获取目标服务的特征值及其属性。
+4. 按特征值属性调用 [uni.readBLECharacteristicValue](#readblecharacteristicvalue) 或 [uni.writeBLECharacteristicValue](#writeblecharacteristicvalue)。调用 `readBLECharacteristicValue` 前需先注册 `onBLECharacteristicValueChange`，读取结果通过该事件的 `value` 返回；读取不要求先开启通知。
+5. 如需接收外设主动发送的数据，调用 [uni.notifyBLECharacteristicValueChange](#notifyblecharacteristicvaluechange) 开启通知，通过已注册的特征值变化事件监听接收数据。
+6. 按需调用 [uni.getBLEDeviceRSSI](#getbledevicerssi) 获取信号强度；iOS 写入长度与 MTU 的说明见 [uni.getBLEMTU](#getblemtu) 和 [uni.setBLEMTU](#setblemtu)。
+7. 不再需要通知时将其关闭；通信结束后调用 [uni.closeBLEConnection](#closebleconnection)，并移除当前页面或组件注册的事件监听。
+
+## 权限@permission
+
+蓝牙权限与[蓝牙-通用](./bluetooth-general.md#permission)一致，请先按该页完成各端权限配置。
+
+## 注意事项@tips
+
+### 通用
+
+- **以特征值属性为准**：读、写和通知分别要求特征值支持对应的操作；支持读取不代表支持通知或写入。
+- **重新连接后重新发现**：断线重连后，应重新获取服务与特征值，并按需开启通知，不要直接沿用上次连接的结果。
+- **区分通知与事件监听**：关闭外设通知需调用 `notifyBLECharacteristicValueChange` 并传入 `state: false`；`offBLECharacteristicValueChange` 只移除事件监听，不能代替关闭通知。
+- **按监听所属范围清理**：不再使用时移除自身注册的特征值和连接状态监听。当前 iOS 插件可保存 `on*` 返回的监听 ID，并将该 ID 传给对应的 `off*`，避免清空其他页面的监听。
+- **控制写入长度与时序**：单次写入长度由平台和当前连接决定，超长数据需由业务分包；同一连接上的读写与通知配置操作宜按完成回调依次执行。
+
+
+<!-- UTSAPIJSON.createBLEConnection.name -->
+
+<!-- UTSAPIJSON.createBLEConnection.description -->
+
+<!-- UTSAPIJSON.createBLEConnection.compatibility -->
+
+<!-- UTSAPIJSON.createBLEConnection.param -->
+
+<!-- UTSAPIJSON.createBLEConnection.fileFormats -->
+
+<!-- UTSAPIJSON.createBLEConnection.returnValue -->
+
+<!-- UTSAPIJSON.createBLEConnection.example -->
+
+<!-- UTSAPIJSON.createBLEConnection.tutorial -->
+
+### iOS 使用说明
+
+- 先初始化适配器并扫描到目标设备，再传入扫描返回的 `deviceId`。能扫描到设备只表示收到了广播，不保证外设当前接受连接。
+- 先注册 `onBLEConnectionStateChange`，再发起连接。同一设备不要并行调用多次 `createBLEConnection`，避免重复连接导致失败。
+- 在 `success` 回调后调用 `getBLEDeviceServices` 和 `getBLEDeviceCharacteristics`，再开始读写或开启通知。连接成功不代表服务发现、特征值发现或业务认证已完成。
+- `timeout` 的单位是毫秒，应设置为大于 0 的数值，并结合真机耗时确定。当前 iOS 插件不传时不设置连接超时期限，但仍可能因系统报告失败或适配器状态变化而结束。
+- 当前 iOS 插件对已经连接的设备再次调用连接会返回成功。
+
+### iOS 连接失败与超时排查 @ios-connection-troubleshooting
+
+`createBLEConnection` 失败时，先确认适配器已初始化且可用，并使用扫描返回的 `deviceId`。连接成功后的服务发现、读写和通知问题，应按对应接口排查。
+
+连接超时表示未在指定时间内完成连接，不代表设备已关机或停止广播；等待上一次断开完成也可能超时。能扫描到设备，不代表设备当前接受连接。
+
+可按以下方向排查：
+
+| 可能原因 | 检查与处理方式 |
+| --- | --- |
+| 信号弱或干扰 | 靠近外设，在干扰较少的环境中重试。 |
+| 外设被占用或不可连接 | 断开其他手机、App 或调试工具的连接，确认外设处于可连接模式。 |
+| 重复连接或断开未完成 | 同一设备只保留一个连接流程，避免并行连接或立即反复重连。 |
+| 超时时间过短 | 结合正常连接耗时，适当增加 `timeout` 后对比。 |
+| 外设重启或配对信息变化 | 重新扫描；若提示配对异常，按设备说明重新配对。持续失败时检查外设日志。 |
+| 连接过多或系统暂不可用 | 关闭不必要的连接和扫描，通过 `onBluetoothAdapterStateChange` 确认可用后再试。 |
+
+重试应设置间隔和次数上限，持续失败时提示用户检查设备。重连成功后，需重新发现服务和特征值，并按需开启通知。仍无法定位时，可按[调试建议](#调试建议)使用蓝牙工具对照验证。
+
+
+<!-- UTSAPIJSON.closeBLEConnection.name -->
+
+<!-- UTSAPIJSON.closeBLEConnection.description -->
+
+<!-- UTSAPIJSON.closeBLEConnection.compatibility -->
+
+<!-- UTSAPIJSON.closeBLEConnection.param -->
+
+<!-- UTSAPIJSON.closeBLEConnection.fileFormats -->
+
+<!-- UTSAPIJSON.closeBLEConnection.returnValue -->
+
+<!-- UTSAPIJSON.closeBLEConnection.example -->
+
+<!-- UTSAPIJSON.closeBLEConnection.tutorial -->
+
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.name -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.description -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.compatibility -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.param -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.fileFormats -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.returnValue -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.example -->
+
+<!-- UTSAPIJSON.onBLEConnectionStateChange.tutorial -->
+
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.name -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.description -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.compatibility -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.param -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.fileFormats -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.returnValue -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.example -->
+
+<!-- UTSAPIJSON.offBLEConnectionStateChange.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.name -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.description -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.compatibility -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.param -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.returnValue -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.example -->
+
+<!-- UTSAPIJSON.getBLEDeviceRSSI.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEMTU.name -->
+
+<!-- UTSAPIJSON.getBLEMTU.description -->
+
+<!-- UTSAPIJSON.getBLEMTU.compatibility -->
+
+<!-- UTSAPIJSON.getBLEMTU.param -->
+
+<!-- UTSAPIJSON.getBLEMTU.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEMTU.returnValue -->
+
+<!-- UTSAPIJSON.getBLEMTU.example -->
+
+<!-- UTSAPIJSON.getBLEMTU.tutorial -->
+
+### iOS 注意事项
+
+- 当前 iOS 插件返回的 `mtu` 是指定 `writeType` 对应的最大可写数据长度，单位为字节，不是 ATT MTU；不传 `writeType` 时按 `write` 查询。
+- 直接以返回值作为该写模式的单次写入长度上限，无需再减 3，也不能通过加 3 推算 ATT MTU。查询时的 `writeType` 应与实际写入时一致。
+- 返回的长度上限不代表外设业务协议支持任意长度的数据，分包还需遵循设备协议。
+
+
+<!-- UTSAPIJSON.setBLEMTU.name -->
+
+<!-- UTSAPIJSON.setBLEMTU.description -->
+
+<!-- UTSAPIJSON.setBLEMTU.compatibility -->
+
+<!-- UTSAPIJSON.setBLEMTU.param -->
+
+<!-- UTSAPIJSON.setBLEMTU.fileFormats -->
+
+<!-- UTSAPIJSON.setBLEMTU.returnValue -->
+
+<!-- UTSAPIJSON.setBLEMTU.example -->
+
+<!-- UTSAPIJSON.setBLEMTU.tutorial -->
+
+### iOS 注意事项
+
+iOS 不支持主动设置 MTU，当前插件调用此接口会执行 `fail` 和 `complete`，返回不支持错误。写入前可通过 `getBLEMTU` 查询对应写模式的最大可写长度。
+
+
+<!-- UTSAPIJSON.onBLEMTUChange.name -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.description -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.compatibility -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.param -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.fileFormats -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.returnValue -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.example -->
+
+<!-- UTSAPIJSON.onBLEMTUChange.tutorial -->
+
+
+<!-- UTSAPIJSON.offBLEMTUChange.name -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.description -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.compatibility -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.param -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.fileFormats -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.returnValue -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.example -->
+
+<!-- UTSAPIJSON.offBLEMTUChange.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEDeviceServices.name -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.description -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.compatibility -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.param -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.returnValue -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.example -->
+
+<!-- UTSAPIJSON.getBLEDeviceServices.tutorial -->
+
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.name -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.description -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.compatibility -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.param -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.fileFormats -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.returnValue -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.example -->
+
+<!-- UTSAPIJSON.getBLEDeviceCharacteristics.tutorial -->
+
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.name -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.description -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.compatibility -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.param -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.fileFormats -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.returnValue -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.example -->
+
+<!-- UTSAPIJSON.readBLECharacteristicValue.tutorial -->
+
+### 注意事项
+
+- 先注册 `onBLECharacteristicValueChange`，再发起读取。读取结果通过该事件的 `value` 返回，`readBLECharacteristicValue` 的成功回调不包含特征值数据。
+- 主动读取要求特征值支持 `read`，无需先调用 `notifyBLECharacteristicValueChange` 开启通知。
+- 多设备或多特征值共用事件监听时，应按事件中的 `deviceId`、`serviceId` 和 `characteristicId` 匹配数据来源。
+
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.name -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.description -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.compatibility -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.param -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.fileFormats -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.returnValue -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.example -->
+
+<!-- UTSAPIJSON.writeBLECharacteristicValue.tutorial -->
+
+### 注意事项
+
+- 应根据特征值属性选择 `writeType`：`write` 为有响应写，`writeNoResponse` 为无响应写。当前 iOS 插件不传时使用 `write`，不会因特征值只支持无响应写而自动切换；此时需显式传入 `writeNoResponse`。
+- 当前 iOS 插件不会自动分包。超过单次写入长度上限时，会调用 `fail` 和 `complete`，需按长度上限与设备协议自行分包，详见 [getBLEMTU 的 iOS 注意事项](#getblemtu)。
+- 无响应写缺少外设对本次写入的协议层确认。若业务需要确认设备已接收或处理数据，应设计应用层应答机制。
+
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.name -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.description -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.compatibility -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.param -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.fileFormats -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.returnValue -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.example -->
+
+<!-- UTSAPIJSON.notifyBLECharacteristicValueChange.tutorial -->
+
+### 注意事项
+
+- 先注册 `onBLECharacteristicValueChange`，再传入 `state: true` 开启通知；特征值需支持 `notify` 或 `indicate`。
+- 开启成功表示通知配置完成，不代表外设会立即发送数据；是否上报、何时上报由设备协议决定。
+- 不再需要通知时传入 `state: false`。断线重连后如需继续接收通知，应重新发现服务和特征值并再次开启通知。
+
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.name -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.description -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.compatibility -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.param -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.fileFormats -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.returnValue -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.example -->
+
+<!-- UTSAPIJSON.onBLECharacteristicValueChange.tutorial -->
+
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.name -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.description -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.compatibility -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.param -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.fileFormats -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.returnValue -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.example -->
+
+<!-- UTSAPIJSON.offBLECharacteristicValueChange.tutorial -->
+
+
+<!-- UTSAPIJSON.ble.example -->
+
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->

package/data/uni-app-x-docs/api/convert2-abs-full-path.md

@@ -0,0 +1,33 @@
+<!-- UTSAPIJSON.convert2AbsFullPath.name -->
+
+<!-- UTSAPIJSON.convert2AbsFullPath.description -->
+
+<!-- UTSAPIJSON.convert2AbsFullPath.compatibility -->
+
+<!-- UTSAPIJSON.convert2AbsFullPath.param -->
+
+<!-- UTSAPIJSON.convert2AbsFullPath.fileFormats -->
+
+<!-- UTSAPIJSON.convert2AbsFullPath.returnValue -->
+
+<!-- UTSAPIJSON.convert2AbsFullPath.example -->
+
+以下为转换结果示例，实际路径因平台、系统版本不同而有所差异
+
+```js
+uni.convert2AbsFullPath('/static/logo.png')
+```
+
+返回值为绝对路径，各平台结果如下：
+
+| 平台 | 返回值 |
+| --- | --- |
+| Android | `/data/data/<package-name>/apps/<appid>/www/static/logo.png` |
+| iOS | `/var/mobile/Containers/.../Documents/uni-app-x/apps/<appid>/www/static/logo.png` |
+| Harmony | `/data/storage/el1/bundle/.../resfile/uni-app-x/apps/<appid>/www/static/logo.png` |
+
+<!-- UTSAPIJSON.convert2AbsFullPath.tutorial -->
+
+<!-- UTSAPIJSON.general_type.name -->
+
+<!-- UTSAPIJSON.general_type.param -->

package/data/uni-app-x-docs/api/create-drama-ad.md

@@ -2,38 +2,47 @@
 
 <!-- UTSAPIJSON.createDramaAd.description -->
 
-短剧广告：通过短剧内容生态（穿山甲内容联盟）变现的高价值广告形式。开发者将短剧内容（列表、播放页）嵌入自己的应用，用户免费观看指定集数后，需观看激励视频解锁后续剧集，从而实现广告变现。
+短剧广告：通过短剧内容生态 `穿山甲内容联盟(短剧)` 变现的高价值广告形式。将短剧内容（列表）嵌入自己的应用中，用户免费观看指定集数后，需观看激励视频解锁后续剧集，从而实现广告变现。
 
-uni-app x 内置短剧 uni-drama，提供两种接入方式：
+通过 uni.createDramaAd 可实现 API 模式接入方式： 调用查询接口获取短剧数据，自定义实现短剧列表界面，用户点击后通过 `open` 打开短剧播放界面。如需快速接入，请使用（[ad-drama](../component/ad-drama.md)）组件模式接入。
 
-| 接入方式 | 说明 | 适用场景 |
-| :- | :- | :- |
-| API 模式 | 通过 `uni.createDramaAd` 创建实例，自行搭建短剧列表页，调用查询接口获取短剧数据，再调用 `open` 打开原生播放页 | 需要自定义短剧列表页样式、深度定制业务 |
-| 组件模式 | 使用 `<ad-drama>` 组件（native-view）| 快速接入，直接使用渠道提供的短剧首页 |
-
-组件模式另见：[ad-drama 组件](../component/ad-drama.md)。
-示例Demo另见：[详见](https://gitcode.com/dcloud/uni-ad-drama)
+- uni-ad的业务介绍：[详见](https://uniapp.dcloud.net.cn/uni-ad/)
+- 示例Demo：[详见](https://gitcode.com/dcloud/uni-ad-drama)
 
 **开通配置广告**
 
 [开通广告步骤详情](https://uniapp.dcloud.net.cn/uni-ad/ad-open.html)
 
 **Tips**
-- 标准基座不支持测试短剧功能。
-- 使用短剧组件需要先开通穿山甲广告。开通问题请咨询：[uni-ad交流群](https://im.dcloud.net.cn/#/?joinGroup=65d85fc09847e92db03ff81a)。
-- 标准基座不包含短剧运行时，需制作自定义基座后运行，否则报错 `-5020`。
+- HBuilder 5.32 版本 app-android 平台支持。
+- 使用短剧组件需要先开通穿山甲广告，相关问题请咨询：[uni-ad交流群](https://im.dcloud.net.cn/#/?joinGroup=65d85fc09847e92db03ff81a)。
+- 标准基座不包含短剧功能，需勾选广告联盟中的“穿山甲内容联盟(短剧)”，打包自定义基座后运行，否则报错 `-5020` 错误。
 
 ### 配置文件
 
-在穿山甲后台 内容输出->接入管理 找到需要接入内容SDK的应用，点击"下载SDK参数配置"，然后将SDK配置文件（例如 sdk_setting_file.json）拷贝到项目的 assets 文件夹下。
+短剧功能使用的“穿山甲内容联盟(短剧)”要求配置 `SDK参数配置` 文件，在穿山甲后台 "内容输出" -> "接入管理" 找到需要接入内容SDK的应用，点击"下载SDK参数配置"：
 
 ![](https://lf3-plat.pglstatp-toutiao.com/obj/union-platform/a30bc3001dff716fcf6876da15151ecf.png)
 
-文件下载之后重命名为：`gm_SDK_Setting.json`，然后将文件放到项目根目录的`nativeResources->android->assets`目录下。
+配置文件下载之后重命名为 `gm_SDK_Setting.json`，然后将文件放到到 uni-app x 项目的 `nativeResources\android\assets` 文件夹中。
 
 ### 服务器回调
 
-用户观看激励视频解锁剧集后，为防止客户端伪造看完广告的凭据，解锁集数的发放由服务器回调完成，这是业内通行的安全方案。调用 `open` 时传入 `urlCallback`（userId/extra），激励发放时会透传到业务服务器参与校验。服务器回调机制详见 [激励视频广告服务器回调](https://uniapp.dcloud.net.cn/uni-ad/ad-rewarded-video.html#callback)。
+短剧的变现逻辑是：用户免费看完前面几集后，需要看一段激励视频才能解锁后续剧集。这里有一个关键的安全问题——"用户到底有没有真的看完广告"，这件事不能听客户端的。
+
+客户端播放结束时的结果（如 `isEnded`）只是本地状态，很容易被黑产通过反编译、抓包伪造请求来冒充。如果直接按客户端上报来解锁，攻击者可以一次广告都不看就骗取解锁，而广告平台那边并没有真正产生广告收入，最后是开发者既赔了内容又拿不到钱。
+
+所以，解锁集数的发放必须由服务器回调来完成：用户完整看完激励视频后，广告平台会通知 uni-ad，uni-ad 再通过 uniCloud 把"这次广告确实看完了"的可信消息发送到开发者自己的业务服务器，由业务服务器来发放解锁。这条链路黑产无法伪造，是业内通行的安全方案（支付回调同理），没有配置服务器回调的解锁是不安全的。
+
+接入步骤：
+
+1. 在 uni-ad 后台为短剧广告位开启激励视频服务器回调，并选择业务所在位置：业务在 uniCloud 则选云函数/云对象；业务在传统服务器则配置回调 URL。
+2. 调用 `open` 时传入 `urlCallback`，用于把业务身份带给服务器：
+   - `userId`：用户唯一标识，服务器据此知道该给谁解锁；
+   - `extra`：业务自定义参数，例如本次要解锁的剧集 ID、订单号等，回调时原样回传。
+3. 业务服务器收到回调后，按 `userId` / `extra` 校验并解锁对应集数。客户端不要自行解锁，只根据服务器结果刷新界面。
+
+服务器回调的详细机制、回调参数、签名校验和完整配置流程，详见 [激励视频广告服务器回调](https://uniapp.dcloud.net.cn/uni-ad/ad-rewarded-video.html#callback)。
 
 <!-- UTSAPIJSON.createDramaAd.compatibility -->
 

package/data/uni-app-x-docs/api/create-selector-query.md

@@ -54,7 +54,7 @@ createSelectorQuery是小程序的API，因小程序未开放DOM，且视图层
   </view>
 </template>
 
-<script setup lang="uts">
+<script setup lang="ts">
   const instance = getCurrentInstance()!.proxy!
   const nodeInfoList = ref<NodeInfo[]>([])
 
@@ -131,7 +131,7 @@ uni.createSelectorQuery().select('.rect1').selectAll('.rect2').boundingClientRec
     <button @click="query">query</button>
   </view>
 </template>
-<script setup lang="uts">
+<script setup lang="ts">
   const instance = getCurrentInstance()!.proxy!
 
   const query = () => {

package/data/uni-app-x-docs/api/create-worker.md

@@ -14,7 +14,7 @@ uni-app x的代码，默认都是在主线程执行的，主线程也称为UI线
 - 线程之间通信，可以post消息，也可以共享变量。web和小程序仅支持shareArrayBuffer数据类型的共享。App平台没有限制，引用类型都可以共享变量。但共享变量时，需要开发者注意线程安全问题，避免多线程同时写同一个变量，或一个线程读、同时另一个线程在写同一个变量，这可能引发崩溃。
 - 线程和Android的协程是不同的。Android上request api内部已经使用了协程。
 - CPU的核数有限，不要同时开太多线程。
-- worker是一个uts API，无法在js环境使用。iOS平台、Android的蒸汽模式， Worker 仅支持在[uts插件](../plugin/uts-plugin.md)中使用，不能直接在 `uvue` 页面中调用 `uni.createWorker`  
+- worker是一个uts API，无法在js环境使用。iOS平台、Android的蒸汽模式， Worker 仅支持在[uts插件](../plugin/uts-plugin.md)中使用，不能直接在 `uvue` 页面中调用 `uni.createWorker`
 
 常见场景：
 - 当你的界面掉帧时，应该检查是什么耗时任务导致不能及时渲染，是否可以剥离一些计算任务到子线程来做。
@@ -129,7 +129,7 @@ export class HelloWorkerTask extends WorkerTaskImpl {
    */
   override onMessage(message : any) {
     // 处理消息对象
-    const messageData = message as UTSJSONObject;
+    const messageData = message;
 
     // console.log('收到主线程数据:', messageData);
 
@@ -204,7 +204,7 @@ const worker = uni.createWorker('workers/HelloWorkerTask.uts');
 
 // 监听 Worker 消息
 worker.onMessage((message: any) => {
-  const messageData = message as UTSJSONObject;
+  const messageData = message;
 
   console.log('收到Worker子线程数据:', messageData);
 });
@@ -283,11 +283,10 @@ worker.terminate();
 ```
 
 ## Tips
-- `uni.createWorker` 仅支持在主线程中使用，在 Worker 子线程中使用会返回错误  
-- 各平台在 Worker 中使用全局变量或静态属性在内存管理中存在差异，Android/iOS平台可以共享内存，其它平台不能共享，为了避免这些差异带来的影响建议不要使用全局变量和静态属性  
-- Worker 子线程间暂不支持直接互相通讯，如要通讯可通过主线程中转发送消息来实现  
-- Android/iOS平台主线程与 Worker 线程传输的引用类型数据是直接共享使用（其它平台是默认为复制），需避免并发访问，暂未提供线程间安全访问机制，需通过业务逻辑控制避免并发访问这些共享的数据  
-- 鸿蒙平台主线程与 Worker 线程传输的数据默认为浅拷贝，如需传出共享对象，可在[uts插件](../plugin/uts-plugin.md)中混编开发定义[Sendable对象](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sendable)，调用 `Worker.postMessage` 发送这些共享对象时设置 `harmonySendable` 参数为 true  
-- Worker 中仅支持调用界面无关的API（如 uni.request、uni.getLocation 等），这些 API 触发的回调运行在 Workder 线程中  
-- Web 平台不支持在 worker 中调用 uni 上的 API  
-
+- `uni.createWorker` 仅支持在主线程中使用，在 Worker 子线程中使用会返回错误
+- 各平台在 Worker 中使用全局变量或静态属性在内存管理中存在差异，Android/iOS平台可以共享内存，其它平台不能共享，为了避免这些差异带来的影响建议不要使用全局变量和静态属性
+- Worker 子线程间暂不支持直接互相通讯，如要通讯可通过主线程中转发送消息来实现
+- Android/iOS平台主线程与 Worker 线程传输的引用类型数据是直接共享使用（其它平台是默认为复制），需避免并发访问，暂未提供线程间安全访问机制，需通过业务逻辑控制避免并发访问这些共享的数据
+- 鸿蒙平台主线程与 Worker 线程传输的数据默认为浅拷贝，如需传出共享对象，可在[uts插件](../plugin/uts-plugin.md)中混编开发定义[Sendable对象](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sendable)，调用 `Worker.postMessage` 发送这些共享对象时设置 `harmonySendable` 参数为 true
+- Worker 中仅支持调用界面无关的API（如 uni.request、uni.getLocation 等），这些 API 触发的回调运行在 Workder 线程中
+- Web 平台不支持在 worker 中调用 uni 上的 API

package/data/uni-app-x-docs/api/dialog-page.md

@@ -29,6 +29,10 @@ dialogPage和主page的区别：
 - 在web平台，dialogPage显示时，不影响URL的变化。
 - dialogPage默认没有窗体动画。如果是半屏内容，建议在页面内通过css或uts操作页面元素进行动画，灵活度更高。如果是全屏界面，可以使用窗体动画，但没有popin这种与上一个页面的联动动画。
 
+pages.json 配置注意事项：
+- dialogPage 没有导航栏，因此其 `style` 中的 `navigationBar` 相关配置无效。
+- dialogPage 的页面方向跟随所属的主页面（parentPage），因此其 `style.pageOrientation` 配置无效。
+
 dialogPage的绑定：
 - dialogPage需绑定在某个主页面上，即parentPage。parentPage页面关闭时，自动销毁相关dialogPage。
 - 在app的onLaunch调用openDialogPage，绑定到首页。

package/data/uni-app-x-docs/api/dom/README.md

@@ -151,7 +151,7 @@ this.myView?.style?.setProperty('background-color', 'red');
 	<!-- #endif -->
 </template>
 
-<script setup lang="uts">
+<script setup lang="ts">
 	const color = ref('red')
 	const myView = ref<UniElement | null>(null)