二、鸿蒙开发-常用组件一(图片、文本、按钮、切换按钮)

提示：本文根据b站尚硅谷2024最新鸿蒙开发HarmonyOS4.0+鸿蒙NEXT星河版零基础教程课整理

链接指引 => 尚硅谷2024最新鸿蒙开发HarmonyOS4.0+鸿蒙NEXT星河版零基础教程

---

一、图片

1.1 参数

Image组件的参数类型为string | Resource | media.PixelMap

1.1.1 string类型

string类型的参数用于通过路径的方式引用图片，包括本地图片和网络图片。

• 本地图片

  Image('images/demo.jpg')

  注意：使用这种方式引入本地图片，需要将图片置于ets目录下，并且需要为Image组件提供图片相对于ets目录的路径。

• 网络图片

  Image('http://xxx/xxx.jpg')

  注意：真机中运行的鸿蒙应用，访问网络图片需要配置网络访问权限，不过在预览器和模拟器中测试时不受限制。权限配置相关的内容在后续章节会系统介绍。

1.1.2 Resource类型

Resource类型的参数用于引入 resources 目录下的图片。
resources目录用于统一存放应用所需的各种资源，包括图片、音频、视频、文本等等。下面简要介绍 resources 目录的用法，首先需要了解 resources 的目录结构，如下

resources 目录下，用于存放资源的子目录有（element、media、profile）和rawfile。下面分别介绍：

• element、media、profile

  （element、media、profile）可存在多种版本，用于适配不同的环境，例如语言环境（zh_CN和en_US）、系统主题（dark和light）、设备类型（phone 和 tablet） 等等。我们可以为上述每种环境各自准备一套资源文件，每种环境对应 resources 下的一个目录，例如上述的 zh_CN 和 en_US。我们在使用resources下的资源时，无需指定具体的环境版本，系统会根据设备所处的环境自动选择匹配的版本，例如当设备系统语言为中文时，则会使用zh_CN目录下的资源，为英文时，则会使用en_US目录下的资源。若没有与当前所处环境相对应的版本，则使用 base 目录下资源。

各目录存储的具体资源如下：

1. media：存放媒体资源，包括图片、音频、视频等文件。
2. element：存放用于描述页面元素的尺寸、颜色、样式等的各种类型的值，每种类型的值都定义在一个相应的 JSON 文件中。
3. profile：存放自定义配置文件。

• rawfile
  用于存储任意格式的原始文件，需要注意的是rawfile不会根据设备所处的环境去匹配不同的资源。

• media.PixelMap
  PixelMap指的是图片的像素位图，其通常是一个二维数组，数组中的每个元素对应着图片中的一个像素，其包含了该像素的颜色等信息。像素位图主要用于图片编辑的场景，例如
  

  1.1.3 常用属性

  1.1.3.1 图片尺寸

  图片尺寸可通过width()方法和height()方法进行设置。例如

  Image($r('app.media.img'))
    .width(100)
    .height(100)

  两个方法可接收的参数类型均为string | number | Resource

• string类型
  string类型的参数可为百分比，例如'100%'，或者为具体尺寸，例如'100px'。
  具体尺寸的单位，常用的有两个，分别是px和vp

  • px(Pixel)
    物理像素，以像素个数来定义图像尺寸。这种方式的弊端是，在不同像素密度的屏幕上，相同的像素个数对应的物理尺寸是不同的。这样一来就会导致我们的应用在不同设备上显示的尺寸可能不同。如下图所示
  • vp(Virtual Pixel)
    为了保证一致的观感，我们可以使用虚拟像素作为单位。虚拟像素是一种可根据屏幕像素密度灵活缩放的单位。1vp相当于像素密度为160ppi的屏幕上的1px。在不同像素密度的屏幕上，HarmonyOS会根据如下公式将虚拟像素换算为对应的物理像素

  

• number类型
  number类型的参数，默认以vp作为单位。
• Resource类型
  Resource类型参数用于引用resources下的element目录中定义的数值。
  引用element目录中的数值，同样需要使用$r()函数。要了解具体语法，需要先熟悉element目录下的文件内容。
  前文提到过，element目录中可保存各种类型的数值，且每种类型的值分别定义在一个JSON文件中。文件中的内容为键值对(name-value)的形式。具体内容如下

我们可以通过 name 引用相应的 value。具体语法为$r('app.<data_type>.<name>')。

注意：无需指定具体版本，系统会自动根据所处环境选择相应版本

例如上述的 greeting 的值，可通过$r('app.string.greeting')引用，width的值可通过$r('app.integer.width')。

1.1.3.2 图片缩放

当图片的原始大小与Image组件不同时，可通过objectFit()方法来设置图片的显示效果。该方法的参数类型为ImageFit枚举类型，可选的枚举值如下

名称	描述
ImageFit.None	保持原有尺寸显示，不做任何缩放，超出显示区域的部分不显示。
ImageFit.Contain	保持宽高比进行缩小或者放大，使得显示区域刚好包含整个图片。
ImageFit.Cover	保持宽高比进行缩小或者放大，使得图片刚好完全覆盖显示区域。
ImageFit.Fill	不保持宽高比进行放大缩小，使得图片充满显示区域。
ImageFit.ScaleDown	保持宽高比进行缩小或不变（不会放大），使得图片完全显示在显示区域内。
ImageFit.Auto	自适应显示

1.1.3.3 图片插值

当原图分辨率较低并且需要放大显示时，图片会模糊并出现锯齿。如下图所示

这时可以使用interpolation()方法对图片进行插值，使图片显示得更清晰。该方法的参数为ImageInterpolation枚举类型，可选的值有

| 名称 | 描述|
| --|-- |
| ImageInterpolation.None | 不使用图片插值。|
| ImageInterpolation.High | 高质量插值，可能会影响图片渲染的速度。|
| ImageInterpolation.Medium | 中等质量插值。|
| ImageInterpolation.Low | 低等质量插值。|

各选项效果如下图所示

二、文本

2.1 参数

Text组件的参数类型为string | Resource

• string类型

  Text('我是一段文本')

• Resource 类型
  Resource类型的参数用于引用 resources/*/element目录中定义的字符串，同样需要使用$r()引用。
  例如resources/base/element目录中有一个string.json文件，内容如下

  {
    "string": [
      {
        "name": "greeting",
        "value": "你好"
      }
    ]
  }

  此时我们便可通过如下方式引用并显示greeting的内容。

  Text($r('app.string.greeting'))

2.2 常用属性

2.2.1 字体大小

字体大小可通过fontSize()方法进行设置，该方法的参数类型为string | number| Resource，下面逐一介绍

• string类型
  string类型的参数可用于指定字体大小的具体单位，例如fontSize('100px')，字体大小的单位支持px、fp。其中fp(font pixel)与vp类似，具体大小也会随屏幕的像素密度变化而变化。
• number类型
  number类型的参数，默认以fp作为单位。
• Resource类型
  Resource类型参数用于引用resources下的element目录中定义的数值。

2.2.2 字体粗细

字体粗细可通过fontWeight()方法进行设置，该方法参数类型为number | FontWeight | string，下面逐一介绍

• number类型
  number类型的取值范围是[100,900]，取值间隔为100，默认为400，取值越大，字体越粗。

• FontWeight类型
  FontWeight为枚举类型，可选枚举值如下

  | 名称 | 描述 |
  |--|--|
  | FontWeight.Lighter | 字体较细。|
  | FontWeight.Normal | 字体粗细正常。|
  | FontWeight.Regular| 字体粗细正常。|
  | FontWeight.Medium | 字体粗细适中。|
  | FontWeight.Bold | 字体较粗。|
  | FontWeight.Bolder | 字体非常粗。|

• string类型
  string类型的参数仅支持number类型和FontWeight类型参数的字符串形式，例如例如'100'和bold。

2.2.3 字体颜色

字体颜色可通过fontColor()方法进行设置，该方法参数类型为Color | string | number | Resource，下面逐一介绍

• Color类型
  Color为枚举类型，其中包含了多种常用颜色，例如Color.Green
• string类型
  string类型的参数可用于设置 rgb 格式的颜色，具体写法可以为'rgb(0, 128, 0)'或者'#008000'
• number类型
  number类型的参数用于使用16进制的数字设置 rgb 格式的颜色，具体写法为0x008000
• Resource类型
  Resource类型的参数用于应用resources下的element目录中定义的值。

2.2.4 文本对齐

文本对齐方向可通过textAlign()方法进行设置，该方法的参数为枚举类型TextAlign，可选的枚举值如下

名称	描述
TextAlign.Start	首部对齐
TextAlign.Center	居中对齐
TextAlign.End	尾部对齐

各选项效果如下

2.2.5 最大行数和超长处理

可使用maxLines()方法控制文本的最大行数，当内容超出最大行数时，可使用textOverflow()方法处理超出部分，该方法的参数类型为{ overflow: TextOverflow }，其中TextOverflow为枚举类型，可用枚举值有

名称	描述
TextOverflow.Clip	文本超长时，进行裁剪显示。
TextOverflow.Ellipsis	文本超长时，显示不下的文本用省略号代替。

各选项效果如下

三、按钮

3.1 参数

Button组件有两种使用方式，分别是不包含子组件和包含子组件，两种方式下，Button 组件所需的参数有所不同，下面分别介绍

• 不包含子组件
  不包含子组件时，Button组件所需的参数如下

  Button(label?: string, options?: { type?: ButtonType, stateEffect?: boolean })

  • label
    label为按钮上显示的文字内容。

  • options.type
    options.type为按钮形状，该属性的类型ButtonType，可选的枚举值有

    名称	描述	效果
    ButtonType.Capsule	胶囊形状
    ButtonType.Circle	圆形
    ButtonType.Normal	普通形状

  • options.stateEffect
    options.stateEffect表示是否开启点击效果

• 包含子组件
  子组件会作为按钮上显示的内容，可以是图片、文字等。这种方式下，Button组件就不在需要label参数了，具体如下

  Button(options?: {type?: ButtonType, stateEffect?: boolean})

3.2 常用属性

3.2.1 背景颜色

按钮的颜色可使用backgroundColor()方法进行设置，例如

Button('绿色按钮').backgroundColor(Color.Green)

3.2.2 边框圆角

按钮的边框圆角大小可使用borderRadius()方法进行设置，例如

Button('圆角按钮', { type: ButtonType.Normal }).borderRadius(10)

3.3 常用事件

对于Button组件而言，最为常用的就是点击事件，可以通过onClick()方法为按钮绑定点击事件，该方法的参数为一个回调函数，当按钮被点击时，就会触发该回调函数，例如

Button('点击事件').onClick(() => {
  console.log('我被点击了')
})

四、切换按钮

4.1 参数

Toggle组件的参数定义如下

Toggle(options: { type: ToggleType, isOn?: boolean })

• type
  type属性用于设置Toggle组件的类型，可通过ToggleType枚举类型进行设置，可选的枚举值如下
  | 名称 | 描述 | 效果 |
  |--|--|--|
  | ToggleType.Switch | 开关 | |
  | ToggleType.Checkbox | 复选框 | |
  | ToggleType.Button | 按钮 | |
• isOn
  isOn属性用于设置Toggle组件的状态，例如

• 例子：

  @Entry
  @Component
  struct ToggleParameter {
    build() {
      Column({ space: 20 }) {
        Row({ space: 20 }) {
          Toggle({ type: ToggleType.Switch, isOn: false })
          Toggle({ type: ToggleType.Switch, isOn: true })
        }
  
        Row({ space: 20 }) {
          Toggle({ type: ToggleType.Checkbox, isOn: false })
          Toggle({ type: ToggleType.Checkbox, isOn: true })
        }
  
        Row({ space: 20 }) {
          Toggle({ type: ToggleType.Button, isOn: false }) {
            Text('button')
          }
  
          Toggle({ type: ToggleType.Button, isOn: true }) {
            Text('button')
          }
        }
      }.width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
  }

4.2 常用属性：

• 选中状态背景色
  可使用selectedColor()方法设置Toggle组件在选中（或打开）状态下的背景色，例如
  
• Swtich滑块颜色
  可使用设置switchPointColor()方法设置Switch类型的Toggle组件中的圆形滑块颜色，例如
  

4.3 常用事件

Toggle组件常用的事件为change事件，每当Toggle组件的状态发生变化，就会触发change事件。开发者可通过onChange()方法为Toggle组件绑定change事件，该方法参数为一个回调函数，具体定义如下

onChange(callback: (isOn: boolean) => void)

当Toggle组件的状态由关闭切换为打开时，isOn为true，从打开切换为关闭时，isOn为false。

例:

@Entry
@Component
struct LightPage {
  @State isOn: boolean = false;

  build() {
    Column({ space: 20 }) {
      if (this.isOn) {
        Image($r('app.media.img_light'))
          .height(300)
          .width(300)
          .borderRadius(20)
      } else {
        Image($r('app.media.img_dark'))
          .height(300)
          .width(300)
          .borderRadius(20)
      }
      Toggle({ type: ToggleType.Switch, isOn: this.isOn })
        .width(60)
        .height(30)
        .onChange((isOn) => {
          this.isOn = isOn;
        })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}