鸿蒙中 @entry 装饰器的作用

原创于 2025-12-20 06:30:00 发布 · 139 阅读

4 ·

CC 4.0 BY-SA版权

文章标签：

#鸿蒙 #harmonyos #华为 #entry #入口页面

鸿蒙专栏收录该内容

387 篇文章

订阅专栏

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

一、@entry 的核心作用

@entry 是应用入口组件的装饰器，标记该组件为应用的主入口页面。

将结构体标记为页面组件，代表一个完整的页面

@Entry装饰器用于标识一个自定义组件作为应用的入口页面。当应用启动时，系统会自动加载并渲染被@Entry标记的组件。
每个UIAbility（应用的能力单元）必须包含至少一个@Entry装饰的组件作为其根页面。

二、使用方式

1、在Stage模型开发中，@Entry必须与@Component联合使用。

// 1. 最简形式 - 标记入口组件
@Entry
@Component
struct Index {
  build() {
    // 首页UI内容
  }
}

// 2. 配合其他装饰器使用
@Entry
@Component
struct MyApp {
  @State private count: number = 0
  
  build() {
    Column() {
      Text('Hello World')
        .fontSize(50)
    }
  }
}

2、单一性 - 每个模块只能有一个 @Entry

// 错误：一个模块中有多个 @Entry
@Entry  // 第一个入口
@Component
struct Page1 {
  // ...
}

@Entry  // 编译错误：重复的 @Entry
@Component
struct Page2 {
  // ...
}




// 正确：只有一个 @Entry
@Entry
@Component
struct MainPage {
  // ...
}

@Component
struct OtherPage {
  // 普通页面，不是入口
  // ...
}

3、必需性 - UIAbility 必须加载 @Entry 组件

// Ability 中加载 Entry 组件
import UIAbility from '@ohos.app.ability.UIAbility'
import window from '@ohos.window'

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // 必须加载 @Entry 装饰的组件
    windowStage.loadContent('pages/Index', (err, data) => {
      // Index 页面必须使用 @Entry 装饰
    })
  }
}

// pages/Index.ets
@Entry  // 必须有 @Entry
@Component
struct Index {
  build() {
    // ...
  }
}

单页应用基础
- 一个应用可包含多个@Entry装饰的页面，通过路由机制实现页面跳转（如router.pushUrl）。
生命周期管理
- 被@Entry标记的组件会自动关联页面的生命周期回调（如onPageShow、onPageHide）。

注意：

@Entry只能修饰自定义组件（用@Component定义的结构体），不能用于普通函数或类
若未声明@Entry，应用将因缺少入口页面而无法启动

三、@entry 的参数配置

@Entry 支持可选参数：

// 1. 配置路由参数
@Entry({
  routeName: 'main',      // 路由名称
  storage: new LocalStorage(),  // 存储方式
  useSharedStorage: true   
})
@Component
struct Index {
  build() {
    // ...
  }
}

参数说明：

参数	类型	说明
`routeName`	string	页面路由名称(可用于命名路由跳转，比如：跨模块跳转等)
`storage`	LocalStorage	组件存储方式
`useSharedStorage`	boolean	控制是否使用共享的LocalStorage实例（默认值false）