openharmony-ui-reference

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenHarmony UI 快速参考

OpenHarmony UI快速参考

概述

概述

OpenHarmony 使用 ArkTS (基于 TypeScript 的声明式 UI) 来构建用户界面。核心概念:声明式 UI 描述、组件化架构、状态管理装饰器、响应式布局。
官方文档:
docs-OpenHarmony-v6.0-Release/zh-cn/application-dev/ui/
快速参考:
docs/
(本地提取的核心文档)
OpenHarmony 使用ArkTS(基于TypeScript的声明式UI)构建用户界面。核心概念包括:声明式UI描述、组件化架构、状态管理装饰器、响应式布局。
官方文档:
docs-OpenHarmony-v6.0-Release/zh-cn/application-dev/ui/
快速参考:
docs/
(本地提取的核心文档)

状态管理

状态管理

V2 (推荐用于新项目)

V2(推荐用于新项目)

装饰器用途作用域
@Local
组件内部状态仅组件内部
@Param
父 → 子 (单向)父到子
@Event
子 → 父回调子到父
@Provider
/
@Consumer
跨组件同步任意后代组件
双向绑定:
typescript
// 父组件
@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 })
装饰器用途作用域
@Local
组件内部状态仅组件内部
@Param
父 → 子(单向)父到子
@Event
子 → 父回调子到父
@Provider
/
@Consumer
跨组件同步任意后代组件
双向绑定:
typescript
// 父组件
@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 (传统方式)

V1(传统方式)

装饰器用途作用域
@State
组件内部状态仅组件内部
@Prop
父 → 子 (单向)父到子
@Link
父 ↔ 子 (双向)双向绑定
@Provide
/
@Consume
跨组件同步任意后代组件
文档参考:
docs/state-management/arkts-state-management-overview.md
装饰器用途作用域
@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
内容居中:
typescript
Column() {
  Text('Centered')
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)
文档参考:
docs/layout/arkts-layout-development-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
内容居中:
typescript
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
组件用途文档
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

导航

导航

Navigation (推荐):
typescript
@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 (传统方式):
typescript
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
Navigation(推荐):
typescript
@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(传统方式):
typescript
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
类型方法使用场景文档
自定义对话框
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
typescript
// 属性动画
@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
    })
  })
类型API使用场景文档
属性动画
.animateTo()
平滑属性变化
docs/animation/arkts-attribute-animation-overview.md
转场动画
.transition()
进出场动画
docs/animation/arkts-transition-overview.md
组件动画
animateTo
组合多个动画
docs/animation/arkts-component-animation.md
typescript
// 属性动画
@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
typescript
// ForEach (始终提供唯一键)
ForEach(this.items, (item: Item) => {
  Text(item.name)
}, (item: Item) => item.id)
控制方式语法使用场景文档
条件渲染
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
typescript
// ForEach (始终提供唯一键)
ForEach(this.items, (item: Item) => {
  Text(item.name)
}, (item: Item) => item.id)

样式

样式

@Styles (可复用样式):
typescript
@Styles
function cardStyle() {
  .backgroundColor(Color.White)
  .borderRadius(12)
  .padding(16)
}

Column() {}
  .cardStyle()
@Extend (扩展组件):
typescript
@Extend(Text)
function redText() {
  .fontSize(18)
  .fontColor(Color.Red)
}

Text('Hello')
  .redText()
文档参考:
docs/state-management/arkts-style.md
@Styles(可复用样式):
typescript
@Styles
function cardStyle() {
  .backgroundColor(Color.White)
  .borderRadius(12)
  .padding(16)
}

Column() {}
  .cardStyle()
@Extend(扩展组件):
typescript
@Extend(Text)
function redText() {
  .fontSize(18)
  .fontColor(Color.Red)
}

Text('Hello')
  .redText()
文档参考:
docs/state-management/arkts-style.md

常用模式

常用模式

带生命周期的自定义组件:
typescript
@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 片段):
typescript
@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
带生命周期的自定义组件:
typescript
@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片段):
typescript
@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()
文档参考:
  • V2 状态管理:
    docs/state-management/arkts-mvvm-V2.md
  • V1 状态管理:
    docs/state-management/arkts-mvvm.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()
文档参考:
  • V2状态管理:
    docs/state-management/arkts-mvvm-V2.md
  • V1状态管理:
    docs/state-management/arkts-mvvm.md

重要提示

重要提示

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