harmony 鸿蒙@ohos.advertising.AdComponent (Non-Full-Screen Ad Component)

2025-06-12
浏览 (181)

@ohos.advertising.AdComponent (Non-Full-Screen Ad Component)

The AdComponent module provides the capability of displaying non-full-screen ads.

NOTE - The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { AdComponent } from '@kit.AdsKit';

AdComponent

AdComponent(ads: advertising.Advertisement[], displayOptions: advertising.AdDisplayOptions, interactionListener: advertising.AdInteractionListener, @BuilderParam adRenderer?: () => void, @Prop rollPlayState?: number): void

Component that displays a non-full-screen ad.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Advertising.Ads

Parameters

Name	Type	Mandatory	Description
ads	advertising.Advertisement[]	Yes	Array of ad objects. Atomic service API: This API can be used in atomic services since API version 12.
displayOptions	advertising.AdDisplayOptions	Yes	Ad display parameters. Atomic service API: This API can be used in atomic services since API version 12.
interactionListener	advertising.AdInteractionListener	Yes	Ad status change callback. Atomic service API: This API can be used in atomic services since API version 12.
adRenderer¹²⁺	() => void	No	Ad self-rendering.
rollPlayState¹⁵⁺	number	No	Roll ad state. The value 1 means that the roll ad is played, and the value 2 means that the roll ad is paused. Other values are invalid and the previous playback state is not changed. If this parameter is left empty, the default value is 2.

Example

import { AdComponent, advertising } from '@kit.AdsKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  // Requested ad content.
  private ads: advertising.Advertisement[] = [];
  // Ad display parameters.
  private adDisplayOptions: advertising.AdDisplayOptions = {
    // Whether to mute the ad. By default, the ad is not muted.
    mute: false
  };

  build() {
    Column() {
      // The AdComponent is used to show a non-full-screen ad.
      AdComponent({
        ads: this.ads,
        displayOptions: this.adDisplayOptions,
        interactionListener: {
          // Ad status change callback.
          onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => {
            switch (status) {
              case 'onAdOpen':
                hilog.info(0x0000, 'testTag', 'onAdOpen');
                break;
              case 'onAdClick':
                hilog.info(0x0000, 'testTag', 'onAdClick');
                break;
              case 'onAdClose':
                hilog.info(0x0000, 'testTag', 'onAdClose');
                break;
            }
          }
        }
      })
        .width('100%')
        .height('100%')
    }
    .width('100%')
    .height('100%')
  }
}