Develop a Simple App Using HarmonyOS ArkUI: A Step-by-Step Guide

HarmonyOS, Huawei’s distributed operating system, is gaining significant traction. ArkUI, its declarative UI framework, offers a modern approach to building cross-device applications. This comprehensive guide will walk you through the process of developing a simple application using HarmonyOS ArkUI, covering everything from setting up your development environment to deploying your first app.

Table of Contents

1. Introduction to HarmonyOS and ArkUI
2. Setting Up Your Development Environment
   • Installing DevEco Studio
   • Configuring the SDK
   • Creating an Emulator
3. Creating a New HarmonyOS Project
   • Choosing the Correct Template
   • Understanding the Project Structure
4. Building the User Interface with ArkUI
   • Understanding the ArkUI Declarative Syntax
   • Working with Components: Text, Button, Image, and Input
   • Implementing Layouts: Row, Column, Flex
   • Styling Your UI with CSS-like Properties
5. Adding Functionality with TypeScript
   • Handling User Interactions: Button Clicks, Input Changes
   • Data Binding: Connecting UI to Data
   • Managing State: Using @State and @Link
6. Implementing a Simple Application: A Counter App
   • Designing the UI
   • Implementing the Counter Logic
   • Testing the Application
7. Testing Your Application
   • Using the DevEco Studio Emulator
   • Debugging Your Code
   • Handling Errors and Exceptions
8. Advanced ArkUI Concepts
   • Custom Components
   • Animations and Transitions
   • Data Persistence
   • Networking
9. Best Practices for HarmonyOS App Development
   • Code Optimization
   • UI/UX Design Principles
   • Performance Tuning
10. Deploying Your Application
    • Creating an HAP Package
    • Submitting to the AppGallery
11. Conclusion

1. Introduction to HarmonyOS and ArkUI

HarmonyOS is a distributed operating system designed by Huawei to provide a unified experience across various devices, including smartphones, tablets, wearables, and smart home appliances. Its key features include modular design, distributed capabilities, and enhanced security.

ArkUI is the declarative UI framework for HarmonyOS. It offers a simplified and efficient way to build user interfaces. Key benefits of using ArkUI include:

• Declarative Syntax: UI is defined using a declarative approach, making the code more readable and maintainable.
• Component-Based Architecture: UI is built using reusable components, promoting code reuse and modularity.
• Cross-Device Compatibility: ArkUI supports a wide range of devices, ensuring a consistent user experience across different form factors.
• Efficient Rendering: ArkUI is optimized for performance, providing smooth and responsive UI.

2. Setting Up Your Development Environment

Before you can start developing HarmonyOS applications, you need to set up your development environment. This involves installing DevEco Studio, configuring the SDK, and creating an emulator.

2.1 Installing DevEco Studio

DevEco Studio is the official IDE (Integrated Development Environment) for HarmonyOS development. It provides all the necessary tools for building, debugging, and deploying HarmonyOS applications.

1. Download DevEco Studio: Visit the official HarmonyOS developer website (developer.harmonyos.com) and download the latest version of DevEco Studio.
2. Install DevEco Studio: Follow the installation instructions provided on the website. Make sure to choose the correct installation directory.
3. Launch DevEco Studio: After installation, launch DevEco Studio. You may be prompted to configure the SDK.

2.2 Configuring the SDK

The SDK (Software Development Kit) contains the necessary libraries and tools for compiling and running HarmonyOS applications.

1. Download the SDK: DevEco Studio usually prompts you to download the SDK during the initial setup. If not, you can download it manually from the SDK Manager within DevEco Studio. Go to File > Settings > HarmonyOS SDK.
2. Configure Environment Variables: DevEco Studio will automatically configure the necessary environment variables. Verify that the OHOS_HOME environment variable is set correctly to the SDK installation directory.
3. Accept the License Agreement: Accept the license agreement for the SDK components.

2.3 Creating an Emulator

The Emulator allows you to test your applications without needing a physical HarmonyOS device.

1. Open Device Manager: In DevEco Studio, go to Tools > Device Manager.
2. Create a New Emulator: Click on the “+” button to create a new emulator.
3. Choose a Device Profile: Select a device profile that matches your target device. You can choose from different form factors, such as smartphones, tablets, and wearables.
4. Configure Emulator Settings: Configure the emulator settings, such as memory size and screen resolution.
5. Download System Image: Download the system image for the selected device profile. This may take some time depending on your internet connection.
6. Start the Emulator: After the system image is downloaded, start the emulator by clicking the “Run” button.

3. Creating a New HarmonyOS Project

Once you have set up your development environment, you can create a new HarmonyOS project.

3.1 Choosing the Correct Template

DevEco Studio provides several project templates to choose from. Select the template that best suits your needs.

1. Open DevEco Studio: Launch DevEco Studio.
2. Create a New Project: Go to File > New > New Project.
3. Select a Template: Choose a template from the available options. For a simple application, select the Empty Ability template. Other useful templates include Stage Model Application, depending on your desired architecture.
4. Configure Project Settings: Enter the project name, package name, and project location.
5. Finish Project Creation: Click “Finish” to create the project.

3.2 Understanding the Project Structure

Understanding the project structure is crucial for navigating and managing your project files.

• entry: Contains the main application code, including the UI and logic.
  • src/main/ets: Contains the TypeScript code for your application.
    • pages: Contains the UI pages. The default page is usually named Index.ets.
    • view: Place where you can define custom components
    • app.ts: The application entry point.
    • .d.ts: Contains type definitions for the project.
  • src/main/resources: Contains resources such as images, fonts, and strings.
  • build.gradle: The build configuration file.
• ohos.build.json5: Contains global project configuration.

4. Building the User Interface with ArkUI

ArkUI uses a declarative syntax to define the user interface. This makes the code more readable and easier to maintain.

4.1 Understanding the ArkUI Declarative Syntax

ArkUI uses a declarative syntax based on TypeScript. The UI is defined using components, which are arranged in a hierarchical structure.

Here’s a simple example of ArkUI code:

  @Entry
  @Component
  struct MyComponent {
    @State message: string = 'Hello, World!';

    build() {
      Column() {
        Text(this.message)
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Blue)
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
      .alignItems(HorizontalAlign.Center)
    }
  }
  

In this example:

• @Entry marks the component as the entry point for the UI.
• @Component declares a new component named MyComponent.
• @State message: string = 'Hello, World!'; declares a state variable named message with an initial value of “Hello, World!”.
• The build() method defines the UI layout.
• Column() creates a vertical layout container.
• Text(this.message) creates a text component displaying the value of the message state variable.
• Chained methods like .fontSize(20), .fontWeight(FontWeight.Bold), and .fontColor(Color.Blue) apply styling to the text component.
• Properties like .width('100%'), .height('100%'), .justifyContent(FlexAlign.Center), and .alignItems(HorizontalAlign.Center) configure the layout of the Column component.

4.2 Working with Components: Text, Button, Image, and Input

ArkUI provides a rich set of built-in components that you can use to build your UI.

• Text: Displays text on the screen.

  
        Text('Hello, World!')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Blue)
        

• Button: Creates a clickable button.

  
        Button('Click Me')
          .onClick(() => {
            console.log('Button clicked!');
          })
        

• Image: Displays an image.

  
        Image('public/images/logo.png')
          .width(100)
          .height(100)
        

• TextInput: Creates a text input field.

  
        TextInput({ placeholder: 'Enter text' })
          .onChange((value) => {
            console.log('Text changed:', value);
          })
        

4.3 Implementing Layouts: Row, Column, Flex

ArkUI provides several layout containers that you can use to arrange components on the screen.

• Row: Arranges components horizontally.

  
        Row() {
          Text('Item 1')
          Text('Item 2')
          Text('Item 3')
        }
        

• Column: Arranges components vertically.

  
        Column() {
          Text('Item 1')
          Text('Item 2')
          Text('Item 3')
        }
        

• Flex: Provides a flexible way to arrange components.

  
        Flex({ direction: FlexDirection.Row, justifyContent: FlexAlign.SpaceAround }) {
          Text('Item 1')
          Text('Item 2')
          Text('Item 3')
        }
        

4.4 Styling Your UI with CSS-like Properties

ArkUI allows you to style your UI components using CSS-like properties.

Here are some common styling properties:

• fontSize: Sets the font size.
• fontWeight: Sets the font weight.
• fontColor: Sets the font color.
• backgroundColor: Sets the background color.
• width: Sets the width.
• height: Sets the height.
• padding: Sets the padding.
• margin: Sets the margin.
• border: Sets the border.

Example:

  Text('Hello, World!')
    .fontSize(20)
    .fontWeight(FontWeight.Bold)
    .fontColor(Color.Blue)
    .backgroundColor(Color.LightGray)
    .padding(10)
    .border({ width: 1, color: Color.Black })
  

5. Adding Functionality with TypeScript

ArkUI uses TypeScript to add functionality to your application.

5.1 Handling User Interactions: Button Clicks, Input Changes

You can handle user interactions using event handlers.

Example:

  Button('Click Me')
    .onClick(() => {
      console.log('Button clicked!');
    })

  TextInput({ placeholder: 'Enter text' })
    .onChange((value) => {
      console.log('Text changed:', value);
    })
  

5.2 Data Binding: Connecting UI to Data

Data binding allows you to connect UI components to data. When the data changes, the UI is automatically updated.

Example:

  @Component
  struct MyComponent {
    @State message: string = 'Hello, World!';

    build() {
      Column() {
        Text(this.message)
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Blue)

        Button('Update Message')
          .onClick(() => {
            this.message = 'New Message!';
          })
      }
    }
  }
  

In this example, the Text component is bound to the message state variable. When the message variable is updated by clicking the button, the Text component is automatically updated.

5.3 Managing State: Using @State and @Link

ArkUI provides the @State and @Link decorators for managing state.

• @State: Declares a state variable that is local to the component. Changes to the state variable trigger a UI update.
• @Link: Creates a two-way binding between a state variable in a parent component and a variable in a child component. Changes to the variable in the child component also update the state variable in the parent component.

Example using @State:

  @Component
  struct MyComponent {
    @State counter: number = 0;

    build() {
      Column() {
        Text(`Counter: ${this.counter}`)
          .fontSize(20)

        Button('Increment')
          .onClick(() => {
            this.counter++;
          })
      }
    }
  }
  

Example using @Link:

  @Component
  struct ParentComponent {
    @State counter: number = 0;

    build() {
      Column() {
        Text(`Counter: ${this.counter}`)
          .fontSize(20)

        ChildComponent({ counter: $counter })
      }
    }
  }

  @Component
  struct ChildComponent {
    @Link counter: number;

    build() {
      Button('Increment')
        .onClick(() => {
          this.counter++;
        })
    }
  }
  

6. Implementing a Simple Application: A Counter App

Let’s implement a simple counter application to demonstrate the concepts we have learned.

6.1 Designing the UI

The counter app will have the following UI elements:

• A text view to display the counter value.
• A button to increment the counter.
• A button to decrement the counter.

6.2 Implementing the Counter Logic

Here’s the code for the counter app:

  @Entry
  @Component
  struct CounterApp {
    @State counter: number = 0;

    build() {
      Column() {
        Text(`Counter: ${this.counter}`)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .padding(20)

        Row() {
          Button('Increment')
            .onClick(() => {
              this.counter++;
            })
            .margin(10)

          Button('Decrement')
            .onClick(() => {
              this.counter--;
            })
            .margin(10)
        }
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
      .alignItems(HorizontalAlign.Center)
    }
  }
  

6.3 Testing the Application

Run the application on the emulator to test it.

7. Testing Your Application

Testing is a crucial part of the development process. It ensures that your application works as expected and is free of bugs.

7.1 Using the DevEco Studio Emulator

The DevEco Studio emulator is a valuable tool for testing your application on different devices and configurations.

To run your application on the emulator:

1. Select the Emulator: In DevEco Studio, select the emulator from the device dropdown menu.
2. Run the Application: Click the “Run” button to run the application on the emulator.

7.2 Debugging Your Code

DevEco Studio provides a powerful debugger that allows you to step through your code, inspect variables, and identify and fix bugs.

To debug your code:

1. Set Breakpoints: Set breakpoints in your code by clicking in the left margin of the editor.
2. Run in Debug Mode: Click the “Debug” button to run the application in debug mode.
3. Step Through Code: Use the debugger controls to step through your code, inspect variables, and examine the call stack.

7.3 Handling Errors and Exceptions

It’s important to handle errors and exceptions gracefully to prevent your application from crashing.

You can use try...catch blocks to handle exceptions.

  try {
    // Code that may throw an exception
    const result = someFunction();
    console.log('Result:', result);
  } catch (error) {
    // Handle the exception
    console.error('Error:', error);
  }
  

8. Advanced ArkUI Concepts

Once you have mastered the basics of ArkUI, you can explore more advanced concepts.

8.1 Custom Components

Custom components allow you to create reusable UI elements.

Example:

  @Component
  struct MyButton {
    @Prop text: string;
    @Prop onClick: () => void;

    build() {
      Button(this.text)
        .onClick(this.onClick)
        .backgroundColor(Color.Blue)
        .fontColor(Color.White)
        .padding(10)
        .borderRadius(5)
    }
  }

  @Entry
  @Component
  struct MyComponent {
    build() {
      Column() {
        MyButton({
          text: 'Click Me',
          onClick: () => {
            console.log('Custom button clicked!');
          }
        })
      }
    }
  }
  

8.2 Animations and Transitions

Animations and transitions can enhance the user experience by adding visual effects to your UI.

Example:

  @Entry
  @Component
  struct MyComponent {
    @State visible: boolean = false;

    build() {
      Column() {
        Button(this.visible ? 'Hide' : 'Show')
          .onClick(() => {
            this.visible = !this.visible;
          })

        if (this.visible) {
          Text('This text will fade in and out')
            .opacity(this.visible ? 1 : 0)
            .animation({ duration: 500, curve: Curve.EaseInOut })
        }
      }
    }
  }
  

8.3 Data Persistence

Data persistence allows you to store data locally on the device so that it is available even after the application is closed.

You can use the LocalStorage API for simple data persistence.

  import { LocalStorage } from '@ohos.data.storage';

  @Entry
  @Component
  struct MyComponent {
    @State value: string = '';

    aboutToAppear() {
      LocalStorage.Get('myKey', (err, data) => {
        if (!err && data) {
          this.value = data;
        }
      });
    }

    build() {
      Column() {
        TextInput({ placeholder: 'Enter text' })
          .onChange((newValue) => {
            this.value = newValue;
            LocalStorage.Set('myKey', newValue, (err) => {
              if (err) {
                console.error('Failed to save data:', err);
              }
            });
          })
          .text(this.value)

        Text(`Saved value: ${this.value}`)
          .fontSize(20)
      }
    }
  }
  

8.4 Networking

Networking allows your application to communicate with remote servers and APIs.

You can use the fetch API to make HTTP requests.

  @Entry
  @Component
  struct MyComponent {
    @State data: string = '';

    aboutToAppear() {
      fetch('https://jsonplaceholder.typicode.com/todos/1')
        .then(response => response.json())
        .then(json => {
          this.data = JSON.stringify(json);
        })
        .catch(error => {
          console.error('Error fetching data:', error);
        });
    }

    build() {
      Column() {
        Text(`Data from API: ${this.data}`)
          .fontSize(20)
      }
    }
  }
  

9. Best Practices for HarmonyOS App Development

Following best practices can help you build high-quality, performant, and user-friendly HarmonyOS applications.

9.1 Code Optimization

• Minimize UI updates: Avoid unnecessary UI updates to improve performance. Use @State variables judiciously.
• Optimize images: Use optimized images to reduce the application size and improve loading times.
• Use efficient data structures: Choose the appropriate data structures for your needs to improve performance.
• Avoid blocking the main thread: Perform long-running tasks in background threads to prevent the UI from freezing.

9.2 UI/UX Design Principles

• Follow the HarmonyOS design guidelines: Adhere to the HarmonyOS design guidelines to ensure a consistent user experience.
• Keep the UI simple and intuitive: Design a simple and intuitive UI that is easy to use.
• Provide clear feedback: Provide clear feedback to the user when they interact with the application.
• Test on different devices: Test your application on different devices and screen sizes to ensure that it looks and works well on all devices.

9.3 Performance Tuning

• Use profiling tools: Use profiling tools to identify performance bottlenecks in your application.
• Optimize rendering: Optimize the rendering of your UI to improve performance.
• Reduce memory usage: Reduce memory usage to prevent the application from running out of memory.
• Monitor performance: Monitor the performance of your application in real-time to identify and fix performance issues.

10. Deploying Your Application

Once you are satisfied with your application, you can deploy it to the AppGallery.

10.1 Creating an HAP Package

An HAP (HarmonyOS Ability Package) package is the distribution format for HarmonyOS applications.

To create an HAP package:

1. Build the Application: In DevEco Studio, go to Build > Build Hap(s)/App(s) > Build Hap(s).
2. Locate the HAP Package: The HAP package will be located in the entry/build/outputs/hap directory.

10.2 Submitting to the AppGallery

To submit your application to the AppGallery:

1. Create a Developer Account: Create a developer account on the Huawei Developer website (developer.huawei.com).
2. Prepare Your Application: Prepare your application for submission by providing the necessary information, such as the application name, description, and screenshots.
3. Submit Your Application: Upload the HAP package to the AppGallery and submit your application for review.

11. Conclusion

This guide has provided a comprehensive overview of how to develop a simple application using HarmonyOS ArkUI. By following these steps, you can create your own HarmonyOS applications and deploy them to the AppGallery. HarmonyOS and ArkUI offer a promising platform for building cross-device applications, and with the knowledge gained from this guide, you’re well-equipped to embark on your HarmonyOS development journey. Remember to continuously explore the HarmonyOS developer documentation and community resources to stay updated with the latest features and best practices.