1# Span 2 3作为[Text](ts-basic-components-text.md)、[ContainerSpan](ts-basic-components-containerspan.md)组件的子组件，用于显示行内文本的组件。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 该组件从API Version 10开始支持继承父组件Text的属性，即如果子组件未设置属性且父组件设置属性，则继承父组件设置的属性。支持继承的属性仅包括：fontColor、fontSize、fontStyle、fontWeight、decoration、letterSpacing、textCase、fontfamily、textShadow。 10 11 12## 子组件 13 14无 15 16 17## 接口 18 19Span(value: string | Resource) 20 21**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 22 23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| -------- | -------- | -------- | -------- | 31| value | string \| [Resource](ts-types.md#resource) | 是 | 文本内容。 | 32 33 34## 属性 35 36属性继承自[BaseSpan](#basespan)。 37 38### decoration 39 40decoration(value: DecorationStyleInterface) 41 42设置文本装饰线样式及其颜色。 43 44**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 45 46**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 47 48**系统能力：** SystemCapability.ArkUI.ArkUI.Full 49 50**参数：** 51 52| 参数名 | 类型 | 必填 | 说明 | 53| ------ | -------- | ---- | -------------- | 54| value | [DecorationStyleInterface<sup>12+</sup>](ts-universal-styled-string.md#decorationstyleinterface) | 是 | 文本装饰线样式对象。<br/>默认值：<br/>{<br/> type: TextDecorationType.None,<br/> color: Color.Black,<br/> style: TextDecorationStyle.SOLID <br/>}<br/>**说明：** <br/>style参数不支持卡片能力。 | 55 56### letterSpacing 57 58letterSpacing(value: number | string) 59 60设置文本字符间距。取值小于0，字符聚集重叠，取值大于0且随着数值变大，字符间距越来越大，稀疏分布。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 61 62**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 63 64**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 65 66**系统能力：** SystemCapability.ArkUI.ArkUI.Full 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| ------ | ------- | ---- | -------------- | 72| value | number \| string | 是 | 文本字符间距。<br/>单位：fp | 73 74### textCase 75 76textCase(value: TextCase) 77 78设置文本大小写。 79 80**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 81 82**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.ArkUI.ArkUI.Full 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| ------ | ------- | ---- | ------- | 90| value | [TextCase](ts-appendix-enums.md#textcase) | 是 | 文本大小写。<br/>默认值：TextCase.Normal | 91 92### fontColor 93 94fontColor(value: ResourceColor) 95 96设置字体颜色。 97 98**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 99 100**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 101 102**系统能力：** SystemCapability.ArkUI.ArkUI.Full 103 104**参数：** 105 106| 参数名 | 类型 | 必填 | 说明 | 107| ------ | ------------------------------------------ | ---- | ---------- | 108| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 字体颜色。<br/>默认值：'e6182431'<br/>Wearable设备上默认值为：'#c5ffffff' | 109 110### fontSize 111 112fontSize(value: number | string | Resource) 113 114设置字体大小。 115 116**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 117 118**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 119 120**系统能力：** SystemCapability.ArkUI.ArkUI.Full 121 122**参数：** 123 124| 参数名 | 类型 | 必填 | 说明 | 125| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 126| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。string类型支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"，不支持设置百分比字符串。<br/>Wearable设备上默认值为：15fp | 127 128### fontStyle 129 130fontStyle(value: FontStyle) 131 132设置字体样式。 133 134**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 135 136**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 137 138**系统能力：** SystemCapability.ArkUI.ArkUI.Full 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| ------ | ------------------------------------------- | ---- | --------------------------------------- | 144| value | [FontStyle](ts-appendix-enums.md#fontstyle) | 是 | 字体样式。<br/>默认值：FontStyle.Normal | 145 146### fontWeight 147 148fontWeight(value: number | FontWeight | string) 149 150设置文本的字体粗细，设置过大可能会在不同字体下有截断。 151 152**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 153 154**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 155 156**系统能力：** SystemCapability.ArkUI.ArkUI.Full 157 158**参数：** 159 160| 参数名 | 类型 | 必填 | 说明 | 161| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 162| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | 是 | 文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal | 163 164### fontFamily 165 166fontFamily(value: string | Resource) 167 168设置字体列表。 169 170**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 171 172**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 180| value | string \| [Resource](ts-types.md#resource) | 是 | 字体列表。默认字体'HarmonyOS Sans'。<br>应用当前支持'HarmonyOS Sans'字体和[注册自定义字体](../js-apis-font.md)。<br>卡片当前仅支持'HarmonyOS Sans'字体。 | 181 182### lineHeight<sup>10+</sup> 183 184lineHeight(value: Length) 185 186设置文本行高。设置string类型时，支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。 187 188**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 189 190**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| ------ | ------ | ---- | ---- | 196| value | [Length](ts-types.md#length) | 是 | 文本行高。 | 197 198### font<sup>10+</sup> 199 200font(value: Font) 201 202设置文本样式。包括字体大小、字体粗细、字体族和字体风格。 203 204**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 205 206**系统能力：** SystemCapability.ArkUI.ArkUI.Full 207 208**参数：** 209 210| 参数名 | 类型 | 必填 | 说明 | 211| ------ | ------------------------ | ---- | ---------- | 212| value | [Font](ts-types.md#font) | 是 | 文本样式。 | 213 214### textShadow<sup>11+</sup> 215 216textShadow(value: ShadowOptions | Array<ShadowOptions>) 217 218设置文字阴影效果。该接口支持以数组形式入参，实现多重文字阴影。不支持fill字段, 不支持智能取色模式。 219 220**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 221 222**系统能力：** SystemCapability.ArkUI.ArkUI.Full 223 224**参数：** 225 226| 参数名 | 类型 | 必填 | 说明 | 227| ------ | ----- | ---- | --- | 228| value | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| Array<[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明)> | 是 | 文字阴影效果。 | 229 230## 事件 231 232通用事件仅支持[点击事件](ts-universal-events-click.md)。 233 234> **说明：** 235> 236> 由于Span组件无尺寸信息，因此点击事件返回的ClickEvent对象的target属性无效。 237 238## BaseSpan 239 240定义BaseSpan基础类，包含Span的通用属性。 241 242**系统能力：** SystemCapability.ArkUI.ArkUI.Full 243 244**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 245 246### textBackgroundStyle<sup>11+</sup> 247 248textBackgroundStyle(style: TextBackgroundStyle): T 249 250设置背景样式。作为[ContainerSpan](ts-basic-components-containerspan.md)的子组件时可以继承它的此属性值，优先使用其自身的此属性。 251 252**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 253 254**系统能力：** SystemCapability.ArkUI.ArkUI.Full 255 256**参数：** 257 258| 参数名 | 类型 | 必填 | 说明 | 259| ----- | ---- | ---- | ---- | 260| style | [TextBackgroundStyle](#textbackgroundstyle11对象说明) | 是 | 背景样式。<br />默认值:<br />{<br /> color: Color.Transparent,<br /> radius: 0<br />} | 261 262**返回值：** 263 264| 类型 | 说明 | 265| ---------------------------------------- | ------- | 266| T | 返回当前Span的属性。 | 267 268### baselineOffset<sup>12+</sup> 269 270baselineOffset(value: LengthMetrics): T 271 272设置Span基线的偏移量。此属性与父组件的baselineOffset是共存的。 273 274**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 275 276**系统能力：** SystemCapability.ArkUI.ArkUI.Full 277 278**参数：** 279 280| 参数名 | 类型 | 必填 | 说明 | 281| ----- | ---- | ---- | ---- | 282| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 设置Span基线的偏移量，设置该值为百分比时，按默认值显示。<br/>正数内容向上偏移，负数向下偏移。<br/>默认值：0<br/>在ImageSpan中，设置为非0时会导致设置verticalAlign失效。 | 283 284**返回值：** 285 286| 类型 | 说明 | 287| ---------------------------------------- | ------- | 288| T | 返回当前Span的属性。 | 289 290## TextBackgroundStyle<sup>11+</sup>对象说明 291 292**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 293 294**系统能力：** SystemCapability.ArkUI.ArkUI.Full 295 296| 名称 | 类型 | 必填 | 说明 | 297| ------ | ------- | ---- | ------------ | 298| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 文本背景色。 | 299| radius | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-universal-attributes-border.md#borderradiuses9对象说明) | 否 | 文本背景圆角。 | 300 301## 示例 302### 示例1（设置文本样式） 303 304该示例展示了设置不同样式的文本效果以及span配置点击事件。 305 306```ts 307// xxx.ets 308@Entry 309@Component 310struct SpanExample { 311 build() { 312 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 313 Text('Basic Usage').fontSize(9).fontColor(0xCCCCCC) 314 Text() { 315 Span('In Line') 316 Span(' Component') 317 Span(' !') 318 } 319 320 Text() { 321 Span('This is the Span component').fontSize(12).textCase(TextCase.Normal) 322 .decoration({ type: TextDecorationType.None, color: Color.Red }) 323 .fontFamily('HarmonyOS Sans') 324 }.margin({ top: 12 }) 325 326 // 文本横线添加 327 Text('Text Decoration').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 328 Text() { 329 Span('I am Underline-WAVY-span') 330 .decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY }) 331 .fontSize(12) 332 } 333 334 Text() { 335 Span('I am LineThrough-DOTTED-span') 336 .decoration({ type: TextDecorationType.LineThrough, color: Color.Red, style: TextDecorationStyle.DOTTED }) 337 .fontSize(12) 338 } 339 340 Text() { 341 Span('I am Overline-DASHED-span') 342 .decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DASHED }) 343 .fontSize(12) 344 } 345 346 // 文本字符间距 347 Text('LetterSpacing').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 348 Text() { 349 Span('span letter spacing') 350 .letterSpacing(0) 351 .fontSize(12) 352 } 353 354 Text() { 355 Span('span letter spacing') 356 .letterSpacing(-2) 357 .fontSize(12) 358 } 359 360 Text() { 361 Span('span letter spacing') 362 .letterSpacing(3) 363 .fontSize(12) 364 } 365 366 // 文本大小写展示设置 367 Text('Text Case').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 368 Text() { 369 Span('I am Lower-span').fontSize(12) 370 .textCase(TextCase.LowerCase) 371 .decoration({ type: TextDecorationType.None }) 372 } 373 374 Text() { 375 Span('I am Upper-span').fontSize(12) 376 .textCase(TextCase.UpperCase) 377 .decoration({ type: TextDecorationType.None }) 378 } 379 380 // 文本字体样式设置 381 Text('FontStyle').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 382 Text() { 383 Span('I am FontStyle-Normal').fontSize(12) 384 .fontStyle(FontStyle.Normal) 385 } 386 387 Text() { 388 Span('I am FontStyle-Italic').fontSize(12) 389 .fontStyle(FontStyle.Italic) 390 } 391 392 // 文本字体粗细设置 393 Text('FontWeight').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 394 Text() { 395 Span('I am FontWeight-Lighter').fontSize(12) 396 .fontWeight(FontWeight.Lighter) 397 } 398 399 Text() { 400 Span('I am FontWeight-Bold').fontSize(12) 401 .fontWeight(FontWeight.Bold) 402 } 403 404 // 文本行高设置 405 Text('LineHeight').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 406 Text() { 407 Span('I am lineHeight default\n').fontSize(12) 408 .fontWeight(FontWeight.Lighter) 409 Span('I am lineHeight 30').fontSize(12) 410 .lineHeight(30) 411 } 412 .backgroundColor(Color.Gray) 413 414 // 文本样式设置 415 Text('Font').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 416 Text() { 417 Span('span font 12 Bolder Italic') 418 .font({ 419 size: 12, 420 weight: FontWeight.Bolder, 421 style: FontStyle.Italic, 422 family: "HarmonyOS Sans" 423 }) 424 } 425 426 // span点击事件设置 427 Text('span click event').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 }) 428 Text() { 429 Span('Span default ').fontSize(12) 430 Span('Span click') 431 .onClick((event) => { 432 console.log("span onClick") 433 }) 434 } 435 }.width('100%').padding({ left: 35, right: 35, top: 35 }) 436 } 437} 438``` 439 440 441 442### 示例2（设置文本阴影） 443 444该示例通过textShadow属性展示了文本设置阴影的效果。 445 446``` ts 447// xxx.ets 448@Entry 449@Component 450struct SpanExample { 451 @State textShadows: ShadowOptions | Array<ShadowOptions> = [{ 452 radius: 10, 453 color: Color.Red, 454 offsetX: 10, 455 offsetY: 0 456 }, { 457 radius: 10, 458 color: Color.Orange, 459 offsetX: 20, 460 offsetY: 0 461 }, 462 { 463 radius: 10, 464 color: Color.Yellow, 465 offsetX: 30, 466 offsetY: 0 467 }, { 468 radius: 10, 469 color: Color.Green, 470 offsetX: 40, 471 offsetY: 0 472 }, 473 { 474 radius: 10, 475 color: Color.Blue, 476 offsetX: 100, 477 offsetY: 0 478 }] 479 480 build() { 481 Column({ space: 8 }) { 482 Text() { 483 Span('123456789').fontSize(50).textShadow(this.textShadows).fontColor(Color.Pink) 484 } 485 486 Text() { 487 Span('123456789') // span can inherit text shadow & font size from outer text 488 }.fontSize(50).textShadow(this.textShadows).fontColor(Color.Pink) 489 } 490 } 491} 492``` 493 494 495### 示例3（设置背景样式） 496 497该示例通过textBackgroundStyle属性展示了文本设置背景样式的效果。 498 499``` ts 500// xxx.ets 501@Component 502@Entry 503struct SpanExample { 504 build() { 505 Column() { 506 Text() { 507 Span(' Hello World ! ') 508 .fontSize('20fp') 509 .textBackgroundStyle({ color: "#7F007DFF", radius: "5vp" }) 510 .fontColor(Color.White) 511 } 512 }.width('100%').margin({ bottom: '5vp' }).alignItems(HorizontalAlign.Center) 513 } 514} 515``` 516 517 518### 示例4（设置文本基线偏移量） 519 520该示例通过baselineOffset属性展示了文本设置不同基线偏移量的效果。 521 522```ts 523// xxx.ets 524import { LengthUnit, LengthMetrics } from '@kit.ArkUI'; 525 526@Entry 527@Component 528struct SpanExample { 529 build() { 530 Row() { 531 Column() { 532 Text() { 533 Span('SpanOne') 534 .fontSize(10) 535 .baselineOffset(new LengthMetrics(20, LengthUnit.VP)) 536 Span('SpanTwo') 537 .fontSize(10) 538 .baselineOffset(new LengthMetrics(0, LengthUnit.VP)) 539 ImageSpan($r("app.media.sky"))//建议使用自定义的本地图片 540 .width('80px') 541 .baselineOffset(new LengthMetrics(-20, LengthUnit.VP)) 542 } 543 .backgroundColor('#7F007DFF') 544 } 545 .width('100%') 546 } 547 .height('100%') 548 } 549} 550``` 551 552 553 554
