鸿蒙开发实战：width()/height() API 全解析

前言：在鸿蒙 HarmonyOS ArkTS 开发中，`width()` 和 `height()` 是最基础、最常用的尺寸设置 API。无论是 Image、Text、Button 还是布局组件（Column、Row），只要需要设置宽高，都离不开这两个方法！

m0_68110835

102人浏览 · 2026-03-29 17:11:59

m0_68110835 · 2026-03-29 17:11:59 发布

🔥 前言：在鸿蒙 HarmonyOS ArkTS 开发中，width() 和 height() 是最基础、最常用的尺寸设置 API。无论是 Image、Text、Button 还是布局组件（Column、Row），只要需要设置宽高，都离不开这两个方法！

📌 本文核心：width()/height() 通用规则 + 3种参数详解 + 完整可运行Demo + 单位避坑指南

一、核心结论：width() 与 height() 完全通用

鸿蒙中所有组件的 width()（设置宽度）和 height()（设置高度）方法，参数类型、写法规则完全一致，无需单独记忆，掌握一个，另一个直接复用。

1. 通用参数类型（必记）

// width() 和 height() 通用参数类型
参数类型: string | number | Resource

2. 全组件通用示例（高频场景）

组件	width()/height() 用法示例	说明
Image（图片）	Image($r(‘app.media.img’)).width(100).height(100)	设置图片宽高，最常用场景
Text（文本）	Text(‘文本’).width(‘100%’).height(50)	文本宽高适配布局
Button（按钮）	Button(‘按钮’).width(150).height(60)	固定按钮尺寸，提升交互体验
Column/Row（布局）	Column().width(‘100%’).height(‘100%’)	布局宽高占满父组件
重点：width() 和 height() 写法完全一致，仅作用不同（一个控宽度，一个控高度）；所有组件通用，无特殊例外。

二、3种通用参数详解

以下3种参数写法，同时适用于 width() 和 height()，结合具体场景演示，复制即可直接使用，新手也能快速上手。

1. string 字符串类型（灵活适配，最常用）

string 类型支持 百分比 和 具体尺寸（带单位） 两种写法，可满足大部分布局场景，适配不同屏幕尺寸。

两种写法格式（必记）

百分比格式：'100%'、'50%'，表示占父组件对应宽/高的百分比，适配性最强；
具体尺寸格式：'数值+单位'，常用单位为 px 和vp（下文详细讲解两者区别）。

常用单位详解（避坑关键）

px（像素）：固定像素值，不随屏幕分辨率、尺寸变化，适合固定尺寸场景（如小图标），但适配性差；
vp（虚拟像素）：鸿蒙推荐单位，会根据屏幕分辨率自动缩放，保证在不同设备上显示效果一致，优先使用。

通用示例（width() 和 height() 通用）

// 1. 百分比写法（占父组件100%宽度，50%高度）
.width('100%')
.height('50%')

// 2. px单位（固定尺寸，不缩放）
.width('450px')
.height('450px')

// 3. vp单位（推荐，自动适配屏幕）
.width('150vp')
.height('150vp')

2. number 数字类型（简洁高效，默认vp单位）

number 类型直接传入数字，无需写单位，默认使用 vp 作为单位，语法简洁，适合快速开发，与 '数值vp' 效果完全一致。

格式规则

直接传入数字（整数/小数均可），系统自动解析为 vp 单位，例如：width(150) 等价于 width('150vp')。

通用示例

// 数字类型（默认vp单位）
Image($r('app.media.img_harmony'))
  .width(150) // 等价于 width('150vp')
  .height(150) // 等价于 height('150vp')

// 小数示例（适配精细尺寸）
Text('精细尺寸')
  .width(80.5)
  .height(30.5)

3. Resource 资源类型（企业级规范，统一管理）

Resource 类型用于引用 resources/element 目录下定义的数值资源，适合项目统一尺寸管理、多端适配，避免重复写数值，便于后期维护（与颜色资源引用逻辑一致）。

步骤1：定义尺寸资源（element目录下）

鸿蒙 element 目录中，不同类型的数值保存在对应 JSON 文件中，尺寸数值通常定义在 integer.json（整数）或 string.json（字符串）中，格式为键值对（name-value）。

// element/integer.json（推荐，用于整数尺寸）
{
  "integer": [
    {
      "name": "img_width",
      "value": 150 // 数值，默认vp单位
    },
    {
      "name": "img_height",
      "value": 150
    },
    {
      "name": "btn_width",
      "value": 200
    }
  ]
}

// element/string.json（可选，用于带单位的尺寸字符串）
{
  "string": [
    {
      "name": "layout_width",
      "value": "100%"
    },
    {
      "name": "small_img_size",
      "value": "80vp"
    }
  ]
}

步骤2：代码中引用资源（通用写法）

使用 $r('app.<data_type>.<name>') 语法引用，无需指定版本，系统自动适配当前环境，注意资源名称与 JSON 文件中一致。

// 引用 integer.json 中的整数尺寸（默认vp）
Image($r('app.media.img_harmony'))
  .width($r('app.integer.img_width'))
  .height($r('app.integer.img_height'))

// 引用 string.json 中的字符串尺寸
Column()
  .width($r('app.string.layout_width'))
  .height($r('app.string.small_img_size'))

// 按钮尺寸引用
Button('确认')
  .width($r('app.integer.btn_width'))
  .height(50)

三、完整实战代码（可直接复制运行）

以下代码演示了 width()/height() 三种参数的所有用法，以 Image 组件为例（其他组件用法完全一致），复制到项目中即可运行，直观感受不同参数的效果。

@Entry
@Component
struct WidthHeightDemo {
  build() {
    Column({ space: 30 }) {
      // 标题
      Text('width()/height() 全参数演示')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .width('100%')
        .textAlign(TextAlign.Center)

      // 第一行：string类型（px + vp）
      Row({ space: 40 }) {
        Column() {
          Image($r('app.media.img_harmony'))
            .width('450px') // string类型 + px单位
            .height('450px')
          Text('宽高:450px（固定像素）')
            .fontSize(16)
            .marginTop(10)
        }

        Column() {
          Image($r('app.media.img_harmony'))
            .width('150vp') // string类型 + vp单位（推荐）
            .height('150vp')
          Text('宽高:150vp（自动适配）')
            .fontSize(16)
            .marginTop(10)
        }
      }

      // 第二行：number类型 + Resource类型
      Row({ space: 40 }) {
        Column() {
          Image($r('app.media.img_harmony'))
            .width(150) // number类型（默认vp）
            .height(150)
          Text('宽高:150（默认vp）')
            .fontSize(16)
            .marginTop(10)
        }

        Column() {
          Image($r('app.media.img_harmony'))
            .width($r('app.integer.img_width')) // Resource类型
            .height($r('app.integer.img_height'))
          Text('宽高:150（资源引用）')
            .fontSize(16)
            .marginTop(10)
        }
      }

    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .padding(20)
  }
}