一、前言

在鸿蒙 ArkUI 声明式开发中，所有文字相关组件分为两大体系：只读文本展示组件（Text/Span）、可交互文本输入组件（TextInput/TextArea/Search）。二者定位完全隔离，本篇一次性梳理清楚区别、特性与适用场景，方便开发选型。

二、第一类：文本显示组件（Text / Span）—— 仅展示，不可编辑

1. Text 基础文本容器

• 是独立的文字容器，可以直接放在 Row、Column 这些布局里，用来承载一整段文字。能设置字体大小、颜色、行高，文字太长还能设置省略、滚动。内部可以嵌套 Span，实现同一段文字多种样式。适用场景：页面标题、提示文字、按钮上的文字、静态说明文案。

2. Span 行内富文本子组件

• 不能单独拿出来用，只能写在 Text 里面，属于行内子组件。作用是给一段文字里的一小部分单独改样式，比如关键字标红、添加下划线，还能单独加点击事件，做页面里的协议链接、跳转文字。

示例代码

Text('欢迎使用') {
  Span('鸿蒙应用')
    .fontColor(Color.Blue)
    .fontSize(22)
    .onClick(() => console.log('点击跳转'))
  Span('开发平台').fontColor(Color.Grey)
}

三、第二类：文本输入组件（TextInput / TextArea / Search）—— 用户可输入编辑

三者均为可交互输入框，接收用户键盘输入，仅区分单行 / 多行 / 搜索专用场景。

1. TextInput 单行输入框

• 核心特性：单行输入，超出宽度不自动换行，回车可绑定提交逻辑；支持密码、数字、手机号等多种输入类型。
• 适用场景：登录账号、密码、手机号、验证码、短表单单行填写。

2. TextArea 多行文本框

• 核心特性：支持自动换行、多行滚动，高度可自适应，回车换行输入长内容。
• 适用场景：评论区、留言、个人简介、长文本备注、意见反馈。

3. Search 搜索专用输入框

• 核心特性：基于 TextInput 封装，自带内置搜索图标、一键清除按钮，内置搜索回车回调，UI 符合系统搜索规范。
• 适用场景：页面顶部搜索栏、商品 / 文章检索、关键词筛选。

示例代码

typescript

// 单行账号输入
TextInput({ text: $$this.account, placeholder: "请输入账号" })
// 多行评论
TextArea({ text: $$this.comment, placeholder: "写下你的评论..." })
// 搜索框
Search({ value: $$this.keyword, placeholder: "搜索内容" })
  .onSubmit((val) => this.searchData(val))

四、两大组件体系核心对比（快速选型）

五、开发避坑总结

1. 不要混用：Text/Span 无法接收用户输入；输入框组件不能用来展示静态文字，会增加性能开销。
2. Span 限制：不能脱离 Text 单独写在 Row/Column 中，编译报错。
3. 富文本区分：简单多色文字用 Span；复杂图文混排使用 RichEditor，不要强行嵌套多层 Span。
4. 输入框选型：短内容选 TextInput，长内容选 TextArea，搜索功能优先使用 Search（统一交互规范）。

六、结尾

ArkUI 把文字展示和文字输入分开设计，逻辑很清晰。做开发先分清需求是 “只看文字” 还是 “用户要填写”，再对应选组件，能少出很多样式、交互 bug。后续再慢慢整理各个组件常用 API 和表单校验的写法。