1# ArkUI子系统Changelog 2 3## cl.arkui.1 默认深浅色切换流程变更 4 5**访问级别** 6 7其他 8 9**变更原因** 10 11针对深浅色模式切换等系统配置的热更新场景，当前的实现方式会导致整个组件树重新构建，进而使得TS层的UI代码重新执行。在页面结构较为复杂时，这种处理方式会显著降低时间性能。我们需要对此进行优化。 12 13**变更影响** 14 15此变更涉及应用适配 16 17- 变更前：系统配置热更新场景下，组件树重新构建，相关属性设置的代码重新执行，存在大量不涉及深浅色变更的冗余开销。 18 19- 变更后：开发者在属性中调用的方法不会再被触发。因此，如果有开发者在属性设置中使用了函数的方式去适配深浅色变化，那么变更后将会失效。 20 21**起始API Level** 22 23不涉及API 24 25**变更发生版本** 26 27从OpenHarmony SDK 6.0.1.2开始。 28 29**变更的接口/组件** 30 31不涉及具体接口/组件 32 33**适配指导** 34 35上面的适配方式虽然在旧版本能够生效，但并不是合理的适配方式，变更后将不再支持。 36开发者可以根据自己的业务场景，按照如下正确方式进行深浅色模式适配： 37方法一：对于仅仅是深浅色模式下显示类资源的自定义配置场景，比如上面代码中的背景色切换，推荐开发者采用资源目录配置的方式适配深浅色。 38参考开发指南：[应用深浅色适配](../../../application-dev/ui/ui-dark-light-color-adaptation.md) 39方法二：对于在不同颜色模式下有比较复杂的定制业务逻辑的场景，开发者需要在Ability类提供的系统配置变更回调中监听配置变更，当深浅等配置变化时通过绑定状态变量等方式进行适配，[参考API文档](../../../application-dev/reference/apis-ability-kit/js-apis-app-ability-ability.md#abilityonconfigurationupdate) 40下面是一个简单的例子： 41 42```ts 43@Entry 44@Component 45struct Index { 46 // 深浅色适配函数 47 getBackgroundColor(): ResourceColor { 48 // let isDark = getSystemColorMode(); 通过媒体查询等方式获取当前系统颜色模式 49 // some other codes 其他的定制逻辑 50 return isDark ? Color.Blue : Color.Black; // 返回自定义颜色值 51 } 52 build() { 53 RelativeContainer() { 54 Column() 55 .width(100) 56 .height(100) 57 // 依赖backgroundColor()属性设置接口重新执行，才会重新执行getBackgroundColor()完成正确切换 58 .backgroundColor(this.getBackgroundColor()) 59 } 60 .height('100%') 61 .width('100%') 62 } 63} 64``` 65 661、通过程序启动时，在UIAbility中重写onConfigurationUpdate监听配置变化。 67```ts 68// EntryAbility.ts 69 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 70 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 71 AppStorage.setOrCreate('currentColorMode', this.context.config.colorMode); 72 73 } 74 75 onConfigurationUpdate(newConfig: Configuration): void { 76 AppStorage.setOrCreate('currentColorMode', newConfig.colorMode); 77 } 78``` 79 802、在需要适配的地方通过[AppStorage能力](../../../application-dev/ui/state-management/arkts-appstorage.md)进行适配。 81 82```ts 83import { ConfigurationConstant } from '@kit.AbilityKit'; 84 85@Entry 86@Component 87struct Index { 88 @State isDark: boolean = false; 89 @StorageProp('currentColorMode') @Watch('onColorModeChange') currentMode: number = 90 ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT; 91 92 onColorModeChange(): void { 93 // 也可以实现更加复杂的应用自定义的适配逻辑，这里用一个颜色变量的设置作为简单例子 94 this.isDark = (this.currentMode === ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT) ? false : true; 95 this.columColor = this.isDark ? Color.Blue : Color.Black; 96 } 97 98 getBackgroundColor(): ResourceColor { 99 return this.isDark ? Color.Blue : Color.Black; 100 } 101 102 // 通过状态变量触发页面更新逻辑 103 @State columColor: ResourceColor = Color.Black; 104 105 build() { 106 RelativeContainer() { 107 Column() 108 .width(100) 109 .height(100) 110 .backgroundColor(this.getBackgroundColor())// 变更前 111 .backgroundColor(this.columColor) 112 } 113 .height('100%') 114 .width('100%') 115 } 116} 117``` 118 119## cl.arkui.2 WithTheme组件设置colorMode后效果异常问题修复 120 121**访问级别** 122 123公开 124 125**变更原因** 126 127WithTheme组件指定局部主题的能力对某些组件不生效。例如：通过WithTheme设置主题深浅色为DARK或LIGHT后，Button子组件使用的资源仍会依循系统深浅色变化。 128 129**变更影响** 130 131此变更涉及应用适配 132 133- 变更前：WithTheme组件设置了主题后，其子组件的主题仍旧跟随系统切换。 134 135- 变更后：WithTheme组件设置了主题后，其中的子组件使用指定的主题，不跟随系统切换。 136 137 **变更涉及组件范围** 138 139 变更前部分组件未适配WithTheme，因此其作为WithTheme子组件不受指定的主题影响，因此变更后这部分组件的行为会受到影响。变更前后会受到影响的具体组件类型列表如下： 140 141 TextArea、Search、Button、DatePicker、TextPicker、TimePicker、AlphabetIndexer、Swiper、Scroll、Tabs、TabContent、RichEditor、Menu、MenuItem、Counter、Progress、TextClock、LoadingProgress。 142 143**起始API Level** 144 14512 146 147**变更发生版本** 148 149从OpenHarmony SDK 6.0.1.2开始。 150 151**变更的接口/组件** 152 153 WithTheme 154 155**适配指导** 156 157变更后，WithTheme组件指定的主题对子组件生效。若需适配，应针对发生变化的组件增加WithTheme，并指定其主题跟随系统，例如设置colorMode属性为SYSTEM。 158 159```ts 160// index.ets 161@Entry 162@Component 163struct Index { 164 build() { 165 Column() { 166 // 设置组件为深色模式 167 WithTheme({ colorMode: ThemeColorMode.DARK }) { 168 // 适配:设置colorMode为ThemeColorMode.SYSTEM 169 Column() { 170 Text('WithTheme') 171 .fontSize(40) 172 .fontWeight(FontWeight.Bold) 173 Text('DARK') 174 .fontSize(40) 175 .fontWeight(FontWeight.Bold) 176 } 177 .justifyContent(FlexAlign.Center) 178 .width('100%') 179 .height('33%') 180 .backgroundColor($r('sys.color.background_primary')) 181 } 182 } 183 .height('100%') 184 .expandSafeArea([SafeAreaType.SYSTEM], 185 [SafeAreaEdge.TOP, SafeAreaEdge.END, SafeAreaEdge.BOTTOM, SafeAreaEdge.START]) 186 } 187} 188``` 189 190## cl.arkui.3 ListItem组件创建行为变更 191**访问级别** 192 193公开接口 194 195**变更原因** 196 197如果ListItem组件不是通过LazyForEach和Repeat动态生成，创建ListItem时会执行两次ListItem的属性方法，需要优化为只执行一次属性方法以提升性能。 198 199**变更影响** 200 201此变更涉及应用适配，只涉及ListItem组件。 202 203变更前：如果ListItem组件不是通过LazyForEach和Repeat动态生成，创建ListItem时会执行两次ListItem的属性方法。 204 205变更后：ListItem在创建时只执行一次属性方法。 206 207如下代码运行后，变更前会打印两次“GetWidth”，变更后只会打印一次“GetWidth”。 208 209```ts 210@Entry 211@Component 212struct ListItemExample { 213 getWidth(): string { 214 console.log("GetWidth"); 215 return "100%" 216 } 217 build() { 218 Column() { 219 List({ space: 20, initialIndex: 0 }) { 220 ListItem() { 221 Text('Item') 222 } 223 .width(this.getWidth()) 224 }.width('90%') 225 }.width('100%').height('100%') 226 } 227} 228``` 229 230**起始API Level** 231 232API 7 233 234**变更发生版本** 235从OpenHarmony SDK 6.0.1.2开始。 236 237**变更的接口/组件** 238 239ListItem组件。 240 241**适配指导** 242 243需要排查ListItem属性方法中是否有调用函数获取属性值，排查函数调用次数是否对业务有影响，如果有影响需要根据实际业务场景适配。 244 245## cl.arkui.4 FullScreenLaunchComponent嵌入式运行元服务内容区避让系统安全区行为变更 246**访问级别** 247 248公开接口 249 250**变更原因** 251 252通过FullScreenLaunchComponent拉起嵌入式运行元服务时，元服务的windowMode为undefined, 元服务的页面内容在任何场景下都不会避让系统安全区，嵌入式运行元服务和跳出式运行元服务页面默认避让行为不一致，需要元服务的开发者针对嵌入式场景主动做避让适配。 253 254**变更影响** 255 256此变更涉及应用适配。 257 258说明：宿主是拉起方，即FullScreenLaunchComponent组件使用方，提供方是被嵌入式运行的元服务。 259 260- 变更前：提供方的windowMode不跟随宿主，默认值为undefined，所有场景下，元服务的页面内容都不会默认避让系统安全区，需要提供方开发者主动避让。 261 262- 变更后：提供方的windowMode跟随宿主保持一致，在宿主windowMode为全屏显示的场景下，并且提供方未主动设置页面为沉浸式，提供方页面会默认避让系统安全区，无需提供方开发者主动避让 263 264| 变更前 | 变更后 | 265| :----------------------------------------: | :-------------------------------------: | 266|  |  | 267 268**起始API Level** 269 270API 12 271 272**变更发生版本** 273从OpenHarmony SDK 6.0.1.2开始。 274 275**变更的接口/组件** 276 277FullScreenLaunchComponent组件及嵌入式拉起的元服务。 278 279**适配指导** 280 281- 宿主的targetsdkversion >= 20。 282 - 建议宿主应用在6.0及以上版本使用嵌入式运行元服务，5.x版本建议使用跳出式运行元服务，提供方元服务无需在嵌入式场景主动避让适配。 283 - 如果宿主应用需要在5.x使用嵌入式运行元服务，需要提供方元服务针对嵌入式场景做适配，需要判断提供方元服务的ohos.extra.atomicservice.param.key.isFollowHostWindowMode，如果ohos.extra.atomicservice.param.key.isFollowHostWindowMode为true,无需主动避让适配；否则需要主动避让适配。 284 285- 宿主的targetsdkversion < 20。 286 - 不建议宿主应用使用嵌入式运行元服务，建议使用跳出式运行元服务。 287 - 如果宿主应用需要使用嵌入式运行元服务，提供方元服务需要判断ohos.extra.atomicservice.param.key.isFollowHostWindowMode，若ohos.extra.atomicservice.param.key.isFollowHostWindowMode为true,无需主动避让适配；否则需要主动避让适配。 288```ts 289export default class AtomicServiceAbility extends EmbeddableUIAbility { 290 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 291 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 292 if (want.parameters) { 293 hilog.info(0x0000, 'testTag', '%{public}s', 'followed host window mode' + want.parameters['ohos.extra.atomicservice.param.key.isFollowHostWindowMode']); 294 } 295 } 296} 297```
