ArkTS 中常用类型ArkTS 常用 UI 相关类型详解在 ArkTS 中，除了 UI 组件（如 Text、Butt

ArkTS 常用 UI 相关类型详解

在 ArkTS 中，除了 UI 组件（如 Text、Button）之外，还有大量用于配置这些组件外观、行为和交互的“类型”或“枚举”。熟练掌握这些常用类型，对于构建功能丰富、样式精美的 UI 至关重要。

本文档将这些常用类型进行分类，并详细介绍其作用及使用方法。

导航与工具栏类型
- ToolbarItem
- NavigationTitleMode
- NavigationBackButtonPosition
样式与外观类型
- Color
- FontWeight
- FontStyle
- TextAlign
- ImageFit
- BorderStyle
- Visibility
布局与对齐类型
- Alignment
- FlexDirection / FlexAlign / FlexWrap
- BarPosition
动画与转场类型
- AnimationOption
- TransitionEffect
- Curve
手势类型
- Gesture (TapGesture, LongPressGesture, PanGesture, etc.)
其他实用类型
- Resource / $r
- EdgeInsets
- Length / Dimension

1. 导航与工具栏类型

这些类型主要与 Navigation 和 Tabs 等导航组件配合使用。

ToolbarItem

作用: 定义 Navigation 组件工具栏上的操作按钮。它不是一个组件，而是一个对象类型，用于描述按钮的图标和行为。
如何使用: 在 Navigation 组件的 .toolBar() 修饰器中使用，通常是一个 ToolbarItem 对象的数组。
属性:
- value: 显示的文本。
- icon: 显示的图标（使用 $r 引用资源）。
- action: 点击时触发的回调函数。
示例:

TypeScript

// 在 Navigation 组件中使用
.toolBar({
  items: [
    {
      value: '分享',
      icon: $r('app.media.ic_share'),
      action: () => {
        console.log('分享被点击');
      }
    },
    {
      value: '设置',
      icon: $r('app.media.ic_settings'),
      action: () => {
        console.log('设置被点击');
      }
    }
  ]
})

NavigationTitleMode

作用: 定义 Navigation 组件标题的显示模式。这是一个枚举类型。
如何使用: 在 .titleMode() 修饰器中使用。
枚举值:
- NavigationTitleMode.Free: 自由模式，标题随页面滚动而滚动。
- NavigationTitleMode.Mini: 迷你模式，标题固定在导航栏顶部。
- NavigationTitleMode.Full: 完整模式，显示一个更大的标题，滚动时可收缩为迷你模式。
示例:

TypeScript

Navigation(this.path) {
  // ... 页面内容
}
.title('我的文件')
.titleMode(NavigationTitleMode.Full)

NavigationBackButtonPosition

作用: 定义 Navigation 组件返回按钮的位置。
如何使用: 在 .backButtonPosition() 修饰器中使用。
枚举值:
- NavigationBackButtonPosition.Start: 靠左显示 (默认)。
- NavigationBackButtonPosition.End: 靠右显示。
示例:

TypeScript

Navigation() {
  // ...
}
.backButtonPosition(NavigationBackButtonPosition.End)

2. 样式与外观类型

这些类型用于定义组件的具体视觉表现。

Color

作用: 表示颜色值的枚举和工具类。
如何使用: 可以使用预定义的颜色枚举，也可以使用 RGB、ARGB 或十六进制字符串。
枚举值: Color.Red, Color.Green, Color.Black, Color.White, Color.Transparent 等。
示例:

TypeScript

Text('示例文字')
  .fontColor(Color.Blue) // 使用枚举

Button('按钮')
  .backgroundColor('#FFC0CB') // 使用十六进制字符串

Column()
  .backgroundColor('rgba(0, 0, 255, 0.5)') // 使用 rgba 字符串

FontWeight

作用: 定义文本的字重（粗细）。
如何使用: 在 Text 等组件的 .fontWeight() 修饰器中使用。
枚举值: FontWeight.Lighter, FontWeight.Normal, FontWeight.Bold, FontWeight.Bolder。也可以直接使用 100 到 900 的数字。
示例:

TypeScript

Text('加粗文本')
  .fontWeight(FontWeight.Bold)

Text('更细的文本')
  .fontWeight(100)

FontStyle

作用: 定义文本的样式（是否倾斜）。
枚举值:
- FontStyle.Normal: 正常。
- FontStyle.Italic: 斜体。
示例:

TypeScript

Text('斜体文字')
  .fontStyle(FontStyle.Italic)

TextAlign

作用: 定义文本在可用空间内的水平对齐方式。
枚举值: TextAlign.Start, TextAlign.Center, TextAlign.End, TextAlign.Justify。
示例:

TypeScript

Text('这段文本将会居中显示，并占据整个宽度。')
  .width('100%')
  .textAlign(TextAlign.Center)

ImageFit

作用: 定义图片的缩放和裁剪模式，以适应其指定的 width 和 height。
枚举值:
- ImageFit.Cover: 保持宽高比，缩放以完全覆盖区域，可能裁剪图片。
- ImageFit.Contain: 保持宽高比，缩放以完整显示在区域内，可能留有空白。
- ImageFit.Fill: 拉伸图片以填满区域，不保持宽高比。
- ImageFit.None: 不进行缩放。
示例:

TypeScript

Image($r('app.media.my_image'))
  .width(100)
  .height(200)
  .objectFit(ImageFit.Cover)

BorderStyle

作用: 定义边框的样式。
枚举值: BorderStyle.Solid (实线), BorderStyle.Dashed (虚线), BorderStyle.Dotted (点线)。
示例:

TypeScript

Column() { /* ... */ }
  .border({
    width: 2,
    color: Color.Red,
    style: BorderStyle.Dashed
  })

Visibility

作用: 控制组件的可见性及其在布局中所占的空间。
枚举值:
- Visibility.Visible: 可见 (默认)。
- Visibility.Hidden: 不可见，但仍在布局中占据空间。
- Visibility.None: 不可见，且不占据任何布局空间。
示例:

TypeScript

@State isVisible: boolean = true

Button(this.isVisible ? '隐藏' : '显示')
  .onClick(() => { this.isVisible = !this.isVisible })

Text('这段文本可以被隐藏')
  .visibility(this.isVisible ? Visibility.Visible : Visibility.Hidden)

3. 布局与对齐类型

这些类型主要用于 Row, Column, Stack, Flex 等布局容器中。

Alignment

作用: 定义子组件在父容器中的对齐方式。
如何使用: 常用在 Stack 的 alignContent 或通用修饰器 .align() 中。
枚举值:
- Alignment.TopStart, Alignment.Top, Alignment.TopEnd
- Alignment.Start, Alignment.Center, Alignment.End
- Alignment.BottomStart, Alignment.Bottom, Alignment.BottomEnd
示例:

TypeScript

Stack() {
  Image($r('...'))
  Text('右下角')
}
.alignContent(Alignment.BottomEnd) // 所有子组件都对齐到右下角

FlexDirection / FlexAlign / FlexWrap

作用: 这些是 Flex 布局专用的枚举。
- FlexDirection: 定义主轴方向 (Row, Column)。
- FlexAlign: 定义主轴 (justifyContent) 和交叉轴 (alignItems) 的对齐方式。
- FlexWrap: 定义当子项超出主轴时是否换行 (Wrap, NoWrap)。
示例:

TypeScript

Flex({
  direction: FlexDirection.Row,
  justifyContent: FlexAlign.SpaceBetween, // 主轴对齐：两端对齐
  alignItems: FlexAlign.Center,          // 交叉轴对齐：居中
  wrap: FlexWrap.Wrap
}) {
  // ... flex items
}

BarPosition

作用: 定义 Tabs 组件中 TabBar（标签栏）的位置。
枚举值: BarPosition.Start (顶部), BarPosition.End (底部)。
示例:

TypeScript

Tabs({ barPosition: BarPosition.End }) {
  // ... TabContent
}

4. 动画与转场类型

用于给 UI 增加动态效果。

AnimationOption

作用: 定义一个动画的详细参数，如时长、曲线、延迟等。
如何使用: 作为 .animation() 修饰器的参数。
属性: duration (时长), curve (动画曲线), delay (延迟), iterations (播放次数)。
示例:

TypeScript

@State widthValue: number = 100

Column() { /* ... */ }
  .width(this.widthValue)
  .backgroundColor(Color.Blue)
  .animation({
    duration: 1000, // 1秒
    curve: Curve.EaseInOut,
    delay: 200 // 延迟200ms
  })

Button('改变宽度')
  .onClick(() => { this.widthValue = 200 }) // 宽度变化会以动画形式展现

TransitionEffect

作用: 定义组件出现和消失时的转场动画效果。
如何使用: 在 .transition() 修饰器中使用。
常见效果: TransitionEffect.opacity(), TransitionEffect.slide(), TransitionEffect.scale(), TransitionEffect.move()。可以组合使用。
示例:

TypeScript

if (this.isVisible) {
  Text('Hello')
    .transition(TransitionEffect.slide(SlideEffect.Bottom)) // 从底部滑入
    .transition(TransitionEffect.opacity(0)) // 附加淡入效果
}

Curve

作用: 定义动画的速度曲线，决定动画过程是快是慢。
枚举值: Curve.Linear, Curve.Ease, Curve.EaseIn, Curve.EaseOut, Curve.EaseInOut, Curve.Spring (弹簧效果) 等。
示例: 见 AnimationOption 示例。

5. 手势类型

ArkTS 提供了封装好的手势类型，用于处理复杂的用户交互。

Gesture

作用: 这是一个基类，其子类包括 TapGesture (点击), LongPressGesture (长按), PanGesture (拖动), PinchGesture (捏合), RotationGesture (旋转) 等。
如何使用: 通过 .gesture() 修饰器将手势绑定到组件上，并通过 .onAction() 等方法监听手势事件。
示例:

TypeScript

@State position: Position = { x: 0, y: 0 }
@State scaleValue: number = 1

// 拖动手势
let panGesture = PanGesture()
  .onActionStart((event: GestureEvent) => { /* ... */ })
  .onActionUpdate((event: GestureEvent) => {
    this.position.x += event.offsetX
    this.position.y += event.offsetY
  })

// 捏合手势
let pinchGesture = PinchGesture()
  .onActionUpdate((event: GestureEvent) => {
    this.scaleValue = event.scale
  })

// 将手势绑定到组件
Image($r('...'))
  .position(this.position)
  .scale({ x: this.scaleValue, y: this.scaleValue })
  .gesture(panGesture) // 绑定拖动
  .gesture(pinchGesture, GesturePriority.Parallel) // 并行绑定捏合

6. 其他实用类型

Resource / $r

作用: Resource 是资源的类型，而 $r 是一个全局函数，用于从应用的 resources 目录中引用资源（如图片、字符串、颜色）。这是访问静态资源的推荐方式。
示例:

TypeScript

// 引用图片
Image($r('app.media.my_icon'))

// 引用字符串
Text($r('app.string.welcome_message'))

// 引用颜色
Column().backgroundColor($r('app.color.primary_color'))

EdgeInsets

作用: 定义内边距 (padding) 和外边距 (margin) 的类型。可以统一设置，也可以分四边设置。
示例:

TypeScript

Text('示例')
  .padding(10) // 四边都是 10

  .padding({
    top: 5,
    bottom: 5,
    left: 10,
    right: 10
  }) // 分别设置

Length / Dimension

作用: Length 是长度的通用类型，可以是 number (vp), string (px, %, fp)，或者 Resource。Dimension 是 Length 的一个别名，在新的 API 中更常用。
示例:

TypeScript

Column()
  .width(100)       // 100 vp
  .height('50%')    // 50% of parent height
  .fontSize('18fp') // 18 font-size pixels

ArkTS 中常用类型

ArkTS 常用 UI 相关类型详解

目录

1. 导航与工具栏类型

ToolbarItem

NavigationTitleMode

NavigationBackButtonPosition

2. 样式与外观类型

Color

FontWeight

FontStyle

TextAlign

ImageFit

BorderStyle

Visibility

3. 布局与对齐类型

Alignment

FlexDirection / FlexAlign / FlexWrap

BarPosition

4. 动画与转场类型

AnimationOption

TransitionEffect

Curve

5. 手势类型

Gesture

6. 其他实用类型

Resource / $r

EdgeInsets

Length / Dimension