@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.1

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/references/changelogs/5.0.3(15)/beta2-os-api-behavior-changes.md

@@ -0,0 +1,240 @@
+---
+title: OS平台API行为的变更
+source: https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/changelogs-for-all-apps-5032
+category: harmonyos-releases
+downloaded_at: 2026-09-03
+---
+
+# OS平台API行为的变更
+
+## ArkUI
+
+### Image、Text和ListItem组件onDragStart接口默认行为变更
+
+**变更原因**
+
+Image、Text和ListItem组件存在设置onDragStart接口DragItemInfo返回值中的builder属性后，返回值中pixelMap和extraInfo属性不生效的问题。
+
+**变更影响**
+
+此变更涉及应用适配，只涉及Image、Text和ListItem组件。
+
+-   变更前：onDragStart接口设置返回值中的builder属性后，无法解析pixelMap和extraInfo属性。同时设置了builder和pixelMap时，拖拽显示的是builder的预览图。onDrop回调中无法获取extraParams参数的值（对应extraInfo）。
+    
+-   变更后：onDragStart接口设置返回值中的builder属性后，能够解析pixelMap和extraInfo属性。同时设置了builder和pixelMap时，拖拽显示的是pixelMap的预览图。onDrop回调中能够获取extraParams参数的值（对应extraInfo）。
+    
+
+**说明**
+
+此变更已做版本隔离，变更仅在应用的targetSdkVersion设置为大于等于5.0.3(15)时生效。
+
+**起始API Level**
+
+11
+
+**变更的接口/组件**
+
+涉及组件：Image、Text和ListItem。
+
+涉及接口： onDragStart(event: (event: DragEvent, extraParams?: string) => CustomBuilder | DragItemInfo)
+
+**适配指导**
+
+onDragStart接口的返回值用于指定拖拽过程中显示的图片(pixelMap，builder)以及拖拽过程中组件携带的额外信息(extraInfo)。变更后，pixelMap属性能够正常解析。由于pixelMap的优先级高于builder，如果同时设置了pixelMap和builder，应移除返回值中的pixelMap属性。同样，若不打算传递extraInfo，也应删除该属性。具体实现代码如下：
+
+```
+@Entry
+@Component
+struct SlideExample {
+  build() {
+    Row() {
+      Image()
+      .onDragStart((event) => {
+        return {
+          builder: () => { this.pixelMapBuilder() },
+          // 若需要拖拽显示builder，需要移除掉pixelMap属性的赋值。
+          // pixelMap:this.pixelMap,
+          // 若设置了builder并且不需要传递extraInfo，需要移除掉extraInfo属性的赋值。
+          // extraInfo: "test"
+        }
+      })
+    }.height('100%')
+  }
+}
+```
+
+### 轴事件支持BEGIN、END及CANCEL类型回调触发
+
+**变更原因**
+
+开发者无法监听到轴事件的BEGIN、END、CANCEL类型的事件回调。
+
+**变更影响**
+
+此变更不涉及应用适配。
+
+变更前：开发者通过OH\_NativeXComponent\_RegisterUIInputEventCallback接口监听轴事件回调，无法收到BEGIN、END、CANCEL类型的事件回调。
+
+变更后：开发者通过OH\_NativeXComponent\_RegisterUIInputEventCallback接口监听轴事件回调，可以收到BEGIN、END、CANCEL类型的事件回调。
+
+**说明**
+
+此变更已做版本隔离，变更仅在应用的targetSdkVersion设置为大于等于5.0.3(15)时生效。
+
+**起始API Level**
+
+12
+
+**变更的接口/组件**
+
+OH\_NativeXComponent\_RegisterUIInputEventCallback接口。
+
+**适配指导**
+
+默认行为变更，无需适配。
+
+### TextController的SetStyledString接口支持保存设置的属性字符串信息到调用的TextController中
+
+**变更原因**
+
+优化属性字符串与Text组件的绑定时机。
+
+**变更影响**
+
+此变更涉及应用适配。
+
+-   变更前：开发者调用TextController的setStyledString接口设置属性字符串时，如果调用时TextController还未绑定对应的Text，则此次设置无效。
+    
+-   变更后：开发者调用TextController的setStyledString接口时，调用的TextController会保存设置的属性字符串。当TextController和Text绑定时，如果TextController中已经存储之前调用setStyledString接口保存的属性字符串，则Text会自动设置保存的属性字符串，显示出对应的属性字符串。
+    
+
+**说明**
+
+此变更已做版本隔离，变更仅在应用的targetSdkVersion设置为大于等于5.0.3(15)时生效。
+
+**起始API Level**
+
+12
+
+**适配指导**
+
+变更后对setStyledString的接口的调用可以更加灵活，Text能够正确地显示出属性字符串。
+
+```
+@Entry
+@Component
+struct StyledStringExample {
+  controller: TextController = new TextController()
+
+  aboutToAppear(): void {
+    this.controller.setStyledString(new StyledString("123456")) // 变更前，由于此时controller还未和Text绑定，此次设置不生效。变更后，属性字符串可以正确的显示
+  }
+
+  build() {
+    Row() {
+      Column() {
+        Text(undefined, {controller: this.controller})
+      }.width('100%')
+    }.height('100%')
+  }
+}
+```
+
+### PC/2in1设备上，悬浮窗层级由低于dock栏调整为高于dock栏
+
+**变更原因**
+
+应用创建的TYPE\_FLOAT类型的悬浮窗，因为层级低于Dock，会被Dock栏遮挡，在视频会议等场景，体验不符合应用预期。
+
+**变更影响**
+
+此变更不涉及应用适配。
+
+-   变更前：在PC/2in1设备上，TYPE\_FLOAT类型的悬浮窗层级在dock栏之下。
+    
+-   变更后：在PC/2in1设备上，TYPE\_FLOAT类型的悬浮窗层级在dock栏之上。
+    
+
+**起始API Level**
+
+9
+
+**变更的接口/组件**
+
+@ohos.window.d.ts
+
+接口：TYPE\_FLOAT
+
+**适配指导**
+
+默认行为变更，无需适配。
+
+## Call Service Kit
+
+### 通话应用在前台时不显示通话胶囊
+
+**变更原因**
+
+通话体验优化。
+
+**变更影响**
+
+此变更涉及应用适配。
+
+**说明**
+
+此变更已做版本隔离，变更仅在应用的targetSdkVersion设置为大于等于5.0.3(15)时生效。
+
+变更前：通话中，即使应用在前台，也会显示通话胶囊，点击通话胶囊可以返回通话界面。
+
+变更后：通话中，如果应用在前台，不会显示通话胶囊；如果应用在前台，但不在通话界面，则需要应用通过显示画中画界面自行实现返回通话界面的功能，如图所示。
+
+| 变更前 | 变更后（应用前台但非通话界面） |
+| --- | --- |
+| ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/01/v3/hCnOPhd7TpOQL_jeu5UTBQ/zh-cn_image_0000002194462304.png?HW-CC-KV=V1&HW-CC-Date=20260903T083917Z&HW-CC-Expire=86400&HW-CC-Sign=8F320422F3B60BA89B1FC9F5957D818C8CB3AAEDF3F838D6716BE43C60622760) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2d/v3/6P3JPTQQQESt4eN1s-vgCg/zh-cn_image_0000002229902133.png?HW-CC-KV=V1&HW-CC-Date=20260903T083917Z&HW-CC-Expire=86400&HW-CC-Sign=B9661DE9D247253483FAFE4474B5872D41B89B87CFE370C07978A696A5FC8882) |
+
+**起始API Level**
+
+4.1.0(11)
+
+**变更的接口/组件**
+
+voipCall.reportIncomingCall（上报来电）
+
+voipCall.reportOutgoingCall（上报去电）
+
+**适配指导**
+
+通话中，如果应用是非通话界面在前台，则需要显示画中画界面用于返回通话界面，详见在应用程序中使用[画中画功能](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/window-pipwindow)。
+
+## Performance Analysis Kit
+
+### HiAppEvent模块onReceive、OH\_HiAppEvent\_OnReceive、takeNext接口支持应用分身故障日志订阅隔离
+
+**变更原因**
+
+应用分身从设计原则上要求数据隔离，当前应用分身的故障日志和主应用未进行隔离，不易于对分身应用的日志维护。
+
+**变更影响**
+
+此变更不涉及应用适配
+
+变更前：hiappevent在主应用、分身应用可以同时获取到主应用和分身应用的故障日志。
+
+变更后：hiappevent在主应用仅可以获取到主应用的故障日志，分身应用仅可以获取到分身应用的故障日志。
+
+**起始API Level**
+
+-   takeNext接：9
+-   onReceive：11
+-   OH\_HiAppEvent\_OnReceive：12
+
+**变更的接口/组件**
+
+@ohos.hiviewdfx.hiAppEvent.d.ts中的[onReceive](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-hiviewdfx-hiappevent#watcher)、[takeNext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-hiviewdfx-hiappevent#takenext)接口。
+
+hiappevent.h中的[OH\_HiAppEvent\_OnReceive](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-hiappevent-h#oh_hiappevent_onreceive)接口。
+
+**适配指导**
+
+默认行为变更，无需适配。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/references/changelogs/5.0.3(15)/beta2-ux-style-and-effect-changes.md

@@ -0,0 +1,90 @@
+---
+title: UX样式或效果的变更
+source: https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/changelogs-ux-5032
+category: harmonyos-releases
+downloaded_at: 2026-09-03
+---
+
+# UX样式或效果的变更
+
+## 动态照片自动播放效果变更
+
+**变更原因**
+
+动态照片自动播放时会放大至1.1倍；动态照片左右滑动自动播放时，闪烁和晃动效果明显。为改善用户界面使用体验，动态照片设置autoPlay自动播放时不放大。
+
+**变更影响**
+
+此变更无需应用适配。
+
+@ohos.multimedia.medialibrary模块中的autoPlay接口ux默认行为规范变更。
+
+变更前行为：动态照片设置autoPlay自动播放时放大至1.1倍。
+
+变更后行为：动态照片设置autoPlay自动播放时不放大。
+
+**起始API Level**
+
+13
+
+**变更的接口/组件**
+
+@ohos.multimedia.medialibrary模块中的autoPlay接口。
+
+**适配指导**
+
+默认行为变更，无需适配。
+
+## NavDestination标题栏工具栏支持跟手滑动隐藏后，超过2秒未操作，不恢复显示
+
+**变更原因**
+
+UX规范变更。
+
+**变更影响**
+
+此变更不涉及应用适配。
+
+-   变更前：NavDestination组件的标题栏工具栏上滑隐藏，下滑显示，2s不操作后自动显示。
+    
+-   变更后：NavDestination组件的标题栏工具栏上滑隐藏，下滑显示，2s不操作后不会自动显示。
+    
+
+**起始API Level**
+
+14
+
+**变更的接口/组件**
+
+NavDestination.bindToScrollable, NavDestination.bindToNestedScrollable
+
+**适配指导**
+
+默认行为变更，无需适配。
+
+## Tabs组件TabBar的显示和隐藏动效变更
+
+**变更原因**
+
+UX规范变更。
+
+**变更影响**
+
+此变更不涉及应用适配。
+
+-   变更前：Tabs组件的TabBar上滑隐藏，下滑消失，2s不操作后自动显示。
+    
+-   变更后：Tabs组件的TabBar上滑隐藏，下滑消失，2s不操作后不会自动显示。
+    
+
+**起始API Level**
+
+13
+
+**变更的接口/组件**
+
+UIContext的bindTabsToScrollable、bindTabsToNestedScrollable接口
+
+**适配指导**
+
+默认行为变更，无需适配。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/references/changelogs/5.0.3(15)/release-os-api-behavior-changes.md

@@ -0,0 +1,69 @@
+---
+title: OS平台API行为的变更
+source: https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/changelogs-for-all-apps-5033
+category: harmonyos-releases
+downloaded_at: 2026-09-03
+---
+
+# OS平台API行为的变更
+
+## ArkUI
+
+### C API轴事件接口OH\_ArkUI\_UIInputEvent\_GetSourceType和OH\_ArkUI\_UIInputEvent\_GetToolType接口返回值变更
+
+**变更原因**
+
+通过鼠标滚轮或触控板触发的轴事件无法正确获取到触发源设备类型。
+
+**变更影响**
+
+此变更涉及应用适配。
+
+-   变更前：在使用鼠标滚轮或触控板的双指滑动操作时，应用程序无法通过OH\_ArkUI\_UIInputEvent\_GetSourceType和OH\_ArkUI\_UIInputEvent\_GetToolType准确获取触发源的类型，返回值为UNKNOWN。
+    
+-   变更后：在使用鼠标滚轮或触控板的双指滑动操作时，应用程序可以通过调用OH\_ArkUI\_UIInputEvent\_GetSourceType和OH\_ArkUI\_UIInputEvent\_GetToolType来获取正确的触发源类型。对于鼠标滚轮操作，获取的SourceType和ToolType均为MOUSE；而针对触控板操作，虽然得到的SourceType仍为MOUSE，但ToolType为TOUCHPAD。
+    
+
+**起始API Level**
+
+12
+
+**变更的接口/组件**
+
+OH\_ArkUI\_UIInputEvent\_GetSourceType和OH\_ArkUI\_UIInputEvent\_GetToolType
+
+**适配指导**
+
+当应用程序通过native\_interface\_xcomponent.h中的OH\_NativeXComponent\_RegisterUIInputEventCallback接口来接收和处理轴事件时，如果回调函数中已使用ToolType类型进行了判断，则无需进一步适配。但如果仅通过UNKNOWN类型处理业务，则需适配，以确保通过具体的目标类型进行区分。
+
+例如以下示例：
+
+```
+if (toolType != UI_INPUT_EVENT_TOOL_TYPE_UNKNOWN) {
+    // 应用业务逻辑
+}
+```
+
+建议以明确的目标类型进行区分，修改为如下代码实现：
+
+```
+if (toolType != UI_INPUT_EVENT_TOOL_TYPE_MOUSE) { // 是鼠标滚轮尝试的轴事件，数值单位为角度
+    // 鼠标滚轮只有竖向轴，获取滚动角度
+    double degree = OH_ArkUI_AxisEvent_GetVerticalAxisValue(event);
+    // 将角度映射为距离像素值
+    // 控制UI进行位移更新
+} else if (toolType != UI_INPUT_EVENT_TOOL_TYPE_TOUCHPAD) {
+    // 触控板上操作，用户即可横向滑动，也可竖向滑动，需要都获取分量
+    double offsetX = OH_ArkUI_AxisEvent_GetHorizontalAxisValue(event);
+    double offsetY = OH_ArkUI_AxisEvent_GetVerticalAxisValue(event);
+    if (offsetX == 0) {
+        // 横向分量为0，说明为竖向滑动
+        // 处理UI竖向滑动
+    } else {
+        // 横向滑动
+        // 处理UI横向滚动
+    }
+} else {
+    // 异常情况，应忽略
+}
+```