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