鸿蒙OS JS API参考 组件text
文本，用于呈现一段信息。
说明
文本的展示内容需要写在元素标签内。
支持设备
| 智慧屏 | 智能穿戴 |
|---|---|
| 支持 | 支持 |
权限列表
无
子组件
支持<span>。
属性
| 名称 | 类型 | 默认值 | 必填 | 描述 |
|---|---|---|---|---|
| id | string | - | 否 | 组件的唯一标识。 |
| style | string | - | 否 | 组件的样式声明。 |
| class | string | - | 否 | 组件的样式类，用于引用样式表。 |
| ref | string | - | 否 | 用来指定指向子元素或子组件的引用信息，该引用将注册到父组件的$refs 属性对象上。 |
| disabled | boolean | false | 否 | 当前组件是否被禁用，在禁用场景下，组件将无法响应用户交互。 |
| focusable | boolean | false | 否 | 当前组件是否可以获取焦点。 当focusable设置为true时，组件可以响应焦点事件和按键事件。 |
| data | string | - | 否 | 给当前组件设置data属性，进行相应的数据存储和读取。 |
事件
| 名称 | 参数 | 描述 |
|---|---|---|
| touchstart | TouchEvent | 手指刚触摸屏幕时触发该事件。 |
| touchmove | TouchEvent | 手指触摸屏幕后移动时触发该事件。 |
| touchcancel | TouchEvent | 手指触摸屏幕中动作被打断时触发该事件。 |
| touchend | TouchEvent | 手指触摸结束离开屏幕时触发该事件。 |
| click | - | 点击动作触发该事件。 |
| longpress | - | 长按动作触发该事件。 |
| focus | - | 获得焦点时触发该事件，span组件无法获取焦点。 |
| blur | - | 失去焦点时触发该事件，span组件无法失去焦点。 |
| key | KeyEvent | 智慧屏特有的按键事件，当用户操作遥控器按键时触发。返回true表示页面自己处理按键事件。返回false表示使用默认的按键事件逻辑。不返回值作为false处理。 |
样式
| 名称 | 类型 | 默认值 | 必填 | 描述 |
|---|---|---|---|---|
| color | <color> | 智慧屏：#e5ffffff智能穿戴：#ffffffff | 否 | 设置文本的颜色。 |
| font-size | <length> | 30px | 否 | 设置文本的尺寸。 |
| allow-scale | boolean | true | 否 | 文本尺寸是否跟随系统设置字体缩放尺寸进行放大缩小。说明如果需要支持动态生效，请参看config描述文件中config-changes标签。 |
| letter-spacing | <length> | 0px | 否 | 设置文本的字符间距。 |
| font-style | string | normal | 否 | 设置文本的字体样式，可选值为：normal：标准的字体样式；italic：斜体的字体样式。 |
| font-weight | number | string | normal | 否 | 设置文本的字体粗细，number类型取值[100, 900]，默认为400，取值越大，字体越粗。说明number取值必须为100的整数倍。string类型取值支持如下四个值：lighter、normal、bold、bolder。 |
| text-decoration | string | none | 否 | 设置文本的文本修饰，可选值为：underline：文字下划线修饰；line-through：穿过文本的修饰线；none：标准文本。 |
| text-align | string | start | 否 | 设置文本的文本对齐方式，可选值为：left：文本左对齐；center：文本居中对齐；right：文本右对齐；start：根据文字书写相同的方向对齐；end：根据文字书写相反的方向对齐。说明如文本宽度未指定大小，文本的宽度和父容器的宽度大小相等的情况下，对齐效果可能会不明显。 |
| line-height | <length> | 0px | 否 | 设置文本的文本行高，设置为0px时，不限制文本行高，自适应字体大小。 |
| text-overflow | string | clip | 否 | 在设置了最大行数的情况下生效，可选值为：clip：将文本根据父容器大小进行裁剪显示；ellipsis：根据父容器大小显示，显示不下的文本用省略号代替。需配合max-lines使用。 |
| font-family | string | sans-serif | 否 | 设置文本的字体列表，用逗号分隔，每个字体用字体名或者字体族名设置。列表中第一个系统中存在的或者通过自定义字体指定的字体，会被选中作为文本的字体。 |
| max-lines | number | - | 否 | 设置文本的最大行数。 |
| min-font-size | <length> | - | 否 | 文本最小字号，需要和文本最大字号同时设置，支持文本字号动态变化。设置最大最小字体样式后，font-size不生效。 |
| max-font-size | <length> | - | 否 | 文本最大字号，需要和文本最小字号同时设置，支持文本字号动态变化。设置最大最小字体样式后，font-size不生效。 |
| font-size-step | <length> | 1px | 否 | 文本动态调整字号时的步长，需要设置最小，最大字号样式生效。 |
| prefer-font-sizes | <array> | - | 否 | 预设的字号集合，在动态尺寸调整时，优先使用预设字号集合中的字号匹配设置的最大行数，如果预设字号集合未设置，则使用最大最小和步长调整字号。针对仍然无法满足最大行数要求的情况，使用text-overflow设置项进行截断，设置预设尺寸集后，font-size、max-font-size、min-font-size和font-size-step不生效。如：prefer-font-sizes: 12px,14px,16px |
| width | <length> | <percentage> | - | 否 | 设置组件自身的宽度。缺省时使用元素自身内容需要的宽度。 |
| height | <length> | <percentage> | - | 否 | 设置组件自身的高度。缺省时使用元素自身内容需要的高度。 |
| padding | <length> | 0 | 否 | 该属性可以有1到4个值：指定一个值时，该值指定四个边的内边距。指定两个值时，第一个值指定上下两边的内边距，第二个指定左右两边的内边距。指定三个值时，第一个指定上边的内边距，第二个指定左右两边的内边距，第三个指定下边的内边距。指定四个值时分别为上、右、下、左边的内边距（顺时针顺序）。 |
| padding-[left|top|right|bottom] | <length> | 0 | 否 | 设置左、上、右、下内边距属性。 |
| padding-[start|end] | <length> | 0 | 否 | 设置起始和末端内边距属性。 |
| margin | <length> | 0 | 否 | 使用简写属性设置所有的外边距属性，该属性可以有1到4个值。只有一个值时，这个值会被指定给全部的四个边。两个值时，第一个值被匹配给上和下，第二个值被匹配给左和右。三个值时，第一个值被匹配给上, 第二个值被匹配给左和右，第三个值被匹配给下。四个值时，会依次按上、右、下、左的顺序匹配 (即顺时针顺序)。 |
| margin-[left|top|right|bottom] | <length> | 0 | 否 | 设置左、上、右、下外边距属性。 |
| margin-[start|end] | <length> | 0 | 否 | 设置起始和末端外边距属性。 |
| border | - | 0 | 否 | 使用简写属性设置所有的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置时，各属性值为默认值。 |
| border-style | string | solid | 否 | 使用简写属性设置所有边框的样式，可选值为：dotted：显示为一系列圆点，圆点半径为border-width的一半。dashed：显示为一系列短的方形虚线。solid：显示为一条实线。 |
| border-[left|top|right|bottom]-style | string | solid | 否 | 分别设置左、上、右、下四个边框的样式，可选值为dotted、dashed、solid。 |
| border-[left|top|right|bottom] | - | - | 否 | 使用简写属性设置对应位置的边框属性，包含边框的宽度，样式，颜色属性，顺序设置为border-width、border-style、border-color，不设置的值为默认值。 |
| border-width | <length> | 0 | 否 | 使用简写属性设置元素的所有边框宽度，或者单独为各边边框设置宽度。 |
| border-[left|top|right|bottom]-width | <length> | 0 | 否 | 分别设置左、上、右、下四个边框的宽度。 |
| border-color | <color> | black | 否 | 使用简写属性设置元素的所有边框颜色，或者单独为各边边框设置颜色。 |
| border-[left|top|right|bottom]-color | <color> | black | 否 | 分别设置左、上、右、下四个边框的颜色。 |
| border-radius | <length> | - | 否 | border-radius属性是设置元素的外边框圆角半径。设置border-radius时不能单独设置某一个方向的border-[left|top|right|bottom]-width，border-[left|top|right|bottom]-color ，如果要设置color和width，需要将四个方向一起设置（border-width、border-color）。 |
| border-[top|bottom]-[left|right]-radius | <length> | - | 否 | 分别设置左上，右上，右下和左下四个角的圆角半径。 |
| background | <linear-gradient> | - | 否 | 仅支持设置渐变样式，与background-color、background-image不兼容。 |
| background-color | <color> | - | 否 | 设置背景颜色。 |
| background-image | string | - | 否 | 设置背景图片。与background-color、background不兼容；支持网络图片资源和本地图片资源地址。 |
| background-size | string<length> <length><percentage> <percentage> | auto | 否 | 设置背景图片的大小。string可选值：contain：把图像扩展至最大尺寸，以使其高度和宽度完全适用内容区域。cover：把背景图像扩展至足够大，以使背景图像完全覆盖背景区域；背景图像的某些部分也许无法显示在背景定位区域中。auto：保持原图的比例不变。length值参数方式：设置背景图像的高度和宽度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为 "auto"。百分比参数方式：以父元素的百分比来设置背景图像的宽度和高度。第一个值设置宽度，第二个值设置高度。如果只设置一个值，则第二个值会被设置为 "auto"。 |
| background-repeat | string | repeat | 否 | 针对重复背景图像样式进行设置，背景图像默认在水平和垂直方向上重复。repeat：在水平轴和竖直轴上同时重复绘制图片。repeat-x：只在水平轴上重复绘制图片。repeat-y：只在竖直轴上重复绘制图片。no-repeat：不会重复绘制图片。 |
| background-position | string string<length> <length><percentage> <percentage> | 0px 0px | 否 | 关键词方式：如果仅规定了一个关键词，那么第二个值为"center"。两个值分别定义水平方向位置和竖直方向位置。left：水平方向上最左侧。right：水平方向上最右侧。top：竖直方向上最顶部。bottom：竖直方向上最底部。center：水平方向或竖直方向上中间位置。length值参数方式：第一个值是水平位置，第二个值是垂直位置。 左上角是 0 0。单位是像素 (0px 0px) 。如果仅规定了一个值，另外一个值将是50%。百分比参数方式：第一个值是水平位置，第二个值是垂直位置。左上角是 0% 0%。右下角是 100% 100%。如果仅规定了一个值，另外一个值为50%。可以混合使用<percentage>和<length> |
| opacity | number | 1 | 否 | 元素的透明度，取值范围为0到1，1表示为不透明，0表示为完全透明。 |
| display | string | flex | 否 | 确定一个元素所产生的框的类型，可选值为：flex：弹性布局。none：不渲染此元素。 |
| visibility | string | visible | 否 | 是否显示元素所产生的框。不可见的框会占用布局（将'display'属性设置为'none'来完全去除框），可选值为：visible：元素正常显示。hidden：隐藏元素，但是其他元素的布局不改变，相当于此元素变成透明。说明visibility和display样式都设置时，仅display生效 |
| flex | number | - | 否 | 规定当前组件如何适应父组件中的可用空间。它作为一个简写属性，用来设置组件的flex-grow。说明仅父容器为<div>、<list-item>、<tabs>时生效。 |
| flex-grow | number | 0 | 否 | 设置组件的拉伸样式，指定父组件容器主轴方向上剩余空间（容器本身大小减去所有flex子元素占用的大小）的分配权重。0为不伸展。说明仅父容器为<div>、<list-item>、<tabs>时生效。 |
| flex-shrink | number | 1 | 否 | 设置组件的收缩样式，元素仅在默认宽度之和大于容器的时候才会发生收缩，0为不收缩。说明仅父容器为<div>、<list-item>、<tabs>时生效。 |
| flex-basis | <length> | - | 否 | 设置组件在主轴方向上的初始大小。说明仅父容器为<div>、<list-item>、<tabs>时生效。 |
| position | string | relative | 否 | 设置元素的定位类型，不支持动态变更。fixed：相对与整个界面进行定位。absolute：相对于父元素进行定位。relative：相对于其正常位置进行定位。说明absolute属性仅在父容器为<div>、<stack>时生效。 |
| [left|top|right|bottom] | <length> | - | 否 | left|top|right|bottom需要配合position样式使用，来确定元素的偏移位置。left属性规定元素的左边缘。该属性定义了定位元素左外边距边界与其包含块左边界之间的偏移。top属性规定元素的顶部边缘。该属性定义了一个定位元素的上外边距边界与其包含块上边界之间的偏移。right属性规定元素的右边缘。该属性定义了定位元素右外边距边界与其包含块右边界之间的偏移。bottom属性规定元素的底部边缘。该属性定义了一个定位元素的下外边距边界与其包含块下边界之间的偏移。 |
说明
- 字体动态缩放：预设尺寸集合和最小最大字号调节基于是否满足最大行数要求，预设尺寸集合会按照从左到右顺序查看是否满足最大行数要求，最小最大字号调节则基于从大到小顺序查看是否满足最大行数要求。
- 文本换行：文本可以通过转义字符\r\n进行换行。
- 文本标签内支持转义字符'\'。