【鸿蒙征文】使用 UTS 插件优雅实现“一键退出应用”功能

随着 uni-app 对鸿蒙开发的支持日益完善，我们现在可以轻松地使用一套代码同时发布到多个平台。不过，在开发鸿蒙（HarmonyOS）应用时，有些平台特有的功能需要我们通过 UTS 插件来调用原生能力。

本文将手把手教你如何创建一个 UTS 插件，并利用鸿蒙系统提供的原生接口，为你的 uni-app 应用添加一个“一键安全退出”的功能。

一、 UTS 插件的创建与命名

首先，我们需要在 uni-app 项目中创建一个专用于封装鸿蒙原生 API 的 UTS 插件。

1. 创建插件： 在 HBuilderX 中，找到你的项目目录下的 uni_modules 文件夹。
2. 右键点击 uni_modules -> 新建插件。
3. 命名插件： 为了与退出应用功能相关联，我们将插件命名为 ohos-exit-helper。
4. 选择类型： 选择插件类型为 uts。

创建完成后，你的项目结构会多出一个 uni_modules/ohos-exit-helper 目录。

二、 插件配置：在 uni 对象上注册新方法

接下来，我们需要修改插件的配置文件，告诉 uni-app 框架：我们要在全局的 uni 对象上注册一个名为 exitCurrentApp 的新方法。

打开 uni_modules/ohos-exit-helper/package.json 文件，找到 uni_modules 字段，并添加如下配置：

// 文件路径：uni_modules/ohos-exit-helper/package.json  

{  
  // ... 其他配置项保持不变 ...  
  "uni_modules": {  
    "uni-ext-api": {  
      "uni": {  
        "exitCurrentApp": "exitCurrentApp"   
      }  
    }  
  }  
}

三、 接口定义：确保类型安全（interface.uts）

为了在开发时获得更好的代码提示和类型检查，我们需要在 UTS 接口文件中定义新方法的签名。

打开 uni_modules/ohos-exit-helper/interface.uts 文件，扩展 Uni 接口，并声明我们的同步方法 exitCurrentApp()。

// 文件路径：uni_modules/ohos-exit-helper/interface.uts  

// ... (省略文件开头其他类型定义) ...  

/**  
 * 扩展全局 uni 接口，添加鸿蒙原生方法  
 */  
interface Uni {  
  /**  
   * 【鸿蒙专属】安全退出当前应用。  
   * * @example  
   * ```typescript  
   * uni.exitCurrentApp()  
   * ```  
   * @remark  
   * - 该接口需同步调用  
   * @uniPlatform { "harmony": { "osVer": "3.0" } }  
   */  
  exitCurrentApp(): void, // 【关键重构】方法签名定义  
}

四、 鸿蒙原生实现：UTS 代码编写（index.uts）

这是实现退出功能的核心步骤。我们需要在插件目录下创建鸿蒙平台专用的实现文件，并利用鸿蒙的 Ability Context 来执行退出操作。

1. 确认路径： 确保你在插件目录下创建了 app-harmony 文件夹和 index.uts 文件：
uni_modules/ohos-exit-helper/app-harmony/index.uts

2. 编写代码： 写入以下代码。我们引入了 @ohos.app.ability.common 模块，并使用 context.terminateSelf() 这一原生方法来实现退出。

// 文件路径：uni_modules/ohos-exit-helper/app-harmony/index.uts  

// 引入鸿蒙 Ability 相关的公共模块  
import AbilityCommon from '@ohos.app.ability.common';   
import hiLog from '@ohos.hilog'; // 引入日志模块，便于调试  

/**  
 * 导出【鸿蒙实现】退出当前应用的功能  
 * * @returns {void}  
 */  
export function exitCurrentApp(): void { // 【关键重构】导出函数名  
  // 1. 获取当前 UIAbility 的上下文对象  
  // getContext() 是 uni-app UTS 提供的全局函数，用于获取原生上下文  
  const appAbilityContext = getContext() as AbilityCommon.UIAbilityContext;  

  // 2. 调用 terminateSelf() 方法来终止 Ability  
  appAbilityContext.terminateSelf();  

  // 3. 打印日志（重构日志变量名和内容）  
  const exitLogTag: string = "APP_CONTROL_LOG";  
  const statusMessage: string = "Application is shutting down gracefully via UTS plugin.";  

  hiLog.info(0x0001, exitLogTag, statusMessage);  
}

五、 在 uni-app 页面中调用插件

至此，我们的鸿蒙退出插件已经完成。最后一步，是在你的 uni-app 页面中引入并使用它。

你可以在任何 .vue、.uvue`` 文件的<script lang="uts">` 块中调用此功能。

<template>  
  <view class="page-container">  
    <image class="app-logo" src="/static/logo.png"></image>  
    <text class="instruction-text">点击下方按钮，使用 UTS 实现鸿蒙应用退出。</text>  
    <view class="button-area">  
      <button class="exit-button" @click="handleAppExit">安全退出应用</button>  
    </view>  
  </view>  
</template>  

<script lang="uts">  

  import { exitCurrentApp } from "@/uni_modules/ohos-exit-helper"   

  export default {  
    data() {  
      return {  
        pageTitle: 'UTS退出功能演示',   
      }  
    },  
    methods: {  
      /**  
       * 处理点击退出按钮的逻辑方法  
       */  
      handleAppExit() { //   
        console.log("准备调用鸿蒙原生退出功能...");  
        // 调用我们插件中导出的退出函数  
        exitCurrentApp();   
      }  
    }  
  }  
</script>  

<style>  
  .page-container {  
    display: flex;  
    flex-direction: column;  
    align-items: center;  
    justify-content: center;  
    padding-top: 150px;  
    background-color: #f7f7f7;  
  }  
  .app-logo {  
    height: 180rpx;  
    width: 180rpx;  
    margin-bottom: 60rpx;  
  }  
  .instruction-text {  
    font-size: 34rpx;  
    color: #333333;  
    margin-bottom: 40rpx;  
  }  
  .exit-button {  
    width: 70%;  
    height: 90rpx;  
    line-height: 90rpx;  
    background-color: #007aff; /* 鸿蒙常用主色调 */  
    color: white;  
    font-size: 36rpx;  
    border-radius: 12rpx;  
    border: none;  
  }  
</style>

六、 运行与测试

现在，你可以运行你的 uni-app 项目到鸿蒙模拟器或真机上。

点击页面上的“安全退出应用”按钮，如果应用顺利关闭，那么恭喜你，你的第一个 UTS 鸿蒙插件就开发成功了！

通过这个示例，我们不仅学会了如何实现退出功能，更掌握了 uni-app 中 UTS 插件的基本开发流程，这是你深度学习鸿蒙原生能力的关键一步！