鸿蒙（HarmonyOS）开发，如何引用本地模块文件

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

在鸿蒙（HarmonyOS）开发中，引用本地模块文件是模块化开发的核心能力。以下是从基础到高级，包含多种引用方式、实际示例和避坑技巧：

一、模块化基础概念

1. 模块类型

2. 关键配置文件

• oh-package.json5：声明模块依赖关系
• module.json5：模块能力声明

二、引用本地模块的5种方式

方式1：通过相对路径引用（同模块内）

// 文件结构
// entry/src/main/ets/
//   ├── pages/
//   │   └── Index.ets
//   └── utils/
//       └── Logger.ets

// Index.ets 中引用Logger工具
import { log } from '../utils/Logger'; // 相对路径

@Entry
@Component
struct Index {
  onPageShow() {
    log('页面加载'); // 调用Logger模块的方法
  }
}

适用场景：同一模块内的文件引用。

方式2：引用另一个本地模块（跨模块）

步骤1：配置依赖关系

在主模块的oh-package.json5中添加依赖：

// entry/oh-package.json5
{
  "dependencies": {
    "feature": "file:../feature" // 指向本地feature模块
  }
}

步骤2：导入并使用

// entry/src/main/ets/pages/Index.ets
import { NewsService } from 'feature/src/main/ets/service/NewsService';

@Entry
@Component
struct Index {
  private newsService: NewsService = new NewsService();

  build() {
    Button('获取新闻')
      .onClick(() => {
        this.newsService.fetchNews(); // 调用其他模块的方法
      })
  }
}

关键点：

• 路径格式为模块名/src/main/ets/...
• 需要先通过oh-package.json5建立依赖

方式3：引用静态共享包（.har文件）

步骤1：生成.har包

在模块目录执行：

npm run build  # 生成feature.har

步骤2：主模块引用har

// entry/oh-package.json5
{
  "dependencies": {
    "feature": "file:../feature/build/feature.har" // 指向har文件
  }
}

步骤3：导入har中的组件

import { CustomButton } from 'feature';

@Entry
@Component
struct Index {
  build() {
    Column() {
      CustomButton() // 使用har包中的组件
    }
  }
}

优势：模块代码被编译封装，保护源代码。

方式4：动态加载模块（API 9+）

// 动态导入feature模块的某个文件
import('feature/src/main/ets/utils/Calculator').then((module) => {
  const result = module.add(1, 2); // 调用动态加载的方法
});

适用场景：按需加载减少启动耗时。

方式5：通过$r引用资源文件

// 引用resources目录下的图片
Image($r('app.media.logo'))

// 引用其他模块的资源（需模块导出）
Image($r('feature.media.news_icon'))

资源配置：

resources/
  ├── base/
  │   ├── element/
  │   ├── media/    # 图片放这里
  │   └── profile/

三、完整项目结构示例 

MyApp/
├── entry/               # 主模块
│   ├── oh-package.json5 # 声明依赖feature和library
│   └── src/main/ets/
│       └── pages/...
├── feature/             # 功能模块
│   ├── oh-package.json5 # 声明依赖library
│   └── src/main/ets/
│       ├── service/
│       └── components/...
└── library/             # 静态共享包
    ├── build/library.har
    └── src/main/ets/
        └── utils/...

四、避坑指南

1. 路径错误解决方案

2. 真机调试技巧

// 打印所有已加载模块
console.log(require.context.keys()); 
// 输出示例：['@entry', '@feature']

3. 多模块资源冲突

若多个模块有同名资源：

// 明确指定模块名
$r('feature.media.icon') 
// 替代模糊引用
$r('app.media.icon')

五、高级技巧：模块间通信

1. 使用EventHub

// 发送方（feature模块）
import emitter from '@ohos.events.emitter';
emitter.emit({
  eventId: 'refresh_event',
  data: { msg: '数据更新' }
});

// 接收方（entry模块）
emitter.on('refresh_event', (data) => {
  console.log(data.msg); // 输出：数据更新
});

2. 导出Ability

在目标模块的module.json5中：

{
  "abilities": [{
    "name": "DataAbility",
    "srcEntry": "./ets/DataAbility.ets",
    "exported": true // 允许跨模块访问
  }]
}

六、总结