鸿蒙应用开发UI基础第八节: ArkTS声明式UI与页面基础结构

鸿蒙ArkTS UI开发基础摘要本文介绍了鸿蒙ArkTS声明式UI开发的核心要点：声明式与命令式UI对比：声明式UI关注"是什么"，通过数据驱动视图自动更新；命令式UI关注"怎么做"，需手动控制每个步骤。 ArkTS页面核心结构：必须包含@Entry、@Component、struct和build()函数一个文件只能有一个@Entry build()

weixin_35045177

80人浏览 · 2026-03-06 10:58:27

weixin_35045177 · 2026-03-06 10:58:27 发布

【学习目标】

理解声明式UI与命令式UI的核心差异，建立“数据驱动视图”的核心认知；
熟练掌握ArkTS页面核心结构（@Entry/@Component + build函数），能独立搭建标准页面骨架；
掌握vp/fp/px/lpx等尺寸单位的适用场景与适配原则，熟练使用系统原生尺寸转换方法，养成规范的单位使用习惯；
学会使用@State状态变量，实现“数据修改→UI自动刷新”的基础交互；
能快速定位并解决多根组件、UI不刷新、尺寸适配等新手高频页面问题。

【课前铺垫】

从本节开始，我们正式进入ArkTS UI开发的核心阶段：声明式UI开发。这是鸿蒙官方推荐的主流开发方式，也是让应用“看得见、可交互”的关键。本节将围绕“页面基础结构”展开，从页面核心组成、多设备尺寸适配，到数据驱动UI刷新，全方位解析声明式UI的核心逻辑，学好这些内容能为后续组件、布局、状态管理的学习筑牢基础。

先思考几个核心问题，带着问题学习更高效：

为什么鸿蒙优先推荐声明式UI？它比传统命令式UI更高效的核心原因是什么？
一个可运行的ArkTS页面，哪些结构是缺一不可的？少了会导致什么问题？
vp和fp是什么，有什么区别？为什么同样的尺寸在平板和手机上显示效果不同？
修改变量后UI不刷新，大概率是哪里出了问题？
特殊场景需要px与vp/fp互转时，如何使用系统原生方法实现？

一、工程结构

本节创建新工程AppDemo（基于鸿蒙API 12+/Stage模型），聚焦讲解UI页面的基本组成和声明式UI，工程核心目录结构如下：

AppDemo
├── AppScope                 # 应用全局配置目录
│   └── app.json5            # 全局配置（包名/应用名称/图标/版本等）
├── entry                    # 主模块目录（Entry HAP，应用核心代码包）
│   ├── src/main
│   │   ├── ets              # ArkTS代码核心目录
│   │   │   ├── common       # 新增：通用工具/常量目录
│   │   │   │   └── constants  
│   │   │   │       └── LayoutConstants.ets # 通用布局常量
│   │   │   ├── entryability # UIAbility组件目录
│   │   │   └── pages        # Page页面目录
│   │   │       └── Index.ets    # 工程默认首页
│   │   ├── resources        # 资源文件目录（字体/文字/数值等放这里）
│   │   │   └── base
│   │   │       ├── element
│   │   │       │   ├── float.json # 字体大小（fp）/数值型资源
│   │   │       │   └── string.json # 字符串型资源（页面文字/提示语等）
│   │   │       └── profile
│   │   └── module.json5     # 模块配置文件
└── 其他目录（构建/测试/配置相关）

二、声明式UI与命令式UI核心差异

两种UI开发模式的本质区别在于关注焦点和UI更新逻辑，通过对比能更清晰理解声明式UI的优势：

1. 核心思维

命令式UI：关注“怎么做”，需要开发者编写每一步操作指令（创建组件→设置属性→添加事件→手动更新），全程掌控UI的绘制和修改。
声明式UI：关注“是什么”，只需描述UI的最终状态和数据关联关系，框架自动处理渲染、更新逻辑，数据变化时UI自动刷新。

2. 代码对比（实现“点击按钮变色”）

命令式UI（iOS原生Swift）

import UIKit

class ViewController: UIViewController {
    var btn: UIButton!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        btn = UIButton(type: .system)
        btn.setTitle("点击变色", for: .normal)
        btn.backgroundColor = UIColor(red: 0/255, green: 125/255, blue: 255/255, alpha: 1)
        btn.setTitleColor(.white, for: .normal)
        btn.frame = CGRect(x: 100, y: 200, width: 200, height: 80)
        btn.addTarget(self, action: #selector(btnClick), for: .touchUpInside)
        
        self.view.addSubview(btn)
    }
    
    @objc func btnClick() {
        btn.backgroundColor = UIColor(red: 255/255, green: 103/255, blue: 0/255, alpha: 1)
    }
}

声明式UI（ArkTS）

// 引入通用布局常量
import { LayoutConstants } from '../common/constants/LayoutConstants';

// 声明页面入口
@Entry
// 声明组件
@Component
struct Index {
    // 状态变量：被@State修饰，数据与UI绑定，修改后自动刷新
    @State btnColor: string = "#007dff";
    
    // build()内定义组件层级和属性
    build() {
        Column({ space: 20 }) {
            Button("点击变色")
                .backgroundColor(this.btnColor) 
                .width(200) // 数值无单位默认vp
                .height(80)
                .fontSize($r('app.float.font_size_normal'))
                .onClick(() => {
                    // 点击修改颜色
                    this.btnColor = "#ff6700"; 
                });
        }
        .width(LayoutConstants.FULL_WIDTH) // 设置根组件宽度
        .height(LayoutConstants.FULL_HEIGHT) // 设置根组件高度
        .justifyContent(FlexAlign.Center);
    }
}

三、ArkTS页面核心结构

一个可运行的ArkTS页面，必须包含入口标记、组件标记、结构体、UI构建函数四大核心部分，缺一不可。

1. 核心组成详解

组成部分	作用说明	核心禁忌
`@Entry`	页面入口标识，告知系统该组件可作为独立页面加载	一个文件仅能有一个@Entry，否则编译报错
`@Component`	自定义组件标识，所有UI组件（页面级/子组件级）都需添加	无此标识，结构体无法作为UI组件使用，编译直接报错
`struct`	ArkTS组件的核心载体，基于结构体实现，无需继承类	命名需大驼峰（如HomePage），小写开头会报语法警告
`build()`函数	唯一的UI构建函数，仅负责描述UI结构	1. 禁止编写业务逻辑（console.log/网络请求等）；2. 必须只有一个根组件

2. 核心禁忌（新手必避）

❌ 禁止一个文件多个@Entry：编译直接报错，需拆分组件或页面。
❌ 禁止build()函数多根组件：多根组件报错In an '@Entry' decorated component, the 'build' method can have only one root node, which must be a container component. <ArkTSCheck>。
❌ 禁止在build()函数写非UI逻辑：如console.log、网络请求等，需封装到独立方法中，在事件回调（如onClick）或生命周期中调用。

四、多设备尺寸适配

4.1 为什么需要尺寸适配？—— 屏幕底层逻辑

（1）屏幕尺寸的核心定义

我们常说的6.7英寸手机 11英寸平板，这里的“英寸”是屏幕 发光区域对角线的物理长度：
物理尺寸

单位换算：1英寸 = 2.54厘米
计算公式： $对角线长度=屏幕宽度2+屏幕高度2\text{对角线长度} = \sqrt{\text{屏幕宽度}^2 + \text{屏幕高度}^2}$

（2）影响显示效果的三大核心概念

物理尺寸：屏幕实际大小（英寸），决定设备握持感；
分辨率：屏幕横向和纵向的物理像素总数（px），如1080×2340，代表屏幕“精细度”；
像素密度（PPI）：每英寸屏幕包含的物理像素数，是影响显示效果的核心参数。PPI数值越高，像素点越密集，屏幕显示越细腻（手机PPI≈400+，平板PPI≈200+）。

（3）适配的核心痛点

px（物理像素）是屏幕硬件的最小显示单元，直接与屏幕PPI绑定，导致相同px值在不同设备上视觉大小差异极大：

100px按钮在普通手机（中等PPI）上大小适中；
在高清屏上，因像素点更密，100px按钮视觉上极小；
在低像素平板上，因像素点更疏，100px按钮视觉上极大。

为解决这种差异，鸿蒙引入了vp+lpx+fp 三位一体的单位体系：

vp 解决“密度差异”，保证触控区域物理大小一致；
lpx 解决“尺寸差异”，保证布局比例适配不同宽度屏幕；
fp 解决“字体适配”，兼容系统字体缩放的无障碍需求。

虚拟像素

4.2 鸿蒙核心尺寸单位（标准定义+核心价值）

单位	完整名称	定义	核心价值	适用场景
px	物理像素	1px 代表屏幕上的一个实际像素点，与设备分辨率直接相关。例如：1920x1080 表示横向1920px，纵向1080px。	像素级精准控制	❌ 仅用于Canvas绘制、图标资源等无需适配的场景，禁止普通布局使用
vp	虚拟像素	根据屏幕密度动态转换物理像素，公式：vp = px / (DPI/160)。默认单位（数值不带单位时默认为vp）。	保障不同密度设备的物理尺寸一致（如按钮触控区均为1cm²）	✅ 组件尺寸（宽/高）、间距/边距，保证触控体验一致性
fp	字体像素	默认与 vp 等值（1fp=1vp），但会随系统字体设置缩放： 1fp = 1vp × scale（scale 为用户字体缩放系数）。	继承vp的密度适配，额外支持系统字体缩放	✅ 所有文字的fontSize（唯一推荐单位），兼容无障碍设置
lpx	逻辑像素	基于屏幕实际宽度与逻辑宽度（`designWidth`，默认720）的比值计算： 1lpx = (屏幕宽度px / designWidth)。	保障不同宽度设备的布局比例一致	✅ 流式布局宽度（列表/栅格）、响应式间距，适配多尺寸屏幕

4.3 “vp+lpx”组合适配（实战核心原则）

lpx是鸿蒙适配多尺寸屏幕的关键单位，但必须与vp配合使用，二者缺一不可：

维度	推荐单位	核心目的	示例场景
组件尺寸/间距	vp	保证触控体验（按钮、输入框等可交互区域物理大小一致）	按钮高度80vp、组件间距16vp
宽度/布局比例	lpx	适配不同宽度屏幕（大屏/小屏布局比例协调）	列表项宽度700lpx、栅格列宽120lpx
字体大小	fp	兼容系统字体缩放（无障碍适配）	正文20fp、标题24fp

示例：720px设计稿的列表项宽度为360px → 代码中用360lpx，在1440px宽平板上自动变为720px，比例始终占屏幕宽度50%；同时列表项高度设为80vp，保证触控高度一致。

4.4 系统原生尺寸转换方法

鸿蒙系统在UIContext中内置了完整的尺寸转换方法，适配当前UI实例所在屏幕的像素比例：

vp2px(value: number): number：将vp单位值转换为px单位值；
px2vp(value: number): number：将px单位值转换为vp单位值；
fp2px(value: number): number：将fp单位值转换为px单位值；
px2lpx(value: number): number：将px单位值转换为lpx单位值；

调用规则：需通过当前组件的this.getUIContext()获取上下文后调用，且建议增加空值安全处理，避免上下文未就绪导致的异常：

// 安全调用示例：空值兜底避免崩溃
const pxValue = this.getUIContext()?.vp2px(100) ?? 100; // vp转px
const lpxValue = this.getUIContext()?.px2lpx(200) ?? 200; // px转lpx

注意：

getUIContext() 禁止在 build() 中直接调用，应在 onClick、onPageShow 等生命周期或事件回调中使用；

折叠屏设备中，lpx 转换值会随折叠状态动态变化，需做好适配处理；

若UI稿基于720px宽度设计，直接使用lpx可实现像素级等比缩放（如设计稿100px → 代码100lpx）。

4.5 核心配置文件

（1）全局通用布局常量

路径：entry/src/main/ets/common/constants/LayoutConstants.ets

/**
 * 全局通用布局常量
 * 统一管理百分比、基础间距等，避免硬编码，提升适配一致性
 */
export class LayoutConstants {
    // 宽度常量
    public static readonly FULL_WIDTH: string = '100%';
    public static readonly HALF_WIDTH: string = '50%';
    // 高度常量
    public static readonly FULL_HEIGHT: string = '100%';
    // 基础间距/内边距（vp单位，保证触控体验）
    public static readonly BASE_PADDING: number = 24;
    public static readonly BASE_SPACE: number = 16;
}

（2）字体大小资源文件（float.json）

路径：entry/src/main/resources/base/element/float.json

{
  "float": [
    {
      "name": "font_size_normal",
      "value": "20fp"
    },
    {
      "name": "font_size_medium",
      "value": "24fp"
    },
    {
      "name": "font_size_large",
      "value": "30fp"
    },
    {
      "name": "font_size_counter",
      "value": "26fp"
    },
    {
      "name": "button_size_width",
      "value": "200vp" // 按钮宽度用vp，保证触控大小
    },
    {
      "name": "list_item_width",
      "value": "700lpx" // 列表项宽度用lpx，适配屏幕比例
    },
    {
      "name": "list_item_height",
      "value": "80vp" // 列表项高度用vp，保证触控体验
    }
  ]
}

（3）文字资源文件（string.json）

路径：entry/src/main/resources/base/element/string.json

{
  "string": [
    {
      "name": "page_title_main",
      "value": "从页面结构、尺寸适配到数据驱动的全方位解析"
    },
    {
      "name": "page_title_home",
      "value": "我的首页"
    },
    {
      "name": "btn_click_change",
      "value": "点击变色"
    },
    {
      "name": "text_counter",
      "value": "当前计数："
    },
    {
      "name": "btn_change_color",
      "value": "点击按钮修改颜色"
    }
  ]
}

4.6 适配黄金法则（标准化规范）

通用布局抽常量：100%/50%等全项目通用百分比、基础间距，统一抽离到LayoutConstants；
字体大小必抽离：所有fontSize必须通过$r('app.float.xxx')引用float.json，禁止硬编码，且必须使用fp单位；
页面文字必抽离：所有页面/按钮/提示文字必须通过$r('app.string.xxx')引用string.json，禁止硬编码；
单位组合规范（核心）：
- 尺寸/间距用vp：保证按钮、输入框等可交互区域的触控体验；
- 宽度/布局比例用lpx：适配不同宽度屏幕，保证布局比例协调；
- 文字大小用fp：兼容系统字体缩放，满足无障碍适配要求；
- 仅Canvas/图标资源可用px，禁止用于普通布局；
转换慎使用：特殊场景需单位转换时，仅使用系统原生UIContext方法，禁止自定义换算公式。

五、核心实战：@State与数据驱动UI（完整示例）

import { LayoutConstants } from '../common/constants/LayoutConstants';

@Entry
@Component
struct Index {
  // @State 基础状态装饰器：修改后自动驱动UI刷新
  @State btnColor: string = "#007dff";
  @State count: number = 0;

  build() {
    Column({ space: LayoutConstants.BASE_SPACE }) {
      // 标题：字体用fp，兼容系统缩放
      Text($r('app.string.page_title_main'))
        .fontSize($r('app.float.font_size_medium'))

      // 按钮：尺寸用vp保证触控，字体用fp
      Button($r('app.string.btn_click_change'))
        .backgroundColor(this.btnColor)
        .width($r('app.float.button_size_width')) // vp单位
        .height(80) // 默认vp，保证触控高度
        .fontSize($r('app.float.font_size_normal')) // fp单位
        .onClick(() => {
          this.btnColor = "#ff6700";
        });

      // 计数器展示：字体用fp
      Text() {
        Span($r('app.string.text_counter'))
        Span(`${this.count}`)
      }
      .fontSize($r('app.float.font_size_counter'));

      // 计数器按钮组：宽度用lpx适配比例，高度用vp保证触控
      Row({ space: 20 }) {
        Button("计数增加")
          .width($r('app.float.list_item_width')) // lpx单位，适配屏幕宽度
          .height($r('app.float.list_item_height')) // vp单位，保证触控
          .onClick(() => {
            this.count++;
          });

        Button("计数减少")
          .width($r('app.float.list_item_width'))
          .height($r('app.float.list_item_height'))
          .onClick(() => {
            this.count--;
          });
      }
      .width('80%') // 百分比适配外层容器
    }
    .width(LayoutConstants.FULL_WIDTH)
    .height(LayoutConstants.FULL_HEIGHT)
    .justifyContent(FlexAlign.Center);
  }
}

【新手排查】UI不刷新/适配异常常见原因：

动态变量未加 @State 装饰器（普通变量修改后无法触发UI刷新）；

单位使用错误：如用px设置按钮尺寸，导致不同设备触控体验差；用vp设置宽屏布局，导致大屏比例失衡；

直接修改对象/数组内部属性（需整体重新赋值才能触发刷新）；

lpx使用时未结合vp，导致布局比例适配但触控区域大小失控。