HarmonyOS开发者社区

有奖活动
HarmonyOS开发者社区 uni-app 通过 UTS 插件实现鸿蒙原生组件嵌入

uni-app 通过 UTS 插件实现鸿蒙原生组件嵌入

通过 UTS 插件和鸿蒙原生组件的结合，开发者可以在 uni-app 中高效地扩展鸿蒙平台的能力。本文以按钮组件为例，演示了从组件注册到页面调用的完整流程，帮助开发者快速掌握鸿蒙原生组件的嵌入技巧。

egzosn

1205人浏览 · 2025-05-10 17:40:43
egzosn  ·  2025-05-10 17:40:43 发布

随着 uni-app 对鸿蒙系统的支持不断增强，开发者可以通过 UTS 插件 实现鸿蒙原生组件的嵌入与交互。从 HBuilderX 4.62 版本开始，uni-app 提供了对鸿蒙原生组件的同层渲染支持，开发者可以直接在 .ets 文件中定义原生组件，并通过 UTS 插件将其集成到 uni-app 项目中。

本文将以「自定义按钮组件」为例，详细讲解如何在鸿蒙系统中注册原生组件，并在 uni-app 中调用它。

开发步骤详解

1. 创建 UTS 插件结构
目录结构
uni_modules/
  └── wq-button-component/  ← 插件主目录
      ├── package.json      ← 插件配置文件
      ├── utssdk/
      │   ├── interface.uts   ← 接口定义
      │   └── app-harmony/
      │       └── index.uts   ← 鸿蒙实现(ETS 文件)
      └── pages/
          └── demo.vue      ← 演示页面
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
配置 package.json
{
  "uni_modules": {
    "uni-ext-api": {
      "uni": {
        "customButton": {
          "name": "customButton",
          "app": {
            "js": false,
            "arkts": true
          }
        }
      }
    }
  }
}
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
2. 在 ETS 文件中注册原生组件
ETS 实现代码
// uni_modules/wq-button-component/utssdk/app-harmony/index.ets
import { NativeEmbedBuilderOptions, defineNativeEmbed } from "@dcloudio/uni-app-runtime";

// 定义按钮组件的 BuilderOptions
interface ButtonBuilderOptions extends NativeEmbedBuilderOptions {
  label: string;
}

// 定义点击事件的详细信息
interface ButtonClickEventDetail {
  text: string;
}

// 原生按钮组件
@Component
struct ButtonComponent {
  @Prop label: string;
  onButtonClick?: Function;

  build() {
    Button(this.label)
      .width('100%')
      .height('100%')
      .onClick(() => {
        if (this.onButtonClick) {
          const detail: ButtonClickEventDetail = {
            text: 'test'
          };
          this.onButtonClick({ detail });
        }
      });
  }
}

// 构造函数，将参数传递给组件
@Builder
function ButtonBuilder(options: ButtonBuilderOptions) {
  ButtonComponent({
    label: options.label,
    onButtonClick: options?.on?.get('click')
  })
    .width(options.width)
    .height(options.height);
}

// 注册原生组件，标签名为 'button'
defineNativeEmbed('button', {
  builder: ButtonBuilder
});
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.
  • 20.
  • 21.
  • 22.
  • 23.
  • 24.
  • 25.
  • 26.
  • 27.
  • 28.
  • 29.
  • 30.
  • 31.
  • 32.
  • 33.
  • 34.
  • 35.
  • 36.
  • 37.
  • 38.
  • 39.
  • 40.
  • 41.
  • 42.
  • 43.
  • 44.
  • 45.
  • 46.
  • 47.
  • 48.
  • 49.
3. 在 uni-app 页面中调用组件
模板代码
<template>
  <view class="content">
    <embed 
      class="native-button" 
      tag="button" 
      :options="options" 
      @click="handleClick"
    ></embed>
  </view>
</template>

<script lang="uts">
export default {
  data() {
    return {
      options: {
        label: '点击我',
        width: 200,
        height: 50
      }
    };
  },
  methods: {
    handleClick(e) {
      console.log('按钮被点击，事件内容:', e.detail.text);
      this.options = {
        label: '已点击',
        width: 200,
        height: 50
      };
    }
  }
};
</script>

<style scoped>
.content {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
}

.native-button {
  width: 200px;
  height: 50px;
  margin: 10px auto;
}
</style>
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.
  • 20.
  • 21.
  • 22.
  • 23.
  • 24.
  • 25.
  • 26.
  • 27.
  • 28.
  • 29.
  • 30.
  • 31.
  • 32.
  • 33.
  • 34.
  • 35.
  • 36.
  • 37.
  • 38.
  • 39.
  • 40.
  • 41.
  • 42.
  • 43.
  • 44.
  • 45.
  • 46.
  • 47.
  • 48.
  • 49.

关键点解析

1. 原生组件注册流程
  • 使用 defineNativeEmbed 注册组件，指定标签名 tag 和构建函数 builder。
  • builder 函数接收参数并返回鸿蒙原生组件实例。
  • 通过 @Component 和 @Builder 装饰器定义组件结构和逻辑。
2. 事件传递机制
  • 原生组件的事件通过 on 属性注册，例如 onButtonClick。
  • 在 uni-app 页面中通过 @click 监听事件，并接收事件对象 e.detail.text。
3. 动态属性更新
  • 修改 options 对象的值(如 label)会触发组件更新。
  • 需要确保 options 是响应式数据(如 Vue 的 data)。

运行与调试

1. HBuilderX 配置
  1. 安装 HBuilderX 4.62+。
  2. 在菜单栏选择 运行 → 运行到手机或模拟器 → 运行到鸿蒙。
  3. 确保设备已开启 开发者选项 和 USB 调试。
2. DevEco Studio 验证
  • 查看日志输出，确认组件是否成功加载。
  • 检查按钮点击事件是否触发并更新标签文本。

注意事项

  1. ETS 文件限制
  • 鸿蒙原生组件仅支持定义在 .ets 文件中。
  • UTS 插件需通过 import 引入 .ets 文件。
  1. 权限声明 在 config.json 中添加必要权限：
{
  "plus": {
    "distribute": {
      "harmony": {
        "requestPermissions": [
          "ohos.permission.GET_BUNDLE_INFO"
        ]
      }
    }
  }
}
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  1. 上下文获取
  • getContext() 需确保在鸿蒙环境下可用。
  • 可封装兼容性处理逻辑，避免空指针异常。

扩展思考

1. 复用组件模式

通过 @Reusable 装饰器实现组件复用，优化性能：

@Reusable
@Component
struct ReusableButton {
  // 组件逻辑
}
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
2. 多类型组件注册

注册多个原生组件时，可使用不同标签名区分：

defineNativeEmbed('custom-button', { builder: CustomButtonBuilder });
defineNativeEmbed('custom-input', { builder: InputBuilder });
  • 1.
  • 2.

总结

通过 UTS 插件和鸿蒙原生组件的结合，开发者可以在 uni-app 中高效地扩展鸿蒙平台的能力。本文以按钮组件为例，演示了从组件注册到页面调用的完整流程，帮助开发者快速掌握鸿蒙原生组件的嵌入技巧。

# harmonyos # uni-app # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙开发零基础教程：理解鸿蒙 OS 架构，搞懂分布式软总线核心概念

avatar HarmonyOS开发者社区

Cangjie-TPC/editor4cj部署指南：HarmonyOS应用集成步骤

EditorKit是专为HarmonyOS设计的强大多语言代码编辑库，支持30+编程语言的语法高亮、代码补全、行号显示等核心功能。本文将详细介绍如何在HarmonyOS应用中快速集成和部署EditorKit，帮助开发者构建专业的代码编辑体验。## 环境准备### 系统要求- **操作系统**: HarmonyOS 3.0+- **开发工具**: Cangjie Studio 1.1.0...

avatar HarmonyOS开发者社区

ArkUI-X/arkui_for_ios：传输加密的端到端保护

在移动应用开发领域，数据传输安全一直是开发者面临的核心挑战。随着ArkUI-X框架将HarmonyOS的ArkUI扩展到iOS平台，如何在跨平台应用中实现端到端的传输加密保护成为关键问题。本文将深入探讨ArkUI-X在iOS平台上的安全传输机制，为开发者提供全面的安全实践指南。## ArkUI-X iOS适配层安全架构### 整体安全设计理念ArkUI-X采用分层安全架构，在iOS平台...

avatar HarmonyOS开发者社区
  • 浏览量 1205
  • 收藏 0
  • 0

所有评论(0)

查看更多评论 

egzosn

@cnzzs
已为社区贡献14条内容