HarmonyOS 6 ArkUI 像素单位使用文档

HarmonyOS 6 ArkUI 像素单位使用文档

单位基础说明

1. 核心单位释义

2. 数值写法规则

1. 纯数字：默认等价vp，例：width(220)=width('220vp')
2. 字符串带单位：明确指定单位，例：width('220px')、width('220lpx')
3. 动态计算值：支持表达式拼接、单位转换API返回值

示例代码

@Entry @Component struct Example { build() { Column() { Flex({ wrap: FlexWrap.Wrap }) { // 1. 纯数字写法，默认单位 vp Column() { Text("width(220)") .width(220) .height(40) .backgroundColor(0xF9CF93) .textAlign(TextAlign.Center) .fontColor(Color.White) .fontSize('12vp') }.margin(5) // 2. 显式指定 px 单位 Column() { Text("width('220px')") .width('220px') .height(40) .backgroundColor(0xF9CF93) .textAlign(TextAlign.Center) .fontColor(Color.White) }.margin(5) // 3. 显式指定 vp 单位（字符串格式） Column() { Text("width('220vp')") .width('220vp') .height(40) .backgroundColor(0xF9CF93) .textAlign(TextAlign.Center) .fontColor(Color.White) .fontSize('12vp') }.margin(5) // 4. lpx 逻辑像素，依赖全局 designWidth Column() { Text("width('220lpx') designWidth:720") .width('220lpx') .height(40) .backgroundColor(0xF9CF93) .textAlign(TextAlign.Center) .fontColor(Color.White) .fontSize('12vp') }.margin(5) // 5. vp 转 px：vp2px() 单位转换 Column() { Text("width(vp2px(220) + 'px')") .width(this.getUIContext().vp2px(220) + 'px') .height(40) .backgroundColor(0xF9CF93) .textAlign(TextAlign.Center) .fontColor(Color.White) .fontSize('12vp') }.margin(5) // 6. fp 字体专用单位 Column() { Text("fontSize('12fp')") .width(220) .height(40) .backgroundColor(0xF9CF93) .textAlign(TextAlign.Center) .fontColor(Color.White) .fontSize('12fp') }.margin(5) // 7. px 转 vp：px2vp() 单位转换 Column() { Text("width(px2vp(220))") .width(this.getUIContext().px2vp(220)) .height(40) .backgroundColor(0xF9CF93) .textAlign(TextAlign.Center) .fontColor(Color.White) .fontSize('12fp') }.margin(5) }.width('100%') } } }

运行效果如图：

代码逐段解析

1. 纯数字尺寸width(220)

• 写法：直接传入数字，默认单位为 vp
• 等价写法：width('220vp')
• 适用：常规布局宽高、间距，鸿蒙标准推荐写法。

2. 物理像素width('220px')

• 显式声明px单位，代表设备真实物理像素
• 特点：不同分辨率设备展示尺寸差异大，不推荐常规布局使用，仅用于对接原生接口、图片固定像素尺寸场景。

3. 字符串格式 vpwidth('220vp')

• 显式字符串声明 vp，语义更清晰，和纯数字写法效果完全一致
• 团队规范要求统一单位写法时可优先使用。

4. 逻辑像素width('220lpx')

• lpx基于全局配置的designWidth（设计稿宽度）做等比缩放
• 示例标注designWidth:720，表示以 720px 作为基准设计稿，多设备自动等比适配
• 适用：整套UI基于统一设计稿出图的跨设备项目。

5. vp 转 px：vp2px(value)

• API：this.getUIContext().vp2px(220)
• 作用：将虚拟像素 vp 换算为当前设备物理像素 px，返回数值可拼接px字符串使用
• 场景：需要向原生组件/系统接口传递物理像素尺寸时使用。

6. 字体单位fontSize('12fp')

• fp专门用于文字字号，会跟随系统「字体大小」设置动态变化
• 规范：文本字号禁止使用 vp/px，统一使用 fp。

7. px 转 vp：px2vp(value)

• API：this.getUIContext().px2vp(220)
• 作用：将物理像素 px 反向换算为虚拟像素 vp，直接作为尺寸参数传入
• 场景：已有图片/素材标注为 px，需要转为布局适配单位时使用。

运行效果

1. 页面使用流式弹性布局Flex(FlexWrap.Wrap)，所有示例卡片自动换行展示；
2. 纯数字220与'220vp'视觉宽度完全相同；
3. 220px在高分屏设备上会显示更小/更大，无自适应能力；
4. 220lpx根据全局设计稿宽度自动缩放，多设备视觉统一；
5. 转换API计算出的尺寸与直接书写对应单位效果一致；
6. fp字体可在系统设置调整字体大小后，实时看到文字缩放变化。

总结

1. 布局尺寸（宽/高/边距/圆角）：优先使用vp（纯数字 或xxvp）
2. 文本字号：强制使用fp
3. 统一设计稿跨端：使用lpx，并在项目入口配置designWidth
4. 对接原生/底层接口：使用px，配合vp2px/px2vp做转换

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力