# 构建第一个HarmonyOS应用（ArkTS）

> 说明
>
> 为确保运行效果，本文以使用[DevEco Studio 26.0.0 Release版本](https://developer.huawei.com/consumer/cn/download/)为例。

## 创建ArkTS工程

1. 若首次打开**DevEco Studio** ，请单击**Create Project** 创建工程。如果已经打开了一个工程，请在菜单栏选择**File** > **New** > **Create Project**来创建一个新工程。

2. 选择**Application** 应用开发（本文以应用开发为例，[Atomic Service](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/glossary#atomic-service元服务)对应为元服务开发），选择模板**Empty Ability** ，单击**Next**进行下一步配置。

   若开发者需要进行Native相关工程的开发，请选择**Native C++** 模板，更多模板的使用和说明请见[工程模板介绍](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-template)。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0c/v3/oNpacL_OR6S2hHW4zoyTTg/zh-cn_image_0000002803263163.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=E4DB7F2894257695079D2649F168A12C405507C00639F310FE96925E5467612E)
3. 进入配置工程界面，**Compatible SDK** 表示兼容的最低API Version，此处以选择**26.0.0** 为例，其他参数保持默认设置即可。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/37/v3/q2Dev1jZQ4WmstqWv2mFrg/zh-cn_image_0000002803223069.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=9A2A7ED59297206A0C010CD4BEAD4AC6335E7C25ADEDB32D79466CA25767AACA)
4. 单击**Finish**，工具会自动生成示例代码和相关资源，等待工程创建完成。

## ArkTS工程目录结构（Stage模型）

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5f/v3/1TlTx14xS_6ZMOv8H-xO0w/zh-cn_image_0000002774063356.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=02BA01A6C08B31F360E4153613F519907CE7A2BC651A9D87D788F1374F73C090)

* **AppScope > app.json5** ：应用的全局配置信息，详见[app.json5配置文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-file)。

* **entry** ：HarmonyOS工程模块，编译构建生成一个[HAP](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package)包。

  * **src > main > ets**：用于存放ArkTS源码。

  * **src > main > ets > entryability**：应用/服务的入口。

  * **src > main > ets > entrybackupability**：应用提供扩展的备份恢复能力。

  * **src > main > ets > pages**：应用/服务包含的页面。

  * **src > main > resources** ：用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等。关于资源文件，详见[资源分类与访问](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/resource-categories-and-access)。

  * **src > main > module.json5** ：[模块](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-glossary#module模块)配置文件。主要包含HAP包的配置信息、应用/服务在具体设备上的配置信息以及应用/服务的全局配置信息。具体的配置文件说明，详见[module.json5配置文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file)。

  * **build-profile.json5**：当前的模块信息 、编译信息配置项，包括buildOption、targets配置等。

  * **hvigorfile.ts**：模块级编译构建任务脚本。

  * **obfuscation-rules.txt** ：混淆规则文件。混淆开启后，在使用Release模式进行编译时，会对代码进行编译、混淆及压缩处理，保护代码资产。详见[开启代码混淆](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-build-obfuscation)。

  * **oh-package.json5**：用来描述包名、版本、入口文件（类型声明文件）和依赖项等信息。

* **oh_modules**：用于存放三方库依赖信息。

* **build-profile.json5**：工程级配置信息，包括签名signingConfigs、产品配置products等。其中products中可配置当前运行环境，默认为HarmonyOS。

* **hvigorfile.ts**：工程级编译构建任务脚本。

* **oh-package.json5**：主要用来描述全局配置，如：依赖覆盖（overrides）、依赖关系重写（overrideDependencyMap）和参数化配置（parameterFile）等。

## 构建第一个页面

1. 使用文本组件。

   工程同步完成后，在**Project** 窗口，单击**entry > src > main > ets > pages** ，打开**Index.ets**文件，将页面从RelativeContainer相对布局修改成Row/Column线性布局。

   针对本文中使用文本/按钮来实现页面跳转/返回的应用场景，页面均使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)和[Column](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-column)组件来组建布局。对于更多复杂元素对齐的场景，可选择使用[RelativeContainer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-relativecontainer)组件进行布局。更多关于UI布局的选择和使用，可见[如何选择布局](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-layout-development-overview#如何选择布局)。

   **Index.ets**文件的示例如下：

   ```ts
   // Index.ets
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World';

     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   ```

2. 添加按钮。

   在上述页面基础上，我们添加一个Button组件，作为按钮响应用户onClick事件，从而实现跳转到另一个页面。**Index.ets**文件的示例如下：

   ```ts
   // Index.ets
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World';

     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           // 添加按钮，以响应用户onClick事件
           Button() {
             Text('Next')
               .fontSize(30)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   ```

3. 在编辑窗口**右上角** 的侧边工具栏，单击**Previewer**，打开预览器。第一个页面效果如下图所示：

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/68/v3/mI71dEefTXSKsO4uqLgBvw/zh-cn_image_0000002773903380.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=90871C6B6AA7789AC6498D294E5DE3D86400421DFE9F307FA2D7E307FE33B423)

## 构建第二个页面

1. 创建第二个页面。

   * 新建第二个页面文件。在**Project** 窗口，打开**entry > src > main > ets** ，右键单击**pages** 文件夹，选择**New > ArkTS File** ，命名为**Second** ，单击**回车键**。可以看到文件目录结构如下：

     ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/59/v3/c_y5O787QtSXG4bAE1Dbkg/zh-cn_image_0000002803263165.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=64A54C23949C9BABF0D23C9690D79DC80583318DAA3EBCD1FD225CB916589C1E)
     > 说明
     >
     > 开发者也可以在右键单击**pages** 文件夹时，选择**New > Page** **> Empty Page** ，命名为**Second** ，单击**Finish**完成第二个页面的创建。使用此种方式则无需再进行下文中第二个页面路由的手动配置。
   * 配置第二个页面的路由。在**Project** 窗口，打开**entry > src > main > resources > base > profile**，在main_pages.json文件中的"src"下配置第二个页面的路由"pages/Second"。示例如下：

     ```json
     {
       "src": [
         "pages/Index",
         "pages/Second"
       ]
     }
     ```

2. 添加文本及按钮。

   参照第一个页面，在第二个页面添加Text组件、Button组件等，并设置其样式。**Second.ets**文件的示例如下：

   ```ts
   // Second.ets
   @Entry
   @Component
   struct Second {
     @State message: string = 'Hi there';

     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           Button() {
             Text('Back')
               .fontSize(30)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   ```

## 实现页面间的跳转

页面间的导航可以通过[页面路由router](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-router)来实现。页面路由router根据页面url找到目标页面，从而实现跳转。

如果需要实现更好的转场动效，推荐使用[Navigation](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-navigation-navigation)。

1. 第一个页面跳转到第二个页面。

   在第一个页面中，跳转按钮绑定onClick事件，单击按钮时跳转到第二页。**Index.ets**文件的示例如下：

   ```ts
   // Index.ets
   import { BusinessError } from '@kit.BasicServicesKit';

   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World';

     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           // 添加按钮，以响应用户onClick事件
           Button() {
             Text('Next')
               .fontSize(30)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
           // 跳转按钮绑定onClick事件，单击时跳转到第二页
           .onClick(() => {
             console.info(`Succeeded in clicking the 'Next' button.`)
             // 获取UIContext
             let uiContext: UIContext = this.getUIContext();
             let router = uiContext.getRouter();
             // 跳转到第二页
             router.pushUrl({ url: 'pages/Second' }).then(() => {
               console.info('Succeeded in jumping to the second page.')

             }).catch((err: BusinessError) => {
               console.error(`Failed to jump to the second page. Code is ${err.code}, message is ${err.message}`)
             })
           })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   ```

2. 第二个页面返回到第一个页面。

   在第二个页面中，返回按钮绑定onClick事件，单击按钮时返回到第一页。**Second.ets**文件的示例如下：

   ```ts
   // Second.ets
   import { BusinessError } from '@kit.BasicServicesKit';

   @Entry
   @Component
   struct Second {
     @State message: string = 'Hi there';

     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           Button() {
             Text('Back')
               .fontSize(30)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
           // 返回按钮绑定onClick事件，单击按钮时返回到第一页
           .onClick(() => {
             console.info(`Succeeded in clicking the 'Back' button.`)
             // 获取UIContext
             let uiContext: UIContext = this.getUIContext();
             let router = uiContext.getRouter();
             try {
               // 返回第一页
               router.back()
               console.info('Succeeded in returning to the first page.')
             } catch (err) {
               let code = (err as BusinessError).code;
               let message = (err as BusinessError).message;
               console.error(`Failed to return to the first page. Code is ${code}, message is ${message}`)
             }
           })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   ```

3. 打开**Index.ets** 文件，单击预览器中的![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a5/v3/qhSwHq96RFiEG44cJCciXQ/zh-cn_image_0000002803223071.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=8CD7BAF5A62E3C100A5EDE65410DD5DD9D3F8BF22B0C655E2099593792091A37)按钮进行刷新。效果如下图所示：

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/43/v3/vIy62azjTcidwsef942jMg/zh-cn_image_0000002774063358.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=F40FF21183FE70ABD3CA7A6FD2BAD0550DBA53E6119C852C8CF118D609B1DBBE)

## 使用真机运行应用

1. 将搭载HarmonyOS系统的真机与电脑连接。具体指导及要求，可查看[使用本地真机运行应用/服务](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-run-device)。

2. 进入**File > Project Structure... > Project > Signing Configs** 界面，勾选"**Automatically generate signature** "，即可完成签名。如果未登录，请先单击**Sign In** 进行登录，然后自动完成签名。具体请见[配置调试签名](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing-auto#section1172562862811)。如下图所示：

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8/v3/3ABRIVXeTWuitmoKAp6VRg/zh-cn_image_0000002773903382.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=ED41036B079BDF41B7CD1D70B06858762AD56D59A5DFC129096775E035F8423D)
3. 在编辑窗口右上角的工具栏，单击![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/42/v3/02gmEP8-SVezj4Z_Lvbz0A/zh-cn_image_0000002803263167.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=6FA70244E4D80AEB9F1590311B41B20BF5D4E58EF43C864134222B08F9F303A4)按钮运行。效果如下图所示：

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/32/v3/tD3BxKU5SdqC3AQkvJvD4g/zh-cn_image_0000002803223073.png?HW-CC-KV=V1&HW-CC-Date=20261026T101415Z&HW-CC-Expire=31536000000&HW-CC-Sign=1B5F65DE118F38AFAD632FC1F5169EF48111E70239E6EA4ABEBDA02DADB4FBD6)

恭喜您已经基于ArkTS语言构建完成第一个HarmonyOS应用，快来探索更多的HarmonyOS功能吧。