HarmonyOS ArkTS 常用 UI 组件通用样式规范手册

2401_88832378

32人浏览 · 2026-06-18 11:35:56

2401_88832378 · 2026-06-18 11:35:56 发布

一、前言

在 HarmonyOS 应用开发过程中，统一的组件样式规范不仅可以让项目 UI 视觉保持一致性、降低多页面的视觉割裂感，还能大幅减少重复样式代码编写、提升团队协作开发效率。本文基于 ArkTS 开发中高频使用的轮播图、选项卡、文本、输入框、按钮、图片、单选框7 类核心组件，整理一套可直接落地复用的通用样式设计规范，同时附带代码示例，新手可直接参考复用。

二、基础通用样式设计规则

（一）尺寸规范（width/height）

页面根容器：统一设置width('100%')，让页面铺满设备屏幕宽度，避免左右留白适配异常。
输入框（TextInput）、常规业务按钮（Button）：固定高度50fp，符合移动端人体工学点击热区规范，既不会过于纤细导致点击困难，也不会占用过多页面高度。
头像类 Image 组件：必须使用正方形尺寸，推荐两套标准规格：100fp * 100fp、120fp * 120fp，统一头像展示比例。
轮播图（Swiper）：宽度 100% 铺满，高度根据业务场景固定（如 200fp/240fp），避免自适应高度造成页面布局抖动。

（二）颜色规范（backgroundColor/fontColor）

系统内置颜色：直接使用Color.xxx枚举值，例如Color.Red、Color.White、Color.Black，可读性高，适合通用场景。
十六进制颜色：格式为0x+八位十六进制数，前两位代表透明度，后六位代表 RGB 色值，示例：0xffddff（不透明浅粉色）。
透明背景：组件需要去除默认底色时，统一使用Color.Transparent透明背景，常用于选项卡、标签、自定义按钮场景。

（三）边距规范（padding 内边距 /margin 外边距）

padding（内边距）：控制组件内部内容与自身边框的距离，输入框、卡片、按钮建议统一设置水平内边距padding({left:16,right:16})，避免文字紧贴组件边缘。
margin（外边距）：控制当前组件和相邻其他组件之间的间距，页面全局统一基础间距16fp，模块之间使用24fp大间距，杜绝间距混乱。

（四）圆角规范（borderRadius）

按照组件类型固定圆角取值，保证视觉统一：

常规按钮 Button：圆角取值范围8fp ~ 12fp，推荐默认 12fp，视觉柔和不生硬。
卡片布局容器：圆角取值范围12fp ~ 16fp，推荐 16fp，区分按钮与卡片的视觉层级。
头像 Image 组件：圆角设置为宽高尺寸的一半，实现圆形头像效果，例如 100fp 正方形头像设置.borderRadius(50)。

（五）边框规范（border）

通用边框统一配置格式：

.border({width:1,color:0xaaffaa})

width：边框粗细，常规业务分割线统一 1fp；
color：边框颜色，浅灰色0xeeeeee作为默认分割线颜色，避免深色边框造成视觉压抑。

（六）阴影规范（shadow）

主要用于卡片类组件，营造凹凸分层视觉效果，通用卡片阴影模板：

.shadow({radius:8,color:0x1a000000,offsetX:2,offsetY:2})

radius：阴影模糊半径；
color：阴影颜色，推荐低透明度黑色；
offsetX/offsetY：阴影横向、纵向偏移量。

（七）透明度规范（opacity）

取值范围0 ~ 1：

opacity(0)：组件完全透明，不可见；
opacity(1)：组件完全不透明（默认值）；
禁用、置灰组件统一使用opacity(0.6)。

（八）图片缩放规范（objectFit）

Image().objectFit(ImageFit.Cover)：默认推荐，图片铺满组件区域，超出部分自动裁剪，保证不变形，适用于轮播图、头像、商品封面。
Image().objectFit(ImageFit.Contain)：图片完整展示在组件内，不会裁剪，会出现留白，适用于 Logo、图标类固定比例素材。

三、七大高频组件通用样式 + 代码示例

1. Button 按钮通用样式

// 主按钮通用样式
Button("提交")
  .width('100%')
  .height(50)
  .backgroundColor(0x007DFF)
  .fontColor(Color.White)
  .fontSize(18)
  .borderRadius(12)
  .margin({top:16,left:16,right:16})

2. TextInput 输入框通用样式

TextInput(this.username)
  .width('92%')
  .height(50)
  .placeholder("请输入用户名")
  .padding({left:16,right:16})
  .border({width:1,color:0xeeeeee})
  .borderRadius(12)
  .margin({top:16})

3. Image 图片 / 头像通用样式

// 圆形头像
Image($r("sys.media.user_icon"))
  .width(100)
  .height(100)
  .borderRadius(50)
  .objectFit(ImageFit.Cover)
  .margin({top:20})

// 轮播图图片
Image($r("sys.media.banner"))
  .width('100%')
  .height(220)
  .objectFit(ImageFit.Cover)

4. Text 文本通用样式

// 标题文本
Text("用户登录")
  .fontSize(22)
  .fontWeight(FontWeight.Bold)
  .fontColor(Color.Black)
  .margin({bottom:24})

// 常规说明文本
Text("请输入账号密码")
  .fontSize(14)
  .fontColor(0x666666)

5. Radio 单选框通用样式

Row() {
  Radio({value:"man",group:"gender"})
    .width(20)
    .height(20)
    .checkedColor(0x007DFF)
  Text("男").margin({left:6})
}
.margin({right:30})

6. 轮播图（Swiper）通用样式

Swiper() {
  Image($r("sys.media.banner1")).width('100%').height(220).objectFit(ImageFit.Cover)
  Image($r("sys.media.banner2")).width('100%').height(220).objectFit(ImageFit.Cover)
}
.width('100%')
.height(220)
.indicator(true)
.loop(true)

7. 选项卡（Tabs）通用样式

Tabs() {
  TabContent() {
    Text("页面1")
  }.tabBar("标签1")
  TabContent() {
    Text("页面2")
  }.tabBar("标签2")
}
.width('100%')
.barBackgroundColor(Color.Transparent)

四、规范落地价值总结

降低 UI 返工成本：统一尺寸、圆角、色值、边距标准，前端开发可严格按照设计规范还原效果图，减少设计反复对齐调整的工作量。
代码高复用：可将通用样式封装为公共自定义组件，全项目调用，避免大量重复样式冗余代码。
提升产品视觉质感：标准化的圆角、阴影、边距规则可以规避页面元素杂乱、比例失调问题，让应用整体设计更精致专业。
团队协作标准化：新人接手项目可直接查阅样式手册，快速对齐项目开发规范，保证多人开发下视觉风格统一。

五、结语

一套完善的组件通用样式规范，是中大型鸿蒙项目规范化开发的基础。本文覆盖了日常开发最高频的 7 类 UI 组件，从尺寸、颜色、边距、圆角、阴影、图片适配多维度制定统一标准，开发者可基于本规范根据产品品牌色微调色值，封装属于项目内部的样式公共库，高效实现高效、规范、统一的 HarmonyOS 应用开发。