HarmonyOS应用开发实战：小事记 – 文本显示与排版：Text/TextInput/TextArea 的富文本与溢出处理-171主机测评

页面预览

前言

文本组件是应用中最基础也最常用的 UI 元素。HarmonyOS 提供了 Text（显示文本）、TextInput（单行输入）和 TextArea（多行输入）三种文本组件，分别满足不同的文本展示和输入需求。本文以小事记（xiaoshiji_ohos_app）的 HomePage.ets 和 RecordPage.ets 为分析对象，深入解析文本组件的使用和排版技巧。

主要实现步骤：

初始化相关参数和配置

调用核心 API 执行主要操作

处理返回结果和异常情况

验证实现效果是否符合预期

本文参考 HarmonyOS 官方文档：Text 组件和 TextInput 组件。

一、Text 组件

1.1 基本用法

// Text 组件的基本用法
Text('小事记')
.fontSize(20)
.fontWeight(FontWeight.Bold)
.fontColor('#1A1A2E')
.textAlign(TextAlign.Start)
.lineHeight(28)

1.2 文本溢出处理

// 文本溢出处理
Text(event.content)
.fontSize(13)
.fontColor('#6B7280')
.maxLines(2) // 最多显示 2 行
.textOverflow({ overflow: TextOverflow.Ellipsis }) // 溢出显示省略号

溢出模式说明效果

Ellipsis	省略号	显示 …
Clip	裁剪	直接裁剪
None	无	默认，不处理

二、TextInput 单行输入

2.1 基本用法

// TextInput 的基本用法
TextInput({ placeholder: '搜索记录…', text: this.searchText })
.width('100%')
.height(36)
.fontSize(14)
.placeholderColor('#9CA3AF')
.onChange((value: string) => {
this.searchText = value;
})

2.2 输入类型

类型说明适用场景

Normal	普通文本	搜索框、名称
Email	邮箱地址	登录输入
Number	数字	验证码、数量
PhoneNumber	电话号码	手机号输入
Password	密码	密码输入

三、TextArea 多行输入

3.1 基本用法

// TextArea 的基本用法
TextArea({ text: this.recordText, placeholder: '记录此刻的想法…' })
.width('100%')
.height(200)
.fontSize(16)
.fontColor('#1A1A2E')
.placeholderColor('#9CA3AF')
.onChange((value: string) => {
this.recordText = value;
})

四、文本样式

4.1 样式属性

属性说明示例

fontSize	字体大小	16
fontWeight	字体粗细	FontWeight.Bold
fontColor	字体颜色	#1A1A2E
lineHeight	行高	24
textAlign	对齐方式	TextAlign.Start
letterSpacing	字间距	1
decoration	装饰线	TextDecorationType.Underline

五、富文本

5.1 使用 Span 实现富文本

// 富文本实现
Text() {
Span('标题：')
.fontSize(16)
.fontWeight(FontWeight.Bold)
Span('这是内容')
.fontSize(14)
.fontColor('#6B7280')
Span(' [链接]')
.fontSize(14)
.fontColor('#7B68EE')
.decoration({ type: TextDecorationType.Underline })
}

六、常见问题

6.1 文本不换行

问题：Text 组件中的长文本不换行。

解决方案：设置 width 和 maxLines。

Text('长文本内容…')
.width('100%')
.maxLines(5)

6.2 输入框样式不一致

问题：TextInput 在不同设备上的样式不一致。

解决方案：统一设置字体大小和颜色。

七、最佳实践

策略说明效果

统一字体大小	定义字号 Token	一致性
文本溢出处理	使用 maxLines + textOverflow	防止布局错乱
输入框校验	在 onChange 中校验	数据有效性
占位符颜色	使用浅色提示	引导用户

十、进一步学习与拓展

掌握以上内容后，可以进一步探索以下相关主题，深化对 HarmonyOS 开发的理解：

10.1 推荐学习路径

学习阶段主题预期目标

基础阶段	掌握核心概念和 API 用法	能够独立完成基本功能开发
进阶阶段	理解底层原理和最佳实践	能够优化应用性能和用户体验
高级阶段	掌握架构设计和性能调优	能够主导复杂项目的技术方案

10.2 实践项目建议

建议通过以下实践项目巩固所学知识：

基于小事记项目，尝试独立实现一个类似的功能模块

阅读 HarmonyOS 官方 Sample 代码，学习最佳实践

参与开源社区，贡献代码或文档

10.3 相关资源

HarmonyOS 官方文档：提供完整的 API 参考和开发指南
DevEco Studio 文档：包含 IDE 使用技巧和调试方法
开源社区：获取项目源码和开发经验

学习建议：理论与实践相结合，在阅读文档的同时动手编写代码，才能更好地掌握 HarmonyOS 应用开发技能。

10.4 拓展阅读

以下资源可以加深对本文内容的理解：

HarmonyOS 官方开发者文档提供了最权威的 API 参考和最佳实践指南

开源社区的项目源码是学习实际应用开发的宝贵资源

DevEco Studio 的代码示例模板可以帮助快速上手

资源类型推荐指数适用人群

官方文档	⭐⭐⭐⭐⭐	所有开发者
开源项目	⭐⭐⭐⭐	中级开发者
技术博客	⭐⭐⭐	入门开发者

学习路径：建议按照“官方文档 → 开源项目 → 实践项目“的路径循序渐进地学习。

十、完整示例：自定义组件封装

将常用的 UI 模式封装为可复用的自定义组件，是提升开发效率的关键。

10.1 组件封装

// CustomCard.ets — 自定义卡片组件
@Component
export struct CustomCard {
@Prop title: string = '';
@Prop description: string = '';
@State isExpanded: boolean = false;

build() {
Column() {
Row() {
Text(this.title)
.fontSize(16)
.fontWeight(FontWeight.Bold)
Blank()
Text(this.isExpanded ? '收起' : '展开')
.fontSize(12)
.fontColor('#7B68EE')
}
.width('100%')
.onClick(() => { this.isExpanded = !this.isExpanded; })

if (this.isExpanded) {
Text(this.description)
.fontSize(14)
.fontColor('#6B7280')
.margin({ top: 8 })
.lineHeight(22)
}
}
.padding(16)
.backgroundColor(Color.White)
.borderRadius(12)
.shadow({ radius: 4, color: '#00000010', offsetX: 0, offsetY: 2 })
}
}

10.2 调用方式

// 使用自定义卡片组件
CustomCard({
title: '重要事件',
description: '这是对事件的详细描述内容，可以包含多行文本信息'
})

10.3 组件属性说明

属性名类型默认值说明

title	string	‘’	卡片标题
description	string	‘’	详情描述文本
isExpanded	boolean	false	展开状态

设计原则：自定义组件应保持单一的职责，通过 @Prop 和 @Link 实现与父组件的状态同步。

十一、常见错误排查

在实际开发过程中，开发者经常会遇到一些典型的错误和问题。以下汇总了常见错误及其解决方案：

11.1 典型错误一览

错误类型错误现象可能原因解决方案

编译错误	编译失败	语法错误或类型不匹配	检查代码语法和类型定义
运行时错误	应用闪退	空指针或资源未加载	添加空值检查和资源预加载
性能问题	页面卡顿	过度渲染或内存泄漏	优化渲染逻辑，及时释放资源
布局异常	显示错乱	约束条件不足	检查布局约束和宽高设置

11.2 调试步骤

遇到问题时，按以下步骤进行排查：

查看 hilog 日志，定位错误发生的位置和堆栈信息

使用 DevEco Studio 的断点调试功能，逐步跟踪代码执行路径

检查 module.json5 和资源配置文件，确认配置项是否正确

在真机环境下复现问题，验证是否与模拟器环境差异有关

11.3 调试代码示例

// 调试工具函数
export class DebugUtil {
static logError(tag: string, message: string, error?: Error): void {
console.error(`[${tag}] ${message}`);
if (error) {
console.error(`[${tag}] Stack: ${error.stack}`);
}
}

static logState(tag: string, state: Record<string, Object>): void {
console.info(`[${tag}] State: ${JSON.stringify(state)}`);
}
}

调试建议：在开发阶段保持 hilog 的详细日志输出，发布前关闭调试日志以提升性能。

总结

本文深入解析了 Text/TextInput/TextArea 三种文本组件的使用。核心要点如下：

Text：使用 maxLines 和 textOverflow 控制文本溢出

TextInput：单行输入，支持多种输入类型

TextArea：多行输入，适合记录编辑

富文本：使用 Span 实现富文本效果

样式统一：定义字号 Token，保持一致性

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

九、完整示例代码

9.1 完整组件实现

以下是一个完整的组件实现示例，展示了本文介绍的各个技术点的综合运用：

import { Component, State, Prop } from '@kit.ArkUI';

@Component
export struct DemoComponent {
@Prop title: string = '';
@State count: number = 0;

build() {
Column({ space: 12 }) {
// 标题区域
Text(this.title)
.fontSize(18)
.fontWeight(FontWeight.Bold)
.fontColor('#1A1A2E')
.width('100%')

// 内容区域
Text(`当前计数: ${this.count}`)
.fontSize(14)
.fontColor('#6B7280')

// 交互按钮
Button('点击增加')
.width(120)
.height(40)
.backgroundColor('#7B68EE')
.borderRadius(20)
.fontColor(Color.White)
.onClick(() => {
this.count++;
})
}
.width('100%')
.padding(16)
.backgroundColor(Color.White)
.borderRadius(12)
.shadow({ radius: 4, color: '#00000008', offsetX: 0, offsetY: 2 })
}
}

9.2 使用方式

在页面中引入并使用该组件：

@Entry
@Component
struct Index {
build() {
Column() {
DemoComponent({ title: '示例组件' })
}
.width('100%')
.height('100%')
.backgroundColor('#F8F9FA')
}
}

9.3 代码说明

组件封装：使用 @Component 装饰器定义可复用的组件
状态管理：使用 @State 管理组件内部状态
参数传递：使用 @Prop 接收外部传入的参数
事件处理：使用 onClick 处理用户交互
样式优化：使用 borderRadius、shadow 等属性美化 UI

前言