鸿蒙单标签常用的属性

原创于 2026-07-06 10:34:32 发布 · 119 阅读

本内容遵循CC 4.0 BY-SA版权协议

一、Text 文本组件（完整版精简）

1. 基础内容属性

属性名	作用说明
content	设置文本显示内容，支持换行符换行
maxLines	限制文本最大展示行数，超出部分按溢出规则处理
minLines	设置文本最小占用行数，内容不足也会撑开对应高度
textOverflow	文本溢出处理规则：Clip 截断、Ellipsis 省略号、None 不处理

2. 字体样式属性（高频）

属性名	作用说明
fontSize	设置字体大小，推荐使用 fp 自适应单位
fontColor	设置文字颜色，支持十六进制、RGB、系统默认色、资源色值
fontWeight	设置字体粗细，支持枚举（正常/加粗）和 100-900 数值字重
fontStyle	字体样式，支持正常、斜体两种样式
fontFamily	自定义字体，填写对应字体名称即可
letterSpacing	字间距，正数加宽文字间距，负数紧缩间距
lineHeight	文本行高，统一控制多行文字排版间距

3. 文本排版对齐属性

属性名	作用说明
textAlign	文本水平对齐：左对齐、居中、右对齐、两端对齐
textIndent	文本首行缩进，常用于段落正文排版
baselineOffset	文字基线偏移，可实现文字上标、下标效果

4. 文字装饰效果属性

属性名	作用说明
decoration	文字装饰线：无装饰、下划线、删除线、上划线
decorationColor	单独设置装饰线的颜色
decorationThickness	设置装饰线的粗细尺寸

5. 视觉特效属性

属性名	作用说明
textShadow	文字阴影效果，可配置阴影半径、颜色、偏移距离，支持多层阴影
opacity	组件整体透明度，取值范围 0-1

6. 复制能力属性

属性名	作用说明
copyOption	文本复制权限：禁止复制、本地复制、跨设备复制

7. 状态控制属性

属性名	作用说明
enabled	控制组件是否可交互，禁用时文本置灰、无法触发点击
visibility	组件显示隐藏：正常显示、隐藏但占位、隐藏且不占位

8. 通用布局属性（高频）

宽高：width 宽度、height 高度、layoutWeight 弹性布局权重
边距：padding 内边距、margin 外边距
外观：backgroundColor 背景色、border 边框、borderRadius 圆角
层级：zIndex 组件堆叠层级

9. 常用交互事件

onClick：文本点击触发事件
onLongPress：文本长按触发事件
onTouch：文本触摸按压、移动、抬起全过程事件

10. Span富文本子组件说明

Span 仅可作为 Text 内部子组件使用，无法单独渲染，用于实现同一段文字多种样式差异化效果。继承 Text 大部分样式属性，可单独配置文字内容、字号、颜色、字重、装饰线等个性化样式。

11. 核心开发注意事项

字体尺寸优先使用 fp 单位，自动适配各类设备屏幕
文本省略效果需要 maxLines 搭配 textOverflow 同时生效
行高数值需大于字体大小，避免文字重叠挤压
文本省略隐藏的内容，无法触发复制功能
颜色支持十六进制、RGB、系统色、资源引用多种格式

二、TextInput 输入框组件

TextInput 为单行文本输入组件，适用于账号、密码、搜索、备注等单行录入场景，支持样式定制、输入规则、焦点控制、内容监听。

1. 基础内容属性

属性名	作用说明
text	绑定输入框默认显示文本，支持双向绑定
placeholder	输入框占位提示文字，无内容时展示
placeholderColor	设置占位文字颜色
maxLength	限制最大输入字符数，超出无法输入
defaultFocus	页面加载默认自动获取焦点
caretColor	设置输入光标颜色

2. 输入类型与规则属性

属性名	作用说明
type	输入类型：普通文本、数字、密码、手机号、邮箱等，自动适配键盘
password	开启密码密文输入，隐藏输入内容
enterKeyType	回车键样式：完成、搜索、下一步、发送等
inputFilter	输入过滤器，正则限制仅可输入指定字符（数字、字母等）

3. 字体与样式属性

属性名	作用说明
fontSize	输入文字大小，支持fp自适应单位
fontColor	输入文字颜色
fontWeight/fontStyle	文字粗细、斜体样式设置
textAlign	输入文字对齐方式：左对齐、居中、右对齐

4. 状态控制属性

属性名	作用说明
enabled	是否可编辑，false为只读禁止输入
readOnly	只读模式，可选中不可修改
showCursor	是否显示输入光标

5. 常用事件

onChange：输入内容发生改变时触发，实时监听输入值
onFocus：输入框获取焦点触发
onBlur：输入框失去焦点触发
onSubmit：点击回车键提交触发
onClear：点击清空按钮触发

6. 开发注意事项

TextInput 仅支持单行输入，多行输入需使用 TextArea 组件
密码模式下可搭配显示/隐藏密码按钮实现切换功能
inputFilter 可精准拦截非法字符输入，提升表单校验效率
双向绑定可实时获取输入内容，无需手动取值

三、Image 图片组件

Image 为鸿蒙核心图片渲染组件，支持加载本地资源、网络图片、像素图等，适配裁剪、缩放、圆角、透明度等样式。

1. 基础资源属性

属性名	作用说明
src	图片资源地址，支持本地资源、网络URL、资源引用
alt	图片加载失败时显示的兜底文本

2. 缩放适配属性（高频）

属性名	作用说明
objectFit	图片缩放模式：自适应、铺满、裁剪、完整显示、居中显示
objectRepeat	小图片是否重复平铺展示
resizeMode	图片缩放渲染模式，适配模糊、清晰展示需求

3. 样式特效属性

属性名	作用说明
borderRadius	图片圆角，支持全局圆角、单独四角圆角，可实现圆形图片
opacity	图片透明度，取值0-1
blur	图片高斯模糊效果，设置模糊度数
backgroundColor	图片空白区域背景色

4. 渲染与状态属性

属性名	作用说明
renderMode	渲染模式：原图、仅灰度、透明区域优化
visibility	组件显示隐藏，支持占位/不占位隐藏

5. 常用事件

onClick：图片点击事件
onLoad：图片加载成功触发
onError：图片加载失败触发，可做兜底处理
onComplete：图片加载完成触发（无论成功失败）

6. 开发注意事项

网络图片需配置网络权限，否则无法加载
实现圆形图片需保证宽高一致 + 圆角为宽高一半
objectFit 是解决图片拉伸、留白、裁剪的核心属性
大尺寸图片建议做压缩处理，避免内存占用过高

四、Button 按钮组件

Button 为核心交互按钮组件，用于点击操作、提交、跳转等场景，支持多种按钮类型、样式、状态定制。

1. 基础内容属性

属性名	作用说明
text	按钮内部显示文字内容
type	按钮类型：普通按钮、胶囊按钮、圆形按钮、文本按钮

2. 样式定制属性

属性名	作用说明
fontSize	按钮文字大小
fontColor	按钮文字颜色
fontWeight	按钮文字粗细
backgroundColor	按钮背景颜色
borderRadius	按钮圆角尺寸，自定义圆角样式
border	自定义按钮边框粗细、颜色

3. 状态控制属性

属性名	作用说明
enabled	按钮是否可点击，禁用时置灰、不可触发事件
loading	开启加载状态，按钮显示loading动画，禁止重复点击
opacity	按钮整体透明度

4. 布局与适配属性

属性名	作用说明
width/height	自定义按钮宽高，支持固定尺寸、百分比
padding/margin	按钮内边距、外边距，控制间距排版