鸿蒙OS Ability AbilitySlice

作为使用 Page 模板的 Ability 的基本单位 ，AbilitySlice 为服务逻辑和 UI 显示提供了带有载体的功能。

一个能力可以有多个能力切片。您必须重写 Ability＃onStart（Intent）方法以指定默认的能力切片。通过使用 Ability＃setMainRoute（String）指定此默认路由。

您可以继承 AbilitySlice 类来实现自己的能力切片，并在 onStart（ohos.aafwk.content.Intent）方法中设置其 UI 。可以使用 setUIContent（ohos.agp.components.ComponentContainer）或setUIContent（int）来设置 UI 。通常，在功能切片的整个生命周期中，只需设置一次 UI。示例代码：

 public class MyAbilitySlice extends AbilitySlice {
     protected void onStart(Intent intent) {
         super.onStart(intent);
         // setup UI content from a layout resource
         setUIContent(R.res.layout);
     }
 }

您可以使用 present（ohos.aafwk.ability.AbilitySlice，ohos.aafwk.content.Intent）方法来呈现新的能力切片，也可以使用 startAbility（ohos.aafwk.content.Intent）方法来启动新能力。

能力切片必须始终托管在一个能力中，并且其生命周期会随着能力的变化而变化。功能片还具有其独立的生命周期更改，该更改在功能片切换期间发生。

注意：在大多数情况下，您负责创建和维护能力切片实例。但是，系统会在某些情况下创建实例。例如，系统在能力的首次启动期间创建能力切片实例。这要求所有 AbilitySlice 子类都具有默认的无参数构造函数。根据 Java 的定义，仅当您未显式声明参数化构造函数时，编译器才会为该类提供默认的无参数构造函数。因此，在覆盖 AbilitySlice 子类时，如果您的实现具有参数化构造函数，则必须显式声明一个无参数构造函数。

使用页面模板输入能力

您可以指定多个动作条目和一个功能的默认主条目。每个条目代表功能和该功能可以提供的 UI。启动一项功能后，系统会将已转移“ Intent”中的“操作”字段与定义的条目进行匹配。如果找到指定的能力片，则系统将启动它。如果转移未指定的操作字段被Intent在被转让或动作字段Intent不匹配所定义的任何条目，则显示默认能力切片。

以下代码显示了如何将条目设置为能力：

 public class MainAbility extends Ability {
     public void onStart(Intent intent) {
         super.onStart(intent);
         // set the main entry
         setMainRoute(MainSlice.class.getName());

         // add action for ability
         addActionRoute("action.pay", PaySlice.class.getName());
         addActionRoute("action.scan", ScanSlice.class.getName());
     }
 }

 

前面的代码仅定义运行时的入口路由。要将能力的功能暴露给其他能力，必须在配置文件 config.json中 注册操作字段。示例代码：

 {
     "module":{
         ...
         "abilities":[
           {
               ...
               "description": "Main ability of hiworld",
               "name": ".MainAbility",
               "label": "main ability",
               "icon": "main-ability.png",
               "type": "page",
               "visible": true,
               "orientation": "unspecified",
               "launch-mode": "standard",
               "skills"[
                   {
                       "actions":[
                           "action.pay",
                           "action.scan"
                       ]
                   }
               ]
               ...
           }
         ]
         ...
     }
 }

 

以上述方式注册受支持的动作后，其他能力可以通过指定动作使用您的能力，并直接打开相应的能力片。示例代码：

     Intent intent = new Intent();
     Operation operation = new Intent.OperationBuilder()
             .withAction("action.pay")
             .withDeviceId("")
             .withBundleName("xxx")
             .withAbilityName("yyy")
             .build();
     intent.setOperation(operation);
     startAbility(intent);

 

AbilitySlice 生命周期

能力切片的生命周期与承载它的能力有关。功能片具有与宿主功能相同的生命周期状态和生命周期回调方法。异能的生命周期状态一旦更改，其异能切片就会发生相同的变化，并调用相同的回调方法。功能切片也可以具有其独立的生命周期更改。在切换能力中的能力切片期间会发生此独立更改。但是，这样的切换不会影响宿主能力的生命周期。

能力切片具有以下四个生命周期状态：

• 初始：能力切片已加载到内存中，但未运行。它是所有能力切片的初始状态。
• 不活跃：能力切片已加载并执行，但不是交互式的。通常，在能力切片变为 ACTIVE 或 Background 之前是中间状态。在此状态下功能切片的 UI 可能可见，但无法接收输入事件。
• 活动：能力切片可见且具有交互性。认为能力切片具有焦点。
• 背景：能力切片是不可见的。如果宿主能力也处于后台，则在内存不足的情况下会破坏能力和能力切片。

与功能类似，功能切片提供以下生命周期回调方法。您可以覆盖它们。

  public class MainAbilitySlice extends AbilitySlice {
      protected void onStart(Intent intent);

      protected void onActive();

      protected void onInactive();

      protected void onForeground(Intent intent);

      protected void onBackground();

      protected void onStop();
  }

 

下图显示了能力切片的完整生命周期。一个能力切片在任何时候都只能处于一种状态。并非所有州都支持直接过渡。

注意：onStart（ohos.aafwk.content.Intent）方法在整个生命周期中只能调用一次。

下面提供了每种生命周期回调方法的含义以及一些最佳实践建议。

• onStart（ohos.aafwk.content.Intent）：必须为 UI 初始化设置实现此方法，例如 setUIContent（int)。在整个生命周期中只能调用一次此方法。调用方可以使用Intent类携带一些自定义的键值，并通过intent提供的方法获取这些参数。
• onActive（）：当功能片返回活动状态时，将调用此方法。回调之后，UI 是交互式的。
• onInactive（）：当能力切片被完全或部分覆盖时，将调用此方法。回调后，UI 不交互式。
• onForeground（ohos.aafwk.content.Intent）（）}：当功能片返回到前景时，将调用此方法。可以在回调中恢复或初始化应用程序的交互逻辑。如果在能力切片返回到前景时需要指定新的自定义参数，则可以传输新的Intent参数。
• onBackground（）：当能力切片进入背景时，将调用此方法。在这种状态下，您不能长时间执行后台任务，因为系统可能会随时停止后台程序的运行。
• onStop（）：调用此方法以销毁能力切片。您可以使用此方法回收资源。

在能力切片之间切换

您可以使用 present（ohos.aafwk.ability.AbilitySlice，ohos.aafwk.content.Intent）方法呈现新的能力切片，并使用Intent传输自定义参数。示例代码：

     Button button = new Button(this);
     button.setClickedListener(listener -> {
         AbilitySlice targetSlice = new MyAbilitySlice();
         Intent intent = new Intent();
         intent.setParam("value", 10);
         present(targetSlice, intent);
     });

 

注意：一个能力中最多可以同时显示 1024 个能力切片。如果尝试显示第 1025 个异能切片，系统将强制使该异能崩溃。为了避免这种情况，如果需要同时显示大量能力切片，则必须改进代码。

领域摘要

构造器摘要

方法总结

构造器详细信息

能力切片

公共 AliceSlice（）

方法细节

onStart

受保护的 void onStart（Intent intent）

开始功能切片时回调。使用 intent 参数传送启动信息。

您必须为每个功能切片覆盖此方法，并使用 setUIContent（int）或setUIContent（ohos.agp.components.ComponentContainer）方法来设置 UI。

在能力切片的整个Lifecycle中只能调用一次此方法。因此，建议您使用此方法来实现初始化，例如，初始化计时器或定义全局对象。

参数：

活跃

protected void onActive()

回叫时的能力片进入 ACTIVE 状态。

能力切片中的UI ACTIVE 状态已获得焦点和是交互式的。

不活动时

protected void onInactive()

当功能片进入 INACTIVE 状态时回调 。

INACTIVE 是中间状态，并且可以立即改变到 ACTIVE 或背景。在此状态下，功能片的 UI 可能可见，但不是交互式的。建议您不要使用此方法来触发复杂的服务逻辑。

在前景上

protected void onForeground(Intent intent)

当能力片的状态从背景变为不 活动时回调 。

能力切片返回到前景。您可以使用此方法来实现重新初始化或通过使用 intent 参数来调整 UI。

参数：

在背景上

protected void onBackground()

技能片进入背景状态时回调 。

处于背景状态的能力切片的用户界面是不可见的，并且不是交互式的。建议您使用此方法停止或释放资源。

停止

protected void onStop()

在摧毁能力片之前回叫。

功能切片调用 Terminate（）方法后，将回调此方法。您可以使用此方法回收资源。

能力结果

protected void onAbilityResult（int requestCode，int resultCode，Intent resultData）

在调用 startAbilityForResult（ohos.aafwk.content.Intent，int）以启动功能并返回结果时调用。

此方法提供的功能与该功能的Ability＃onAbilityResult（int，int，Intent）方法相同。

参数：

也可以看看：

startAbilityForResult（Intent，int）

结果

protected void onResult（int requestCode，Intent resultIntent）

返回 presentForResult（ohos.aafwk.ability.AbilitySlice，ohos.aafwk.content.Intent，int）方法的结果时 回调。

当调用presentForResult（ohos.aafwk.ability.AbilitySlice，ohos.aafwk.content.Intent，int）以启动新的功能片时，销毁功能片时将返回执行结果。您可以重写此方法来处理结果。

参数：

也可以看看：

presentForResult（AbilitySlice，Intent，int），setResult（Intent）

方向改变

受保护的 void onOrientationChanged（（AbilityInfo.DisplayOrientation displayOrientation）

当屏幕的显示方向改变时回调。

当显示方向改变时，您可以重写此方法以实现您的逻辑。默认情况下，更改显示方向时不执行任何操作。

参数：

onBackPressed

protected void onBackPressed（）

当按下返回键时回叫。

默认实现会破坏能力切片。您可以覆盖此方法。

按下按键

public boolean onKeyDown（int keyCode，KeyEvent keyEvent）

按下键时调用。当 AbilitySlice 中的任何组件获得焦点时，将首先处理该组件的按下事件。如果为组件的按下事件触发的回调返回 true，则不会调用此回调。此回调的默认实现不执行任何操作，并返回 false。

参数：

返回值：

如果已处理此事件且将不进一步传递，则返回 true；否则，返回 false。如果未处理此事件，则应返回 false并应将其传递给其他处理程序。

也可以看看：

onKeyUp（int，ohos.multimodalinput.event.KeyEvent）

在关键

public boolean onKeyUp（int keyCode，KeyEvent keyEvent）

释放键时调用。当 AbilitySlice 中的任何组件获得焦点时，将首先处理该组件的按键事件。如果为组件的按键事件触发的回调返回 true，则不会调用此回调。此回调的默认实现不执行任何操作，并返回 false。

参数：

返回值：

如果已处理此事件且将不进一步传递，则返回 true；否则，返回 false。如果未处理此事件，则应返回false并应将其传递给其他处理程序。

也可以看看：

onKeyDown（int，ohos.multimodalinput.event.KeyEvent）

字符串

公共string toString（）

提供 impl 和相应的切片信息，以方便人类阅读。

覆写：

类 Object中的toString

返回值：

字符串格式的信息。

获取窗口

公共Window getWindow（）

获取与当前能力对应的窗口。

此方法提供的功能与 Ability＃getWindow（）方法相同。

返回值：

返回与当前能力相对应的窗口。

获取布局参数

public WindowManager.LayoutConfig getLayoutParams（）

获取能力的窗口布局参数。必须为所有功能的窗口设置布局参数。为父窗口提供了这些参数，以指定如何布置当前功能的窗口。

此方法提供的功能与 Ability＃getLayoutParams（）方法相同。

返回值：

返回能力的窗口布局参数；如果未设置布局参数，则返回null。

设置布局参数

public void setLayoutParams（WindowManager.LayoutConfig 参数）

设置功能的窗口布局参数。为父窗口提供了这些参数，以指定如何布置当前功能的窗口。

此方法提供的功能与 Ability＃setLayoutParams（LayoutConfig）方法相同。

参数：

设置环境模式

public void setIsAmbientMode（boolean isEnabled）

设置窗口的输入 AOD 模式

参数：

设置UI内容

public final void setUIContent（int layoutRes）

通过使用布局资源 ID 来扩大布局资源。

参数：

也可以看看：

setUIContent（ComponentContainer）

设置UI内容

public void setUIContent（（ComponentContainer componentContainer）

通过使用 ComponentContainer来膨胀 UI 控件 。

您可以创建一个包含多个组件的 ComponentContainer 实例。

参数：

也可以看看：

setUIContent（int）

按ID查找组件

public Component findComponentById（int resID）

根据资源 ID 在 XML 文件中查找组件。

参数：

返回值：

如果找到记录，则返回与 ID 对应的组件；否则返回 null。

当下

public final void present（AbilitySlice targetSlice，Intent intent）

提供另一个能力切片，可以是尚未开始的能力切片或宿主能力中的现有能力切片。

您可以使用 Intent对象传递必需的信息。

仅在以下情况下可以调用此方法：

• 主机能力在 ACTIVE 状态。
• 目标能力切片未启动或破坏。
• 宿主技能中的技能片数不超过 1024。

参数：

也可以看看：

presentForResult（AbilitySlice，Intent，int）

呈现结果

public final void presentForResult（AbilitySlice targetSlice，Intent intent，int requestCode）

呈现另一个能力切片，并通过调用 setResult（ohos.aafwk.content.Intent） 返回目标能力切片的结果集 。

您可以使用 Intent 对象传递必需的信息。

仅在以下情况下可以调用此方法：

• 目前的能力片的主机能力在 ACTIVE 状态。
• 目标能力切片未启动或破坏。
• 主持人能力中有1024个或更少的能力切片。

参数：

也可以看看：

setResult（Intent），onResult（int，Intent）

设定结果

public final void setResult（Intent resultData）

设置销毁能力切片时要返回的数据。

当能力切片调用 Terminate（）方法时，当前方法设置的结果数据将传输到调用方。

参数：

也可以看看：

presentForResult（AbilitySlice，Intent，int），onResult（int，Intent）

终止

公共最终无效终止（）

摧毁当前能力切片。

当前能力切片调用此方法销毁自身时，由 setResult（ohos.aafwk.content.Intent）设置的结果数据将返回给调用方。如果要销毁的片是其宿主能力的唯一片，则该能力也将被摧毁。否则，该能力将不会受到影响。

启动能力

public void startAbility（Intent intent）

开始一项新技能。

技能切片也可以使用此方法来启动新技能。与 Ability＃startAbility（Intent）方法的功能相似，系统会根据intent参数的值从已安装的能力中定位目标能力，然后启动它。

参数：

启动能力

public void startAbility（Intent intent，AbilityOptions 选项）

从选项开始新技能。

技能切片也可以使用此方法来启动新技能。与 Ability＃startAbility（Intent，AbilityOptions）方法的功能相似，系统会根据 intent 参数的值从已安装的能力中定位目标能力，然后启动它。

参数：

开始结果的能力

public void startAbilityForResult（Intent intent，int requestCode）

启动一个异能并在该异能被销毁时返回执行结果。

此方法提供的功能与 Ability＃startAbilityForResult（Intent，int）方法相同。

参数：

也可以看看：

onAbilityResult（int，int，Intent）

停止能力

public final boolean stopAbility（Intent intent）throws IllegalArgumentException，IllegalStateException

破坏使用服务模板的能力。

此方法提供的功能与 Ability＃stopAbility（Intent）方法相同。

指定者：

接口ContextstopAbility

覆写：

stopAbility 类 AbilityContext

参数：

返回值：

如果成功销毁了使用服务模板的能力，则返回 true；否则，返回 true。否则返回 false。

Throws：

也可以看看：

Context.stopAbility（Intent）

终止能力

公共无效 terminateAbility（）

破坏主机能力。

此方法提供的功能与 Ability＃terminateAbility（）方法相同。

指定者：

接口 Context中的 terminateAbility

覆写：

terminateAbility 类 AbilityContext

也可以看看：

Context.terminateAbility（）

连接能力

public final boolean connectAbility（Intent intent，IAbilityConnection conn）throws IllegalArgumentException，IllegalStateException

将主持人能力与使用服务模板的能力联系起来。

此方法提供的功能与 Ability＃connectAbility（Intent，IAbilityConnection）方法相同。

指定者：

接口Context connectAbility

覆写：

类 AbilityContext 中的connectAbility

参数：

返回值：

如果连接成功，则返回 true；否则，返回 false。否则返回 false。

Throws：

也可以看看：

Context.connectAbility（Intent，IAbilityConnection）

断开能力

public final void disconnectAbility（IAbilityConnection conn）throws IllegalArgumentException，IllegalStateException

将主机功能与使用服务模板的功能断开连接。

此方法提供的功能与 Ability＃disconnectAbility（IAbilityConnection）方法相同。

指定者：

接口ContextdisconnectAbility

覆写：

disconnectAbility 类 AbilityContext

参数：

Throws：

也可以看看：

Context.disconnectAbility（IAbilityConnection）

继续能力

public final boolean connectAbility​(Intent intent, IAbilityConnection conn) throws IllegalArgumentException, IllegalStateException

Connects the host ability to an ability that uses the Service template.

将主机功能迁移到同一分布式网络上的另一台设备。

此方法提供的功能与 Ability＃continueAbility（）方法相同。

Throws：

继续能力

公共无效的 continuAbility （string deviceId）Throws IllegalStateException，UnsupportedOperationException

将主机功能迁移到同一分布式网络上的给定设备。

此方法提供的功能与 Ability＃continueAbility（String）方法相同。

参数：

Throws：

连续能力可逆

公共无效的 continueAbilityReversible（）Throws IllegalStateException，UnsupportedOperationException

以可逆的方式将主机功能迁移到同一分布式网络上的另一台设备，该功能允许将该功能通过 reverseContinueAbility（）迁移回本地设备 。

此方法提供的功能与 Ability＃continueAbilityReversible（） 方法相同。

Throws：

连续能力可逆

public void continueAbility (String deviceId) throws IllegalStateException，UnsupportedOperationException

以可逆的方式将主机功能迁移到同一分布式网络上的另一台设备，该功能允许将该功能通过reverseContinueAbility（）迁移回本地设备 。

此方法提供的功能与 Ability＃continueAbilityReversible（String）方法相同。

参数：

Throws：

反向连续能力

public boolean reverseContinueAbility（）throws IllegalStateException，UnsupportedOperationException

将主机功能从同一分布式网络上的另一台设备迁移回本地设备。

此方法提供的功能与 Ability＃reverseContinueAbility（） 方法相同。

返回值：

如果迁移请求成功，则返回 true；否则，返回 true。否则返回 false。

Throws：

获取延续状态

public final ContinuationState getContinuationState() throws UnsupportedOperationException

获得宿主能力的迁移状态。

此方法提供的功能与 Ability＃getContinuationState（）方法相同。

返回值：

返回迁移状态。

Throws：

获取原始 DeviceId

公共最终string getOriginalDeviceId（）Throws UnsupportedOperationException

获取从其迁移主机功能的源设备的 ID。

此方法提供的功能与 Ability＃getOriginalDeviceId（）方法相同。

返回值：

返回源设备 ID。

Throws：

设置显示方向

public void setDisplayOrientation(AbilityInfo.DisplayOrientation requestedOrientation)

设置主持人能力的显示方向。

After you change the display orientation using this method, the system calls back the onOrientationChanged(ohos.bundle.AbilityInfo.DisplayOrientation) method. If requestedOrientation is set to DisplayOrientation#UNSPECIFIED, the display orientation of the ability depends on the system setting.

如果某个能力处于前台，该设置将立即生效。否则，该设置将在该异能返回到前景时生效。

指定者：

接口 Context中的setDisplayOrientation

覆写：

类 AbilityContext中的setDisplayOrientation

参数：

也可以看看：

Context.setDisplayOrientation（AbilityInfo.DisplayOrientation）

获取能力形式异步

public boolean acquisitionAbilityFormAsync（Intent intent，AbilityForm.OnAcquiredCallback createdCallback）

请求目标能力提供的 AbilityForm 实例。

此方法异步执行。获取 AbilityForm 实例后，系统将回调 OnAcquiredCallback 方法。如果目标功能不使用 Page 模板或不提供 AbilityForm 功能，则不会通知呼叫者。

要使用此方法，您的应用程序必须具有 ohos.permission.REQUIRE_FORM 权限。该权限仅适用于系统应用程序。如果呼叫者没有权限，则返回 false。

参数：

返回值：

如果请求发送成功，则返回 true；否则，返回 false。否则返回 false。

释放能力表

公共无效发布 AbilityForm（AbilityForm 能力表单）

释放主机能力的指定 AbilityForm 实例。

参数：

获取生命周期

public final Lifecycle getLifecycle()

获取当前能力切片的 Lifecycle对象。

指定者：

getLifecycle 接口 ILifecycle

返回值：

返回Lifecycle对象。

获得能力

public final Ability getAbility()

获得该切片所属的能力。

返回值：

归还能力。