第2章基础组件入门

2、基础组件入门：Text、Button、Image、TextInput 与通用属性

好，咱们今天聊聊鸿蒙开发里最基础、也最常用的几个组件。说实话，不管多复杂的界面，最后拆解下来，都是这些基础组件的组合。我刚开始接触鸿蒙时，也以为这些组件很简单，不就是显示文字、点个按钮嘛。但真正做项目才发现，每个组件都有不少门道。

这一节，我会带着大家把 Text、Button、Image、TextInput 这四个组件过一遍，再聊聊它们的通用属性。嗯，咱们开始吧。

2.1 Text 组件：不只是显示文字

Text 组件，说白了就是用来展示文本的。但你别小看它，我见过不少新手直接拿它当「万能文本容器」，结果排版乱得一塌糊涂。

先看一个最简单的例子：

Text("你好，鸿蒙！")
    .fontSize(20)
    .fontColor(Color.Blue)
    .fontWeight(FontWeight.Bold)

这段代码会显示一行蓝色、加粗、20号大小的文字。嗯，很直观对吧？

但实际项目中，我们经常需要处理多行文本。比如用户协议、商品描述这些。这时候就要用到 .maxLines() 和 .textOverflow() 了。

核心经验： 我建议所有需要展示长文本的地方，都加上 .maxLines() 限制。否则一旦数据异常，整个布局可能被撑变形。

Text("这是一段很长的文本，可能会超出显示区域，我们需要对它进行截断处理。")
    .maxLines(2)
    .textOverflow({ overflow: TextOverflow.Ellipsis })

这样，超过两行的内容就会显示为「...」。用户体验会好很多。

另外，Text 还支持富文本样式。比如你想让一段文字里某些词变颜色：

Text() {
    Span("点击")
    Span("这里").fontColor(Color.Red).fontWeight(FontWeight.Bold)
    Span("查看更多详情")
}

这个技巧我在做「用户协议」页面时用过，效果很不错。

2.2 Button 组件：交互的起点

Button 是用户和界面交互最直接的方式。我个人习惯把按钮分为三类：主按钮、次按钮、文字按钮。

类型	使用场景	样式建议
主按钮	提交、确认、保存	填充色 + 白色文字
次按钮	取消、返回、次要操作	边框 + 透明背景
文字按钮	查看详情、跳转链接	纯文字，无边框

看一个实际例子：

Button("提交订单")
    .type(ButtonType.Capsule)
    .backgroundColor(Color.Blue)
    .fontColor(Color.White)
    .width(200)
    .height(48)
    .onClick(() => {
        console.info("按钮被点击了")
    })

这里我用了 ButtonType.Capsule，就是那种圆角胶囊形状。我个人比较喜欢这种风格，看起来更现代。

注意： 我曾经踩过一个坑——按钮的点击区域太小。用户怎么点都没反应。后来我养成了习惯，所有按钮至少给 44px 的高度，这是手指触摸的最小舒适区。

2.3 Image 组件：图片加载有讲究

Image 组件用来显示图片。但图片加载这件事，坑特别多。你想想看，网络图片加载慢怎么办？图片尺寸不对怎么办？

先看基础用法：

Image($r("app.media.icon"))
    .width(100)
    .height(100)
    .borderRadius(10)

这是加载本地资源。如果是网络图片，需要加 .src()：

Image()
    .src("https://example.com/logo.png")
    .width(200)
    .height(100)
    .objectFit(ImageFit.Contain)

这里 .objectFit() 很关键。它决定了图片怎么适应容器：

Cover：裁剪填充，会损失边缘内容
Contain：完整显示，可能会有留白
Fill：拉伸填充，会变形

我建议大部分场景用 Contain。除非你确定图片比例和容器完全一致，否则别用 Fill，变形了很难看。

小技巧： 网络图片加载时，最好加一个占位图。我习惯用 .alt() 属性设置加载失败时的替代图片，这样用户体验不会断档。

2.4 TextInput 组件：用户输入的入口

TextInput 是用户输入文本的组件。说白了就是输入框。但输入框的细节特别多，比如键盘类型、输入限制、占位提示等等。

基础用法：

TextInput({ placeholder: "请输入用户名" })
    .width(300)
    .height(40)
    .type(InputType.Normal)
    .onChange((value: string) => {
        console.info("输入内容：" + value)
    })

这里 .type() 控制键盘类型。我遇到过不少新手，做密码输入框时忘了设置 InputType.Password，结果输入的内容明文显示，这肯定不行。

常用的输入类型：

Normal：普通文本
Password：密码，显示为圆点
Email：邮箱，键盘带 @ 符号
Number：数字键盘

避坑指南： 我曾经做过一个登录页面，用户输入密码时，键盘把输入框挡住了。后来我加了 .keyboardAvoid(true) 属性，才解决了这个问题。嗯，这个属性默认是关闭的，记得手动打开。

2.5 组件的通用属性

上面讲的四个组件，虽然功能不同，但有很多共同的属性。我把它们统称为「通用属性」。掌握了这些，你写任何组件都会顺手很多。

我整理了一张表，方便你对照：

属性	作用	示例
width / height	设置宽高	.width(100).height(50)
padding / margin	内边距 / 外边距	.padding(10).margin({ top: 5 })
backgroundColor	背景颜色	.backgroundColor(Color.Red)
borderRadius	圆角	.borderRadius(8)
opacity	透明度	.opacity(0.8)
visibility	可见性	.visibility(Visibility.Hidden)
align	对齐方式	.align(Alignment.Center)

举个例子，给一个按钮加上圆角和阴影：

Button("点击我")
    .width(150)
    .height(45)
    .backgroundColor("#007AFF")
    .borderRadius(22)
    .shadow({ radius: 4, color: Color.Gray, offsetX: 2, offsetY: 2 })

你看，这些属性都是通用的。你可以在 Text、Image、TextInput 上同样使用。说白了，掌握了这些，你就能控制任何组件的外观和布局。

我的建议： 刚开始学的时候，别急着背所有属性。先记住最常用的那几个——宽高、边距、背景色、圆角。其他的用到再查，慢慢就熟了。

知识体系总览

下面这张图，是我为你梳理的本章知识结构。你可以把它当作一个「地图」，随时回来对照：

好了，这一节的内容就到这里。Text、Button、Image、TextInput 这四个组件，加上通用属性，足够你搭建出大部分常见界面了。记住，多动手写代码，比光看文档强十倍。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

2、基础组件入门：Text、Button、Image、TextInput 与通用属性

2.1 Text 组件：不只是显示文字

2.2 Button 组件：交互的起点

2.3 Image 组件：图片加载有讲究

2.4 TextInput 组件：用户输入的入口

2.5 组件的通用属性

知识体系总览