目录

liveViewManager

本模块提供Live View Kit的基础能力,包括创建、更新和结束实况窗、获取实况窗和检查实况窗开关的功能。

起始版本:4.1.0(11)

导入模块

import { liveViewManager } from '@kit.LiveViewKit';

liveViewManager.isLiveViewEnabled

isLiveViewEnabled(): Promise<boolean>

查看应用实况窗开关,使用Promise异步返回结果。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

返回值:

类型

说明

Promise<boolean>

以Promise形式返回当前应用实况窗的开关状态。

  • true表示实况窗开关开启。
  • false表示实况窗开关关闭。

错误码:

以下错误码的详细介绍请参见ArkTS API错误码。

错误码ID

错误信息

1003500001

Internal error.

1003500002

Marshalling or unmarshalling error.

1003500003

Failed to connect service.

示例:
import { liveViewManager } from '@kit.LiveViewKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  liveViewManager.isLiveViewEnabled().then((isEnabled: boolean) => {
    hilog.info(0x0000, 'testTag', 'Succeeded in checking whether liveView is enabled, liveView is : %{public}s', isEnabled);
  }).catch((err: BusinessError) => {
    hilog.error(0x0000, 'testTag', 'Failed to check whether liveView is enabled: %{public}d %{public}s', err.code, err.message);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to check whether liveView is enabled: %{public}d %{public}s', e.code, e.message);
}

liveViewManager.startLiveView

startLiveView(liveView: LiveView): Promise<LiveViewResult>

创建实况窗,使用Promise异步返回结果。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

参数:

参数名

类型

必填

说明

liveView

LiveView

是

一个实况窗实例。

返回值:

类型

说明

Promise<LiveViewResult>

Promise对象,返回创建实况窗的结果。

错误码:

以下错误码的详细介绍请参见ArkTS API错误码。

错误码ID

错误信息

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1003500001

Internal error.

1003500002

Marshalling or unmarshalling error.

1003500003

Failed to connect service.

1003500004

LiveView is not enabled.

1003500005

The right of liveView is not enabled.

1003500006

The liveView already exists.

1003500007

Couldn't connect to server.

1003500008

Over max number liveViews per second.

示例:
import { liveViewManager } from '@kit.LiveViewKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { Want, wantAgent } from '@kit.AbilityKit';

async function startLiveView(): Promise<void> {
  try {
    // 定义创建的liveView
    let liveView: liveViewManager.LiveView = {
      id: 123,
      event: "PICK_UP",
      sequence: 1,
      isMute: false,
      liveViewData: {
        primary: {
          title: "餐品已备好",
          content: [
            { text: "请前往" }, 
            { text: "一号窗口", textColor: "#FFFF0000" }
          ],
          keepTime: 1,
          clickAction: await buildWantAgent(),
          extensionData: {
            text: "待取餐",
            type: liveViewManager.ExtensionType.EXTENSION_TYPE_COMMON_TEXT
          },
          layoutData: {
            layoutType: liveViewManager.LayoutType.LAYOUT_TYPE_PICKUP,
            title: "取餐码",
            content: "72988",
            underlineColor: "#FFFF0000",
            descPic: "coffee.jpg"
          }
        },
        capsule: {
          type: liveViewManager.CapsuleType.CAPSULE_TYPE_TEXT,
          status: 1,
          icon: "coffee.jpg",
          title: "待取餐",
          content: "取餐码:72988",
          backgroundColor: "#FF308977"
        }
      }
    };

    liveViewManager.startLiveView(liveView).then((liveViewResult: liveViewManager.LiveViewResult) => {
      hilog.info(0x0000, 'testTag', 'Succeeded in starting liveView, result: %{public}s', JSON.stringify(liveViewResult));
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', 'Failed to start liveView: %{public}d %{public}s', err.code, err.message);
    });
  } catch (err) {
    let e: BusinessError = err as BusinessError;
    hilog.error(0x0000, 'testTag', 'Failed to start liveView: %{public}d %{public}s', e.code, e.message);
  }
}

async function buildWantAgent(): Promise<Want> {
  const wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
      {
        bundleName: 'xxx.xxx.xxx',
        abilityName: 'EntryAbility'
      } as Want
    ],
    actionType: wantAgent.OperationType.START_ABILITIES,
    requestCode: 0,
    actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
  };
  try {
    const agent = await wantAgent.getWantAgent(wantAgentInfo);
    return agent;
  } catch (e) {
    const err: BusinessError = e as BusinessError;
    hilog.error(0x0000, 'testTag', 'Failed to get wantAgent: %{public}s', err.message);
    throw e as Error;
  }
}

liveViewManager.updateLiveView

updateLiveView(liveView: LiveView): Promise<LiveViewResult>

更新实况窗,使用Promise异步返回结果。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

参数:

参数名

类型

必填

说明

liveView

LiveView

是

一个实况窗实例。对于非必填字段,若无特殊说明,则不携带时默认继承上一次的状态。

返回值:

类型

说明

Promise<LiveViewResult>

Promise对象,返回更新实况窗的结果。

错误码:

以下错误码的详细介绍请参见ArkTS API错误码。

错误码ID

错误信息

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1003500001

Internal error.

1003500002

Marshalling or unmarshalling error.

1003500003

Failed to connect service.

1003500004

LiveView is not enabled.

1003500008

Over max number liveViews per second.

1003500009

The liveView does not exist.

1003500010

The liveView has ended.

1003500011

The liveView sequence is incorrect.

示例:
import { liveViewManager } from '@kit.LiveViewKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { Want, wantAgent } from '@kit.AbilityKit';

async function updateLiveView(): Promise<void> {
  try {
    // 定义更新的liveView
    let liveView: liveViewManager.LiveView = {
      id: 123,
      event: "PICK_UP",
      sequence: 2,
      isMute: false,
      liveViewData: {
        primary: {
          title: "餐品已备好",
          content: [
            { text: "请前往" }, 
            { text: "一号窗口", textColor: "#FFFF0000" }
          ],
          keepTime: 1,
          clickAction: await buildWantAgent(),
          extensionData: {
            text: "待取餐",
            type: liveViewManager.ExtensionType.EXTENSION_TYPE_COMMON_TEXT
          },
          layoutData: {
            layoutType: liveViewManager.LayoutType.LAYOUT_TYPE_PICKUP,
            title: "取餐码",
            content: "72988",
            underlineColor: "#FFFF0000",
            descPic: "coffee.jpg"
          }
        },
        capsule: {
          type: liveViewManager.CapsuleType.CAPSULE_TYPE_TEXT,
          status: 1,
          icon: "coffee.jpg",
          title: "待取餐",
          content: "取餐码:72988",
          backgroundColor: "#FF308977"
        }
      }
    };

    liveViewManager.updateLiveView(liveView).then((liveViewResult: liveViewManager.LiveViewResult) => {
      hilog.info(0x0000, 'testTag', 'Succeeded in updating liveView, result: %{public}s', JSON.stringify(liveViewResult));
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', 'Failed to update liveView: %{public}d %{public}s', err.code, err.message);
    });
  } catch (err) {
    let e: BusinessError = err as BusinessError;
    hilog.error(0x0000, 'testTag', 'Failed to update liveView: %{public}d %{public}s', e.code, e.message);
  }
}

async function buildWantAgent(): Promise<Want> {
  const wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
      {
        bundleName: 'xxx.xxx.xxx',
        abilityName: 'EntryAbility'
      } as Want
    ],
    actionType: wantAgent.OperationType.START_ABILITIES,
    requestCode: 0,
    actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
  };
  try {
    const agent = await wantAgent.getWantAgent(wantAgentInfo);
    return agent;
  } catch (e) {
    const err: BusinessError = e as BusinessError;
    hilog.error(0x0000, 'testTag', 'Failed to get wantAgent: %{public}s', err.message);
    throw e as Error;
  }
}

liveViewManager.stopLiveView

stopLiveView(liveView: LiveView): Promise<LiveViewResult>

结束实况窗,使用Promise异步返回结果。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

参数:

参数名

类型

必填

说明

liveView

LiveView

是

一个实况窗实例。对于非必填字段,若无特殊说明,则不携带时默认继承上一次的状态。

返回值:

类型

说明

Promise<LiveViewResult>

Promise对象,返回结束实况窗的结果。

错误码:

以下错误码的详细介绍请参见ArkTS API错误码。

错误码ID

错误信息

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1003500001

Internal error.

1003500002

Marshalling or unmarshalling error.

1003500003

Failed to connect service.

1003500004

LiveView is not enabled.

1003500008

Over max number liveViews per second.

1003500009

The liveView does not exist.

1003500010

The liveView has ended.

1003500011

The liveView sequence is incorrect.

示例:
import { liveViewManager } from '@kit.LiveViewKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { Want, wantAgent } from '@kit.AbilityKit';

async function stopLiveView(): Promise<void> {
  try {
    // 定义要结束的liveView
    let liveView: liveViewManager.LiveView = {
      id: 123,
      event: "PICK_UP",
      sequence: 3,
      isMute: false,
      liveViewData: {
        primary: {
          title: "餐品已备好",
          content: [
            { text: "请前往" }, 
            { text: "一号窗口", textColor: "#FFFF0000" }
          ],
          keepTime: 1,
          clickAction: await buildWantAgent(),
          extensionData: {
            text: "待取餐",
            type: liveViewManager.ExtensionType.EXTENSION_TYPE_COMMON_TEXT
          },
          layoutData: {
            layoutType: liveViewManager.LayoutType.LAYOUT_TYPE_PICKUP,
            title: "取餐码",
            content: "72988",
            underlineColor: "#FFFF0000",
            descPic: "coffee.jpg"
          }
        },
        capsule: {
          type: liveViewManager.CapsuleType.CAPSULE_TYPE_TEXT,
          status: 1,
          icon: "coffee.jpg",
          title: "待取餐",
          content: "取餐码:72988",
          backgroundColor: "#FF308977"
        }
      }
    };

    liveViewManager.stopLiveView(liveView).then((liveViewResult: liveViewManager.LiveViewResult) => {
      hilog.info(0x0000, 'testTag', 'Succeeded in stopping liveView, result: %{public}s', JSON.stringify(liveViewResult));
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', 'Failed to stop liveView: %{public}d %{public}s', err.code, err.message);
    });
  } catch (err) {
    let e: BusinessError = err as BusinessError;
    hilog.error(0x0000, 'testTag', 'Failed to stop liveView: %{public}d %{public}s', e.code, e.message);
  }
}

async function buildWantAgent(): Promise<Want> {
  const wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
      {
        bundleName: 'xxx.xxx.xxx',
        abilityName: 'EntryAbility'
      } as Want
    ],
    actionType: wantAgent.OperationType.START_ABILITIES,
    requestCode: 0,
    actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
  };
  try {
    const agent = await wantAgent.getWantAgent(wantAgentInfo);
    return agent;
  } catch (e) {
    const err: BusinessError = e as BusinessError;
    hilog.error(0x0000, 'testTag', 'Failed to get wantAgent: %{public}s', err.message);
    throw e as Error;
  }
}

liveViewManager.getActiveLiveView

getActiveLiveView(id: number): Promise<LiveView>

获取活动的liveView,使用Promise异步返回结果。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

参数:

参数名

类型

必填

说明

id

number

是

实况窗的id。

返回值:

类型

说明

Promise<LiveView>

Promise对象,返回活动的实况窗实例。

错误码:

以下错误码的详细介绍请参见ArkTS API错误码。

错误码ID

错误信息

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

1003500001

Internal error.

1003500002

Marshalling or unmarshalling error.

1003500003

Failed to connect service.

1003500009

The liveView does not exist.

示例:
import { liveViewManager } from '@kit.LiveViewKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 定义需要查询的实况窗id
const id = 1;
try {
  liveViewManager.getActiveLiveView(id).then((liveView: liveViewManager.LiveView) => {
    hilog.info(0x0000, 'testTag', 'Succeeded in getting active liveView, liveView is : %{public}s', JSON.stringify(liveView));
  }).catch((err: BusinessError) => {
    hilog.error(0x0000, 'testTag', 'Failed to get active liveView: %{public}d %{public}s', err.code, err.message);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to get active liveView: %{public}d %{public}s', e.code, e.message);
}

LiveView

实况窗对象参数,具体示例请见创建实况窗。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

id

number

是

实况窗唯一标识,取值范围为[-2147483648, 2147483647],由开发者自行生成。对应Push Kit中的activityId字段。

event

string

是

实况窗的应用场景。

  • TAXI:出行打车。
  • DELIVERY:即时配送(外卖、生鲜)。
  • FLIGHT:航班。
  • TRAIN:高铁/火车。
  • QUEUE:排队。
  • PICK_UP:取餐。
  • SCORE:赛事比分。
  • RENT:共享租赁。
  • TIMER:计时。
  • WORKOUT:运动锻炼。
  • NAVIGATION:导航。

使用对应场景需要申请权益,详情请参见开通实况窗权益。

sequence

number

否

支持实况窗消息更新保序能力,取值范围为[0, 2147483647],新的实况窗版本号需大于当前展示实况窗版本号,否则会更新失败。若不传入参数值,Live View Kit不会自动生成(此时,调用getActiveLiveView接口查询实况信息,返回结果中sequence:4294967295为无效值,该无效值不允许用来更新实况),也不会校验实况窗版本号。对应Push Kit中的version字段。

isMute

boolean

否

消息提醒方式。若您在创建或更改实况窗状态时不传入此字段,则始终默认静默提醒。

  • true:静默提醒。
  • false:铃声震动提醒。

timer

LiveViewTimer

否

实况窗计时器,展示时每秒刷新一次。

说明:

起始版本:5.0.0(12)。

配置了计时器后,可以在部分字段中使用占位符:${placeholder.timer},系统会将占位符替换为计时器。

当前支持使用占位符的字段:

liveViewData

LiveViewData

是

实况窗详细信息。

LiveViewTimer

实况窗计时器参数。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:5.0.0(12)

名称

类型

必填

说明

time

number

否

计时器初始值,单位为毫秒,大于等于0,默认为0。每秒刷新一次。

isCountdown

boolean

否

计时器是否为倒计时,默认为false。

  • true:计时器为倒计时类型
  • false:计时器为正计时类型

isPaused

boolean

否

计时器是否暂停,默认false。计时器暂停时,会显示暂停的那一秒。

LiveViewData

实况窗详细信息。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

primary

PrimaryData

是

卡片形态内容。

capsule

TextCapsule | TimerCapsule | ProgressCapsule

否

胶囊形态内容。

external

ExternalData

否

小折叠外屏形态内容。

PrimaryData

卡片形态参数。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

title

string

创建:是

更新/结束:否

固定区标题,若填值时不能为空,长度小于1024。

content

Array<RichText>

创建:是

更新/结束:否

固定区内容,若填值时不能为空。

  • 数组中所有对象的text字段字符串长度总和需小于1024。
  • 数组中对象不设置textColor字段时,文本颜色默认为#99000000;设置textColor字段时,所有拥有textColor字段的对象仅能设置同一种颜色。

keepTime

number

否

实况窗存档时间,在结束实况窗后,通知仍保留在通知中心的时长,默认0不保留,范围[0,3600]秒(s)。

clickAction

WantAgent

创建:是

更新/结束:否

点击实况窗默认动作,请调用wantAgent.getWantAgent()来构造。

extensionData

ExtensionData

否

辅助区内容。

layoutData

ProgressLayout | PickupLayout | FlightLayout | ScoreLayout | NavigationLayout | LayoutData

创建:是

更新/结束:否

扩展区数据。

说明:

从5.0.0(12)版本开始,新增支持参数类型NavigationLayout。

liveViewLockScreenPicture

string | image.PixelMap

否

锁屏沉浸实况窗大图样式在指定路径下的文件名。传入实际存在的图片时,用户在锁屏下点击实况胶囊中的应用图标、长按胶囊内容或长按卡片内容,会进入沉浸态,展示大图。不传入或传入图片不存在时,用户点击行为不会进入沉浸态。

  • string类型的取值为在“/resources/rawfile”路径下的文件名,长度最大为256

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 建议使用大小约为1000*1000的图片,不支持GIF格式的图片文件。
说明:

起始版本:5.0.0(12)。

liveViewLockScreenAbilityName

string

否

LiveViewLockScreenExtensionAbility(锁屏沉浸实况窗扩展Ability)的名称,仅创建实况窗时生效,传入时值不可为空,长度最大为128。若在创建实况窗时与liveViewLockScreenPicture同时传入,则仅本字段生效。

说明:

起始版本:5.0.0(12)。

liveViewLockScreenAbilityParameters

Record<string, string>

否

用户自定义向LiveViewLockScreenExtensionAbility(锁屏沉浸实况窗扩展Ability)传入的参数,填值时不能为空,key-value键值对最多50个,传入后可在ability的onSessionCreate()中,通过want.parameters获取。

说明:

起始版本:5.0.0(12)。

ExtensionData

辅助区参数。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

type

ExtensionType

否

辅助区显示类型。

text

string

创建:是(仅当type值为ExtensionType.EXTENSION_TYPE_COMMON_TEXT或ExtensionType.EXTENSION_TYPE_CAPSULE_TEXT时)

更新/结束:否

辅助区显示的文本信息,若填值时不能为空,长度小于128。

pic

string | image.PixelMap

创建:是(仅当type值为ExtensionType.EXTENSION_TYPE_PIC或ExtensionType.EXTENSION_TYPE_ICON时)

更新/结束:否

辅助区显示的图片,更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

clickAction

WantAgent

否

点击辅助区的跳转动作,请调用wantAgent.getWantAgent()来构造。

LayoutData

定义扩展区模板类型参数的基类。当layoutType为LayoutType.LAYOUT_TYPE_DEFAULT时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

layoutType

LayoutType

是

模板类型。

ProgressLayout

进度可视化模板扩展区参数,继承LayoutData。当layoutType为LayoutType.LAYOUT_TYPE_PROGRESS时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

progress

number

是

进度百分比,决定指示器在进度条中的位置,值范围:[0,100]。

color

string

否

进度条颜色,"#ARGB"16进制格式,长度为9。默认颜色为#FF317AF7。

backgroundColor

string

否

进度条背景颜色,"#ARGB"16进制格式,长度为9。默认颜色为#19000000,深色模式默认颜色#19FFFFFF。

indicatorType

IndicatorType

否

扩展区指示器小图标显示类型,默认不显示指示器小图标。

indicatorIcon

string | image.PixelMap

创建:是(仅当indicatorType值为IndicatorType.INDICATOR_TYPE_UP或IndicatorType.INDICATOR_TYPE_OVERLAY时)

更新/结束:否

进度条指示器图标,更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

lineType

LineType

否

扩展区进度条显示类型,默认为虚线进度。

nodeIcons

Array<string | image.PixelMap>

创建:是

更新/结束:否

进度条每个节点图标,数组长度范围为[2, 5],更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

PickupLayout

强调文本模板扩展区参数,继承LayoutData。当layoutType为LayoutType.LAYOUT_TYPE_PICKUP时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

title

string

创建/模板切换:是

更新/结束:否

扩展区标题,若填值时不能为空,长度小于128。

content

string

创建/模板切换:是

更新/结束:否

扩展区内容,若填值时不能为空,长度小于128。

underlineColor

string

否

扩展区内容下划线颜色,"#ARGB"16进制格式,长度为9,默认不显示下划线。

descPic

string | image.PixelMap

创建:是

更新/结束:否

扩展区右侧产品描述图,更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

FlightLayout

左右文本模板扩展区参数,继承LayoutData。当layoutType为LayoutType.LAYOUT_TYPE_FLIGHT时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

firstTitle

string

创建/模板切换:是

更新/结束:否

扩展区左侧标题,若填值时不能为空,长度小于128。

firstContent

string

创建/模板切换:是

更新/结束:否

扩展区左侧内容,若填值时不能为空,长度小于128。

lastTitle

string

创建/模板切换:是

更新/结束:否

扩展区右侧标题,若填值时不能为空,长度小于128。

lastContent

string

创建/模板切换:是

更新/结束:否

扩展区右侧内容,若填值时不能为空,长度小于128。

spaceIcon

string | image.PixelMap

创建:是

更新/结束:否

扩展区中间间隔图标,更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

isHorizontalLineDisplayed

boolean

否

是否显示扩展区分割线,默认显示分割线。

  • true:显示。
  • false:不显示。

additionalText

string

否

扩展区底部内容,若填值时不能为空,长度小于1024。

说明:

起始版本:5.0.0(12)。

ScoreLayout

赛事比分模板扩展区参数,继承LayoutData。当layoutType为LayoutType.LAYOUT_TYPE_SCORE时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

hostName

string

创建/模板切换:是

更新/结束:否

扩展区左侧名称,若填值时不能为空,长度小于128。

hostIcon

string | image.PixelMap

创建:是

更新/结束:否

扩展区左侧图标,更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

hostScore

string

创建/模板切换:是

更新/结束:否

扩展区左侧比分,若填值时不能为空,长度小于128。

guestName

string

创建/模板切换:是

更新/结束:否

扩展区右侧名称,若填值时不能为空,长度小于128。

guestIcon

string | image.PixelMap

创建:是

更新/结束:否

扩展区右侧图标,更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

guestScore

string

创建/模板切换:是

更新/结束:否

扩展区右侧比分,若填值时不能为空,长度小于128。

competitionDesc

string | Array<RichText>

创建/模板切换:是

更新/结束:否

扩展区中间上方描述文本,比赛介绍,若填值时不能为空。

  • 填string时,字符串长度需小于128。
  • 填Array<RichText>时:
    1. 数组中所有对象的text字段字符串长度总和需小于128。
    2. 数组中对象不设置textColor字段时,文本颜色默认为#99000000;设置textColor字段时,所有拥有textColor字段的对象仅能设置同一种颜色
说明:

从5.0.0(12)版本开始,新增支持入参类型Array<RichText>。

competitionTime

string

创建/模板切换:是

更新/结束:否

扩展区中间下方比赛时间,若填值时不能为空,长度小于128。

isHorizontalLineDisplayed

boolean

否

是否显示扩展区分割线,默认显示分割线。

  • true:显示。
  • false:不显示。

NavigationLayout

导航模板扩展区参数,继承LayoutData。当layoutType为LayoutType.LAYOUT_TYPE_NAVIGATION时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:5.0.0(12)

名称

类型

必填

说明

currentNavigationIcon

string | image.PixelMap

创建:是

更新/结束:否

当前导航方向。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名,图片大小不大于128KB。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

    若本地资源不存在,创建时失败,更新/结束时导航模板扩展区不更新。

  • 填image.PixelMap时,图片大小不大于30KB。

navigationIcons

Array<string | image.PixelMap>

否

导航方向的箭头集合图片,支持2-6个。创建时不传,则不展示扩展区。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名,图片大小不大于128KB。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

    若本地资源不存在,创建时失败,更新/结束时导航模板扩展区不更新。

  • 填image.PixelMap时,图片大小不大于30KB。

CapsuleData

定义实况胶囊基本属性的基类。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

type

CapsuleType

是

实况胶囊的类型。

status

number

是

实况胶囊的显示状态。

  • 1:胶囊显示。
  • -1:胶囊结束显示。

icon

string | image.PixelMap

创建:是

更新/结束:否

实况胶囊的图标,更新/结束不携带时显示上次的图片。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

backgroundColor

string

创建:是

更新/结束:否

实况胶囊的背景颜色,"#ARGB"16进制格式,长度为9。更新或结束未填时,继承上一次状态变更时的颜色。

不建议使用以下颜色:

  • #FF000000
  • #FFFFFFFF
  • #FFF1F3F5

TextCapsule

文本胶囊区参数,继承CapsuleData。当type为CapsuleType.CAPSULE_TYPE_TEXT时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

title

string

创建:是

更新/结束:否

实况胶囊的标题,若填值时不能为空,长度小于128。

content

string

否

实况胶囊的内容,若填值时不能为空,长度小于128。

TimerCapsule

计时器胶囊区参数,继承CapsuleData。当type为CapsuleType.CAPSULE_TYPE_TIMER时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

content

string

否

实况胶囊的内容,若填值时不能为空,长度小于128。

time

number

否

胶囊计时器初始值,每秒刷新一次,单位ms,默认为0。

isCountdown

boolean

否

是否显示倒计时器。

  • true:倒计时。
  • false:正计时(默认值)。

isPaused

boolean

否

胶囊计时器是否暂停,计时器暂停时,胶囊会显示暂停的那一秒。

  • true:暂停。
  • false:不暂停(默认值)。

ProgressCapsule

进度胶囊区参数,继承CapsuleData。当type为CapsuleType.CAPSULE_TYPE_PROGRESS时,使用此类型。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

max

number

否

进度条最大进度值,默认为1,范围为[1, 2147483647]。

progress

number

否

进度条当前进度值,默认为0,范围为[0, 2147483647]。进度的值为progress/max的比值。

indeterminate

boolean

否

进度显示类型,默认显示为数值占比。

  • true:百分比。
  • false:数值占比(默认)。

ExternalData

外屏形态模板参数。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

title

string

创建:是

更新/结束:否

外屏标题,若填值时不能为空,长度小于128。

content

Array<RichText>

创建:是

更新/结束:否

外屏内容,应用可以设置字符串中部分文本的颜色,若填值时不能为空。

  • 数组中所有对象的text字段字符串长度总和需小于128。
  • 数组中对象不设置textColor字段时,文本颜色默认为#99000000;设置textColor字段时,所有拥有textColor字段的对象仅能设置同一种颜色。

type

ExternalType

否

外屏背景样式类型,默认为背景色。

说明:

起始版本:5.0.0(12)。

backgroundColor

string

否

外屏背景颜色,"#RGB"16进制格式, 长度为7,默认颜色为#F1F3F5。

backgroundPicture

string | image.PixelMap

创建:是(仅当type为ExternalType.BACKGROUND_PICTURE时)

更新/结束:否(当type为ExternalType.BACKGROUND_PICTURE时,此参数生效)

外屏背景图片,更新/结束不携带时显示上次的图片。

说明:

起始版本:5.0.0(12)。

  • 填string时,取值为在“/resources/rawfile”路径下的本地资源文件名。

    示例:图片文件“icon.png”存放在应用的“/resources/rawfile”路径下,则取值为“icon.png”。

  • 填image.PixelMap时,图片大小不大于30KB。

RichText

富文本参数。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

必填

说明

text

string

是

文本内容。

textColor

string

否

文本颜色,"#ARGB"16进制格式,长度为9。不设置textColor时,文本颜色默认为#99000000;设置textColor时,数组中的所有对象仅能设置一种颜色。

LiveViewResult

实况窗结果。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

类型

说明

resultCode

number

实况窗结果码。

  • 0:成功。
  • 1:固定区更新/结束失败。
  • 2:辅助区更新/结束失败。
  • 3:扩展区更新/结束失败。
  • 4:胶囊更新/结束失败。
  • 5:外屏更新/结束失败。

message

string

实况窗结果信息。

LayoutType

扩展区类型,为枚举值。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

值

说明

LAYOUT_TYPE_DEFAULT

-1

不显示扩展区。

LAYOUT_TYPE_PROGRESS

3

进度可视化类型。

LAYOUT_TYPE_PICKUP

4

强调文本类型。

LAYOUT_TYPE_FLIGHT

5

左右文本类型。

LAYOUT_TYPE_SCORE

7

赛事类型。

LAYOUT_TYPE_NAVIGATION

8

导航类型。

说明:

起始版本:5.0.0(12)

ExtensionType

辅助区类型,为枚举值。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

值

说明

EXTENSION_TYPE_DEFAULT

0

不显示辅助区。

EXTENSION_TYPE_COMMON_TEXT

1

普通文本。

EXTENSION_TYPE_CAPSULE_TEXT

2

胶囊文本。

EXTENSION_TYPE_PIC

3

显示图片。

EXTENSION_TYPE_ICON

4

显示图标。

IndicatorType

指示器类型,为枚举值。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

值

说明

INDICATOR_TYPE_UNDISPLAYED

0

不显示指示器小图标。

INDICATOR_TYPE_UP

1

显示在进度线上方。

INDICATOR_TYPE_OVERLAY

2

显示覆盖在进度线上。

LineType

扩展区进度条类型,为枚举值。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

值

说明

LINE_TYPE_DOTTED_LINE

0

虚线进度。

LINE_TYPE_NORMAL_SOLID_LINE

1

实线进度。

LINE_TYPE_THICK_SOLID_LINE

2

粗实线进度。

CapsuleType

胶囊类型,为枚举值。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:4.1.0(11)

名称

值

说明

CAPSULE_TYPE_TEXT

1

文本胶囊。

CAPSULE_TYPE_TIMER

2

计时器胶囊。

CAPSULE_TYPE_PROGRESS

3

进度胶囊。

ExternalType

外屏背景样式类型,为枚举值。

模型约束:此接口仅可在Stage模型下使用。

系统能力:SystemCapability.LiveView.LiveViewService

起始版本:5.0.0(12)

名称

值

说明

BACKGROUND_COLOR

0

显示背景色。

BACKGROUND_PICTURE

1

显示背景图片。