OpenHarmony UI 快速参考

概述

OpenHarmony 使用 ArkTS (基于 TypeScript 的声明式 UI) 来构建用户界面。核心概念:声明式 UI 描述、组件化架构、状态管理装饰器、响应式布局。

官方文档: docs-OpenHarmony-v6.0-Release/zh-cn/application-dev/ui/ 快速参考: docs/ (本地提取的核心文档)

状态管理

V2 (推荐用于新项目)

双向绑定:

// 父组件
@ComponentV2
struct Parent {
  @Local text: string = ''

  build() {
    Child({ text: this.text, onTextChange: (val) => { this.text = val } })
  }
}

// 子组件
@ComponentV2
struct Child {
  @Param text: string
  @Event onTextChange: (val: string) => void

  build() {
    TextInput({ text: this.text })
      .onChange((val) => this.onTextChange(val))
  }
}

// 语法糖(更简单)
TextInput({ text: $$this.text })

V1 (传统方式)

文档参考: docs/state-management/arkts-state-management-overview.md

布局

内容居中:

Column() {
  Text('Centered')
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)

文档参考: docs/layout/arkts-layout-development-overview.md

常用组件

导航

Navigation (推荐):

@Entry
@Component
struct NavPage {
  @Provide('pageInfos') pageInfos: NavPathStack = new NavPathStack()

  build() {
    Navigation(this.pageInfos) {
      Column() {
        Button('Go to Page2')
          .onClick(() => {
            this.pageInfos.pushPath({ name: 'Page2' })
          })
      }
    }
    .title('Main Page')
  }
}

Router (传统方式):

import router from '@ohos.router'

// 跳转页面
router.pushUrl({ url: 'pages/Page2' })

// 返回
router.back()

文档参考:

• Navigation: docs/navigation/arkts-navigation-navigation.md
• Router: docs/navigation/arkts-routing.md

对话框和弹窗

动画

// 属性动画
@State scale: number = 1

Image($r('app.media.icon'))
  .scale({ x: this.scale, y: this.scale })
  .onClick(() => {
    animateTo({ duration: 300 }, () => {
      this.scale = this.scale === 1 ? 1.5 : 1
    })
  })

渲染控制

// ForEach (始终提供唯一键)
ForEach(this.items, (item: Item) => {
  Text(item.name)
}, (item: Item) => item.id)

样式

@Styles (可复用样式):

@Styles
function cardStyle() {
  .backgroundColor(Color.White)
  .borderRadius(12)
  .padding(16)
}

Column() {}
  .cardStyle()

@Extend (扩展组件):

@Extend(Text)
function redText() {
  .fontSize(18)
  .fontColor(Color.Red)
}

Text('Hello')
  .redText()

文档参考: docs/state-management/arkts-style.md

常用模式

带生命周期的自定义组件:

@ComponentV2
struct CustomComponent {
  @Local count: number = 0

  aboutToAppear() {
    console.log('Component will appear')
  }

  aboutToDisappear() {
    console.log('Component will disappear')
  }

  build() {
    Text(`Count: ${this.count}`)
  }
}

@Builder (可复用 UI 片段):

@Builder
function TitleBar(title: string) {
  Row() {
    Text(title)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
  }
  .width('100%')
  .padding(16)
}

// 使用
Column() {
  TitleBar({ title: 'My Page' })
}

文档参考: docs/state-management/arkts-builder.md

问题排查

文档参考:

• V2 状态管理: docs/state-management/arkts-mvvm-V2.md
• V1 状态管理: docs/state-management/arkts-mvvm.md

重要提示

• 始终提供唯一键 给 ForEach 以避免渲染问题
• 新项目使用 V2 状态管理 (@Local, @Param)
• 优先使用 Navigation 而非 Router 进行页面路由
• 尽可能使用 $$ 语法 简化双向绑定
• 大数据集使用 LazyForEach (> 1000 项)
• 在不同屏幕尺寸上测试 使用媒体查询

更多参考

官方文档: docs-OpenHarmony-v6.0-Release/zh-cn/application-dev/ui/

本地快速参考: docs/

核心文档:

• UI 概览: docs/overview/arkts-ui-development-overview.md
• 状态管理: docs/state-management/arkts-state-management-overview.md
• 布局开发: docs/layout/arkts-layout-development-overview.md
• 组件库: docs/components/arkts-common-components-text-display.md 及相关文件
• 导航: docs/navigation/arkts-navigation-navigation.md
• 动画: docs/animation/arkts-attribute-animation-overview.md