harmony 鸿蒙Span

2025-06-12
浏览 (3)

Span

作为Text、ContainerSpan组件的子组件，用于显示行内文本的组件。

说明：

该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

该组件从API version 10开始支持继承父组件Text的属性，即如果子组件未设置属性且父组件设置属性，则继承父组件设置的属性。支持继承的属性仅包括：fontColor、fontSize、fontStyle、fontWeight、decoration、letterSpacing、textCase、fontFamily、textShadow。

子组件

无

接口

Span(value: string|Resource)

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string \|Resource	是	文本内容。

属性

属性继承自BaseSpan。

decoration

decoration(value: DecorationStyleInterface)

设置文本装饰线样式及其颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	DecorationStyleInterface¹²⁺	是	文本装饰线样式对象。默认值： {  type: TextDecorationType.None,  color: Color.Black,  style: TextDecorationStyle.SOLID  } 说明： style参数不支持卡片能力。

letterSpacing

letterSpacing(value: number|ResourceStr)

设置文本字符间距。取值小于0，字符聚集重叠，取值大于0且随着数值变大，字符间距越来越大，稀疏分布。string类型支持number类型取值的字符串形式，可以附带单位，例如”10”、”10fp”。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number \| ResourceStr	是	文本字符间距。单位：fp 从API version 20开始，支持Resource类型。

textCase

textCase(value: TextCase)

设置文本大小写。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	TextCase	是	文本大小写。默认值：TextCase.Normal

fontColor

fontColor(value: ResourceColor)

设置字体颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	字体颜色。默认值：’e6182431’ Wearable设备上默认值为：’#c5ffffff’

参数名	类型	必填	说明
value	number \| string \| Resource	是	字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。string类型支持number类型取值的字符串形式，可以附带单位，例如”10”、”10fp”，不支持设置百分比字符串。 Wearable设备上默认值为：15fp

fontStyle

fontStyle(value: FontStyle)

设置字体样式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	FontStyle	是	字体样式。默认值：FontStyle.Normal

fontWeight

fontWeight(value: number|FontWeight|ResourceStr)

设置文本的字体粗细，设置过大可能会在不同字体下有截断。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number \| FontWeight \| ResourceStr	是	文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如”400”，以及”bold”、”bolder”、”lighter”、”regular”、”medium”，分别对应FontWeight中相应的枚举值。默认值：FontWeight.Normal 从API version 20开始，支持Resource类型。

fontFamily

fontFamily(value: string|Resource)

设置字体列表。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string \| Resource	是	字体列表。默认字体’HarmonyOS Sans’。应用当前支持’HarmonyOS Sans’字体和注册自定义字体。卡片当前仅支持’HarmonyOS Sans’字体。

lineHeight¹⁰⁺

lineHeight(value: Length)

设置文本行高。设置string类型时，支持number类型取值的字符串形式，可以附带单位，例如”10”、”10fp”。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Length	是	文本行高。

font¹⁰⁺

font(value: Font)

设置文本样式。包括字体大小、字体粗细、字体族和字体风格。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Font	是	文本样式。

textShadow¹¹⁺

textShadow(value: ShadowOptions|Array<ShadowOptions>)

设置文字阴影效果。该接口支持以数组形式入参，实现多重文字阴影。不支持fill字段, 不支持智能取色模式。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ShadowOptions \|  Array<ShadowOptions>	是	文字阴影效果。

事件

通用事件支持点击事件onClick、悬浮事件onHover。

说明：

由于Span组件无尺寸信息，因此点击事件返回的ClickEvent对象的target属性无效。

BaseSpan

定义BaseSpan基础类，包含Span的通用属性。

系统能力： SystemCapability.ArkUI.ArkUI.Full

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

textBackgroundStyle¹¹⁺

textBackgroundStyle(style: TextBackgroundStyle): T

设置背景样式。作为ContainerSpan的子组件时可以继承它的此属性值，优先使用其自身的此属性。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
style	TextBackgroundStyle	是	背景样式。默认值: { color: Color.Transparent, radius: 0 }

返回值：

类型	说明
T	返回当前Span的属性。

baselineOffset¹²⁺

baselineOffset(value: LengthMetrics): T

设置Span基线的偏移量。此属性与父组件的baselineOffset是共存的。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	LengthMetrics	是	设置Span基线的偏移量，设置该值为百分比时，按默认值显示。正数内容向上偏移，负数向下偏移。默认值：0 在ImageSpan中，设置为非0时会导致设置verticalAlign失效。

返回值：

类型	说明
T	返回当前Span的属性。

TextBackgroundStyle¹¹⁺对象说明

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
color	ResourceColor	否	文本背景色。
radius	Dimension \|BorderRadiuses	否	文本背景圆角。

示例

示例1（设置文本样式）

该示例展示了设置不同样式的文本效果以及span配置点击事件。

// xxx.ets
@Entry
@Component
struct SpanExample {
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
      Text('Basic Usage').fontSize(9).fontColor(0xCCCCCC)
      Text() {
        Span('In Line')
        Span(' Component')
        Span(' !')
      }

      Text() {
        Span('This is the Span component').fontSize(12).textCase(TextCase.Normal)
          .decoration({ type: TextDecorationType.None, color: Color.Red })
          .fontFamily('HarmonyOS Sans')
      }.margin({ top: 12 })

      // 文本横线添加
      Text('Text Decoration').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('I am Underline-WAVY-span')
          .decoration({ type: TextDecorationType.Underline, color: Color.Red, style: TextDecorationStyle.WAVY })
          .fontSize(12)
      }

      Text() {
        Span('I am LineThrough-DOTTED-span')
          .decoration({ type: TextDecorationType.LineThrough, color: Color.Red, style: TextDecorationStyle.DOTTED })
          .fontSize(12)
      }

      Text() {
        Span('I am Overline-DASHED-span')
          .decoration({ type: TextDecorationType.Overline, color: Color.Red, style: TextDecorationStyle.DASHED })
          .fontSize(12)
      }

      // 文本字符间距
      Text('LetterSpacing').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('span letter spacing')
          .letterSpacing(0)
          .fontSize(12)
      }

      Text() {
        Span('span letter spacing')
          .letterSpacing(-2)
          .fontSize(12)
      }

      Text() {
        Span('span letter spacing')
          .letterSpacing(3)
          .fontSize(12)
      }

      // 文本大小写展示设置
      Text('Text Case').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('I am Lower-span').fontSize(12)
          .textCase(TextCase.LowerCase)
          .decoration({ type: TextDecorationType.None })
      }

      Text() {
        Span('I am Upper-span').fontSize(12)
          .textCase(TextCase.UpperCase)
          .decoration({ type: TextDecorationType.None })
      }

      // 文本字体样式设置
      Text('FontStyle').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('I am FontStyle-Normal').fontSize(12)
          .fontStyle(FontStyle.Normal)
      }

      Text() {
        Span('I am FontStyle-Italic').fontSize(12)
          .fontStyle(FontStyle.Italic)
      }

      // 文本字体粗细设置
      Text('FontWeight').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('I am FontWeight-Lighter').fontSize(12)
          .fontWeight(FontWeight.Lighter)
      }

      Text() {
        Span('I am FontWeight-Bold').fontSize(12)
          .fontWeight(FontWeight.Bold)
      }

      // 文本行高设置
      Text('LineHeight').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('I am lineHeight default\n').fontSize(12)
          .fontWeight(FontWeight.Lighter)
        Span('I am lineHeight 30').fontSize(12)
          .lineHeight(30)
      }
      .backgroundColor(Color.Gray)

      // 文本样式设置
      Text('Font').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('span font 12 Bolder Italic')
          .font({
            size: 12,
            weight: FontWeight.Bolder,
            style: FontStyle.Italic,
            family: "HarmonyOS Sans"
          })
      }

      // span点击事件设置
      Text('span click event').fontSize(9).fontColor(0xCCCCCC).margin({ top: 12 })
      Text() {
        Span('Span default ').fontSize(12)
        Span('Span click')
          .onClick((event) => {
            console.log("span onClick")
          })
      }
    }.width('100%').padding({ left: 35, right: 35, top: 35 })
  }
}

Span

示例2（设置文本阴影）

该示例通过textShadow属性展示了文本设置阴影的效果。

// xxx.ets
@Entry
@Component
struct SpanExample {
  @State textShadows: ShadowOptions|Array<ShadowOptions> = [{
    radius: 10,
    color: Color.Red,
    offsetX: 10,
    offsetY: 0
  }, {
    radius: 10,
    color: Color.Orange,
    offsetX: 20,
    offsetY: 0
  },
    {
      radius: 10,
      color: Color.Yellow,
      offsetX: 30,
      offsetY: 0
    }, {
      radius: 10,
      color: Color.Green,
      offsetX: 40,
      offsetY: 0
    },
    {
      radius: 10,
      color: Color.Blue,
      offsetX: 100,
      offsetY: 0
    }]

  build() {
    Column({ space: 8 }) {
      Text() {
        Span('123456789').fontSize(50).textShadow(this.textShadows).fontColor(Color.Pink)
      }

      Text() {
        Span('123456789') // span can inherit text shadow & font size from outer text
      }.fontSize(50).textShadow(this.textShadows).fontColor(Color.Pink)
    }
  }
}

TextshadowExample

示例3（设置背景样式）

该示例通过textBackgroundStyle属性展示了文本设置背景样式的效果。

// xxx.ets
@Component
@Entry
struct SpanExample {
  build() {
    Column() {
      Text() {
        Span('   Hello World !   ')
          .fontSize('20fp')
          .textBackgroundStyle({ color: "#7F007DFF", radius: "5vp" })
          .fontColor(Color.White)
      }
    }.width('100%').margin({ bottom: '5vp' }).alignItems(HorizontalAlign.Center)
  }
}

TextBackgroundStyleExample

示例4（设置文本基线偏移量）

该示例通过baselineOffset属性展示了文本设置不同基线偏移量的效果。

// xxx.ets
import { LengthUnit, LengthMetrics } from '@kit.ArkUI';

@Entry
@Component
struct SpanExample {
  build() {
    Row() {
      Column() {
        Text() {
          Span('SpanOne')
            .fontSize(10)
            .baselineOffset(new LengthMetrics(20, LengthUnit.VP))
          Span('SpanTwo')
            .fontSize(10)
            .baselineOffset(new LengthMetrics(0, LengthUnit.VP))
          ImageSpan($r("app.media.sky"))//建议使用自定义的本地图片
            .width('80px')
            .baselineOffset(new LengthMetrics(-20, LengthUnit.VP))
        }
        .backgroundColor('#7F007DFF')
      }
      .width('100%')
    }
    .height('100%')
  }
}

SpanBaselineOffset

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙弹出框 (Dialog)

harmony 鸿蒙DialogV2

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/mJRjgn

harmony 鸿蒙Span

Span

子组件

接口

属性

decoration

letterSpacing

textCase

fontColor

fontSize

fontStyle

fontWeight

fontFamily

lineHeight¹⁰⁺

font¹⁰⁺

textShadow¹¹⁺

事件

BaseSpan

textBackgroundStyle¹¹⁺

baselineOffset¹²⁺

TextBackgroundStyle¹¹⁺对象说明

示例

示例1（设置文本样式）

示例2（设置文本阴影）

示例3（设置背景样式）

示例4（设置文本基线偏移量）

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

harmony 鸿蒙Span

Span

子组件

接口

属性

decoration

letterSpacing

textCase

fontColor

fontSize

fontStyle

fontWeight

fontFamily

lineHeight10+

font10+

textShadow11+

事件

BaseSpan

textBackgroundStyle11+

baselineOffset12+

TextBackgroundStyle11+对象说明

示例

示例1（设置文本样式）

示例2（设置文本阴影）

示例3（设置背景样式）

示例4（设置文本基线偏移量）

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

lineHeight¹⁰⁺

font¹⁰⁺

textShadow¹¹⁺

textBackgroundStyle¹¹⁺

baselineOffset¹²⁺

TextBackgroundStyle¹¹⁺对象说明