Maintaining Compatibility for UI Custom Components

The API version number format has been adjusted since 26.0.0 (for details, see the version number format adjustment description). This adjustment does not affect the basic logic for determining API compatibility. Therefore, the old version number format is still used in the examples provided in this document.

The relationship between the latest API versions is as follows:

26.0.0 > 6.1.1(24) > 6.1.0(23) > 6.0.2(22) > 6.0.1(21) > 6.0.0(20) > 5.1.1(19) > 5.1.0(18) > 5.0.5(17)

For UI custom components, state management decorators require API version isolation implemented within the custom component.

Example: In a scrolling list with reused items, the API for the new component reuse feature, implemented via the @ReusableV2 decorator, is available since SDK version 5.1.0(18). To ensure your application remains compatible with devices running API version 5.0.0(12), use deviceInfo.sdkApiVersion for compatibility checks.

(1) Provide a base custom component (V1Component) compatible with API version 5.0.0(12), and a reusable custom component (ReuseComponentV2) compatible with version 5.1.0(18).

(2) Use deviceInfo.sdkApiVersion within LazyForEach to conditionally decide which custom component to use.

Sample code:

import { deviceInfo } from '@kit.BasicServicesKit';

class BasicDataSource implements IDataSource {
  private listener: DataChangeListener | undefined = undefined;
  public dataArray: number[] = [];
  totalCount(): number {
    return this.dataArray.length;
  }
  getData(index: number): number {
    return this.dataArray[index];
  }
  registerDataChangeListener(listener: DataChangeListener): void {
    this.listener = listener;
  }
  unregisterDataChangeListener(listener: DataChangeListener): void {
    this.listener = undefined;
  }
}

@Entry
@ComponentV2
struct Index {
  private data: BasicDataSource = new BasicDataSource();
  aboutToAppear(): void {
    for (let index = 1; index < 20; index++) {
      this.data.dataArray.push(index);
    }
  }
  build() {
    List() {
      LazyForEach(this.data, (item: number, index: number) => {
        ListItem() {
          if (deviceInfo.sdkApiVersion >= 18) {
            ReuseComponentV2({ num: item }) // On devices with ROM API version 5.1.0(18) or later, use the reusable component enabled by the @ReusableV2 decorator.
          } else {
            V1Component({ num: item })  // On devices with ROM API version earlier than 5.1.0(18), use the standard V1 component.
          }
        }
      }, (item: number, index: number) => index.toString())
    }.cachedCount(1)
  }
}

// Custom component with V1 state management
@Component
struct V1Component {   // Reusable custom component (V1)
  @State num: number = 0;
  aboutToAppear(): void {
    console.log(`V1Component-- aboutToAppear`)  // On versions earlier than 5.1.0(18), V1 components are instantiated.
  }
  build() {
    BaseCom(this.num)  // Common UI
  }
}
// Custom component with V2 state management
@ReusableV2
@ComponentV2
struct ReuseComponentV2 {  // Reusable custom component (V2)
  @Param num: number = 0;
  aboutToReuse(): void {
    console.log(`ReuseComponentV2-- aboutToReusableV2`) // On version 5.1.0(18) or later, the V2 reuse mechanism is activated.
  }

  build() {
    BaseCom(this.num)
  }
}

// Common UI
@Builder function BaseCom(num: number) {  // Use @Builder to extract common UI components.
  Column() {
    Text('ReuseComponentChild num:' + num.toString())
  }.height(200)
}

In this example, the API version is checked using deviceInfo.sdkApiVersion:

(1) For device ROMs with API version of 5.1.0(18) or later, the V2 reuse mechanism activates. Scrolling through the list logs "ReuseComponentV2-- aboutToReusableV2," indicating that ReuseComponentV2 are being reused during scrolling.

(2) For device ROMs with API version earlier than 5.1.0(18), the system creates V1 components instead, logging "V1Component-- aboutToAppear," indicating that new V1Component instances are being created during scrolling.

目录

Maintaining Compatibility for UI Custom Components