OpenHarmony UI 快速参考

概述

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

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

状态管理

V2 (推荐用于新项目)

装饰器	用途	作用域
`@Local`	组件内部状态	仅组件内部
`@Param`	父 → 子 (单向)	父到子
`@Event`	子 → 父回调	子到父
`@Provider`/`@Consumer`	跨组件同步	任意后代组件

双向绑定:

// 父组件
@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 (传统方式)

装饰器	用途	作用域
`@State`	组件内部状态	仅组件内部
`@Prop`	父 → 子 (单向)	父到子
`@Link`	父 ↔ 子 (双向)	双向绑定
`@Provide`/`@Consume`	跨组件同步	任意后代组件

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

布局

需求	组件	关键属性	文档
水平排列	`Row`	space, alignItems, justifyContent	`docs/layout/arkts-layout-development-linear.md`
垂直排列	`Column`	space, alignItems, justifyContent	`docs/layout/arkts-layout-development-linear.md`
层叠布局	`Stack`	alignContent	`docs/layout/arkts-layout-development-stack-layout.md`
弹性布局	`Flex`	direction, wrap, justifyContent	`docs/layout/arkts-layout-development-flex-layout.md`
相对布局	`RelativeContainer`	x/y 规则	`docs/layout/arkts-layout-development-relative-layout.md`
网格布局	`Grid`/`GridItem`	columnsTemplate, rowsTemplate	`docs/layout/arkts-layout-development-grid-layout.md`
标签页	`Tabs`/`TabContent`	barPosition, scrollable	`docs/navigation/arkts-navigation-tabs.md`
列表	`List`/`ListItem`	space, scrollBar	`docs/layout/arkts-layout-development-create-list.md`
瀑布流	`WaterFlow`/`FlowItem`	columnsTemplate	`docs/layout/arkts-layout-development-create-waterflow.md`

内容居中:

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

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

常用组件

组件	用途	文档
Text	显示文本	`docs/components/arkts-common-components-text-display.md`
TextInput	单行输入	`docs/components/arkts-common-components-text-input.md`
TextArea	多行输入	`docs/components/arkts-common-components-text-input.md`
Button	可点击按钮	`docs/components/arkts-common-components-button.md`
Image	显示图片	`docs/components/arkts-graphics-display.md`
List	垂直滚动列表	`docs/layout/arkts-layout-development-create-list.md`
Grid	网格布局	`docs/layout/arkts-layout-development-create-grid.md`
Swiper	轮播图	`docs/layout/arkts-layout-development-create-looping.md`
RichEditor	富文本编辑器	`docs/components/arkts-common-components-richeditor.md`

@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

对话框和弹窗

类型	方法	使用场景	文档
自定义对话框	`openCustomDialog()`	推荐	`docs/uicontext/arkts-uicontext-custom-dialog.md`
警告对话框	`AlertDialog.show()`	简单确认	`docs/dialogs/arkts-base-dialog-overview.md`
列表选择	`ActionSheet.show()`	选项选择	`docs/dialogs/arkts-base-dialog-overview.md`
弹窗	`.bindPopup()`	绑定到组件	`docs/popup/arkts-popup-and-menu-components-popup.md`
提示	`prompt.showToast()`	简短反馈	`docs/popup/arkts-create-toast.md`

动画

类型	API	使用场景	文档
属性动画	`.animateTo()`	平滑属性变化	`docs/animation/arkts-attribute-animation-overview.md`
转场动画	`.transition()`	进出场动画	`docs/animation/arkts-transition-overview.md`
组件动画	`animateTo`	组合多个动画	`docs/animation/arkts-component-animation.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
    })
  })

渲染控制

控制方式	语法	使用场景	文档
条件渲染	`if (condition) { } else { }`	显示/隐藏组件	`docs/state-management/arkts-rendering-control-ifelse.md`
循环渲染	`ForEach(arr, (item) => {}, (item) => key)`	渲染列表	`docs/state-management/arkts-rendering-control-foreach.md`
懒加载循环	`LazyForEach(dataSource, (item) => {})`	大数据集	`docs/state-management/arkts-rendering-control-lazyforeach.md`

// 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

问题排查

症状	常见原因	解决方法
状态变化不更新 UI	缺少装饰器	添加 `@Local` (V2) 或 `@State` (V1)
子组件未接收更新	使用单向而非双向绑定	添加 `@Event` 回调 (V2) 或使用 `@Link` (V1)
嵌套对象不响应	缺少深度观察	添加 `@ObservedV2`/`@Trace` (V2) 或 `@Observed`/`@ObjectLink` (V1)
不必要的重渲染	本地状态中有大对象	对不可变属性使用 `@Param`
ForEach 渲染问题	缺少唯一键	始终提供唯一键生成器
导航不工作	使用 Router 而非 Navigation	使用 `NavPathStack` API
对话框不显示	缺少 UI 上下文	使用 `getUIContext().openCustomDialog()`