鸿蒙界面开发——组件（2）：文本显示 (Text/Span) &文本输入 (TextInput/TextArea) &显示图片 (Image) & 自定义弹窗 (CustomDialog)

weightOneMillion

已于 2024-09-05 17:20:10 修改

阅读量1.4k

点赞数 30

分类专栏：鸿蒙前端学习文章标签： harmonyos 华为前端鸿蒙

于 2024-09-02 08:24:49 首次发布

本文链接：https://blog.csdn.net/littleyy666/article/details/141754782

版权

鸿蒙前端学习专栏收录该内容

29 篇文章 5 订阅

订阅专栏

文本显示 (Text/Span)

Text可通过以下两种方式来创建：

Text(content?: string | Resource , value?: TextOptions)
Text('我是一段文本')//string字符串
Text($r('app.string.module_desc'))//引用Resource资源，文件位置为/resources/base/element/string.json。

参数名	类型	必填	说明
content	string或Resource	否	文本内容。包含子组件Span且未设置属性字符串时content 不生效，显示Span内容，并且此时text组件的样式不生效。默认值：’ '。设置属性字符串时也不生效。

value | TextOptions | 否 | 文本组件初始化选项。

文本组件初始化选项TextOptions可选项为文本控制器TextController。

controller: TextController = new TextController();
Text(undefined, { controller: this.controller })

TextController 的属性方法有：
closeSelectionMenu(): void 关闭自定义选择菜单或系统默认选择菜单。
setStyledString(value: StyledString): void 触发绑定或更新属性字符串。
getLayoutManager(): LayoutManager 获取布局管理器对象。

setStyledString 触发绑定或更新属性字符串可以参考属性字符串StyledString一章，设置更灵活的文本样式。

属性

除支持通用属性和文本通用属性外，还支持以下属性：

textAlign(value: TextAlign)设置文本段落在水平方向的对齐方式。

名称	描述
TextAlign.Start	水平对齐首部。
TextAlign.Center	水平居中对齐。
TextAlign.End	水平对齐尾部。
TextAlign.JUSTIFY	双端对齐。
当textAlign属性设置为TextAlign.JUSTIFY时，需要根据文本内容设置wordBreak(设置断行规则)属性，且最后一行文本不参与两端对齐，为水平对齐首部效果。
文本段落宽度占满Text组件宽度。可通过align（设置容器元素绘制区域内的子元素的对齐方式。）属性控制文本段落在垂直方向上的位置。

textOverflow(value: { overflow: TextOverflow })设置文本超长时的显示方式。

名称	描述
TextOverflow .None	文本超长时按最大行截断显示。
TextOverflow .Clip	文本超长时按最大行截断显示。
TextOverflow .Ellipsis	文本超长时显示不下的文本用省略号代替。
TextOverflow .MARQUEE	文本超长时以跑马灯的方式展示。

当overflow设置为TextOverflow.None、TextOverflow.Clip、TextOverflow.Ellipsis时，需配合maxLines使用，单独设置不生效。设置TextOverflow.None与TextOverflow.Clip效果一样。

当overflow设置为TextOverflow.MARQUEE时，文本在一行内滚动显示，设置maxLines及copyOption属性均不生效。在文本不可滚动时，设置textAlign属性生效；在文本可滚动时，设置textAlign属性不生效。在跑马灯模式下，Text组件clip属性默认为true。

maxLines(value: number)设置文本的最大行数。
lineHeight(value: number | string | Resource)设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，number类型时单位为fp。
decoration(value: DecorationStyleInterface)设置文本装饰线样式及其颜色。

参数名	类型	必填	说明
type	TextDecorationType	是	装饰线类型。取值：None、Underline、LineThrough、Overline
color	ResourceColor	否	装饰线颜色。
style	TextDecorationStyle	否	装饰线样式。取值SOLID、DOUBLE、DOTTED、DASHED、WAVY

baselineOffset(value: number | string)设置文本基线的偏移量，设置该值为百分比时，按默认值显示。
letterSpacing(value: number | string)设置文本字符间距。当取值为负值时，文字会发生压缩.
minFontSize(value: number | string | Resource)设置文本最小显示字号。需配合maxFontSize以及maxlines或布局大小限制使用，单独设置不生效，对子组件和属性字符串不生效。自适应字号生效时，fontSize设置不生效。minFontSize小于或等于0时，自适应字号不生效。
maxFontSize(value: number | string | Resource)同上
textCase(value: TextCase)设置文本大小写。
copyOption(value: CopyOptions)设置组件是否支持文本可复制粘贴
draggable(value: boolean)设置选中文本拖拽效果。
font(value: Font)设置文本样式。包括字体大小、字体粗细、字体族和字体风格。
textShadow(value: ShadowOptions | Array)设置文字阴影效果。
heightAdaptivePolicy(value: TextHeightAdaptivePolicy)设置文本自适应高度的方式。
textIndent(value: Length)设置首行文本缩进。
wordBreak(value: WordBreak)设置断行规则。WordBreak.BREAK_ALL与{overflow: TextOverflow.Ellipsis}，maxLines组合使用可实现英文单词按字母截断，超出部分以省略号显示
selection(selectionStart: number, selectionEnd: number)设置选中区域。选中区域高亮且显示手柄和文本选择菜单。
ellipsisMode(value: EllipsisMode)设置省略位置。
enableDataDetector(enable: boolean)
dataDetectorConfig(config: TextDataDetectorConfig)需配合enableDataDetector一起使用
bindSelectionMenu(spanType: TextSpanType, content: CustomBuilder, responseType: TextResponseType,options?: SelectionMenuOptions)
TextSpanType枚举说明

名称	说明
TEXT	Span为文字类型。
IMAGE	Span为图像类型。
MIXED	Span为图文混合类型。
TextResponseType枚举说明

名称	描述
RIGHT_CLICK	通过鼠标右键触发菜单弹出。
LONG_PRESS	通过长按触发菜单弹出。
SELECT	通过鼠标选中触发菜单弹出。

fontFeature(value: string)设置文字特性效果，比如数字等宽的特性。
lineSpacing(value: LengthMetrics)设置文本的行间距
privacySensitive(supported: boolean)设置是否支持卡片敏感隐私信息。
lineBreakStrategy(strategy: LineBreakStrategy)设置折行规则。该属性在wordBreak不等于breakAll的时候生效，不支持连词符。
textSelectable(mode: TextSelectableMode)设置是否支持文本可选择、可获焦以及Touch后能否获取焦点。
editMenuOptions(editMenu: EditMenuOptions)设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。
minFontScale(scale: number | Resource)设置文本最小的字体缩放倍数。
maxFontScale(scale: number | Resource)设置文本最大的字体缩放倍数。
halfLeading(halfLeading: boolean)设置文本是否将行间距平分至行的顶部与底部。

事件

除支持通用事件外，还支持以下事件：

onCopy(callback:(value: string) => void)长按文本内部区域弹出剪贴板后，点击剪切板复制按钮，触发该回调。目前文本复制仅支持文本。
onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void)文本选择的位置发生变化时，触发该回调。

Span&ImageSpan&ContainerSpan&SymbolSpan

Span只能作为Text和RichEditor组件的子组件显示文本内容。可以在一个Text内添加多个Span来显示一段信息，例如产品说明书、承诺书等。
Span作为Text、ContainerSpan组件的子组件，用于显示行内文本的组件。

Text('我是Text') {
  Span('我是Span')
}

ImageSpan：Text、ContainerSpan组件的子组件，用于显示行内图片。
ContainerSpan：Text组件的子组件，用于统一管理多个Span、ImageSpan的背景色及圆角弧度。
SymbolSpan：作为Text组件的子组件，用于显示图标小符号的组件。

属性

和Text属性有很多重合。属性继承自BaseSpan，通用属性方法仅支持文本通用。

文本输入 (TextInput/TextArea)

TextInput为单行输入框、TextArea为多行输入框。通过以下接口来创建。

TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController})
TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextAreaController})

多行输入框文字超出一行时会自动折行。

设置输入框当前的文本内容。

TextInput({placeholder:'我是提示文本',text:'我是当前文本内容'})

在这里插入图片描述
TextInput默认会占据一行，单行输入框可设置.width('auto')使组件宽度自适应文本宽度(从API version 10开始)

.width('auto')

默认情况下，通用属性padding的默认值为：

{top: '8vp',
right: '16vp',
bottom: '8vp',
left: '16vp'}

输入框开启下划线模式时通用属性padding的默认值为：

{top: '12vp',
right: '0vp',
bottom: '12vp',
left: '0vp'}

文本输入框默认圆角矩形框，独占一行？？。可将内边距Padding设置为0。

TextInput属性

除支持通用属性和文本通用属性的fontColor、fontSize、fontStyle、fontWeight、fontFamily外，还支持以下属性：

type(value: InputType)设置输入框类型。InputType枚举说明：Normal、Password、Email、Number、PhoneNumber
enableAutoFill(value: boolean)设置是否启用自动填充。
contentType(value: ContentType)设置自动填充类型。ContentType枚举说明
placeholderColor(value: ResourceColor)设置placeholder文本颜色。
placeholderFont(value?: Font)设置placeholder文本样式，包括字体大小，字体粗细，字体族，字体风格。目前仅支持默认字体族。
enterKeyType(value: EnterKeyType)设置输入法回车键类型。
caretColor(value: ResourceColor)设置输入框光标颜色。
caretStyle(value: CaretStyle)设置光标风格。
maxLength(value: number)设置文本的最大输入字符数。
caretPosition(value: number)设置光标位置。
inputFilter(value: ResourceStr, error?: (value: string) => void)通过正则表达式设置输入过滤器。
copyOption(value: CopyOptions)设置输入的文本是否可复制。
showPasswordIcon(value: boolean)设置当密码输入模式时，输入框末尾的图标是否显示。
style(value: TextInputStyle | TextContentStyle)设置输入框为默认风格或内联输入风格，内联输入风格只支持InputType.Normal类型。
textAlign(value: TextAlign)设置文本在输入框中的水平对齐方式。
selectedBackgroundColor(value: ResourceColor)设置文本选中底板颜色。
showUnit(value: CustomBuilder)设置控件作为文本框单位。需搭配showUnderline使用。
showUnderline(value: boolean)设置是否开启下划线。
showError(value?: ResourceStr | undefined)设置错误状态下提示的错误文本或者不显示错误状态。
underlineColor(value: ResourceColor|UnderlineColor|undefined)开启下划线时，支持配置下划线颜色。
passwordIcon(value: PasswordIcon)设置当密码输入模式时，输入框末尾的图标。
enableKeyboardOnFocus(value: boolean)设置TextInput通过点击以外的方式获焦时，是否绑定输入法。
selectionMenuHidden(value: boolean)设置是否不弹出系统文本选择菜单。
barState(value: BarState)设置内联输入风格编辑态时滚动条的显示模式。
maxLines(value: number)设置内联输入风格编辑态时文本可显示的最大行数。
customKeyboard(value: CustomBuilder, options?: KeyboardOptions)设置自定义键盘。
passwordRules(value: string)定义生成密码的规则
cancelButton(value: { style?: CancelButtonStyle, icon?: IconOptions })设置右侧清除按钮样式。不支持内联模式。
selectAll(value: boolean)设置当初始状态，是否全选文本。不支持内联模式。
showCounter(value: boolean, options?: InputCounterOptions)设置当通过InputCounterOptions输入的字符数超过阈值时显示计数器。
showPassword(visible: boolean)设置密码的显隐状态。需组合密码模式才能生效
enablePreviewText(enable: boolean)设置是否开启输入预上屏。

事件

onChange(callback: EditableTextOnChangeCallback)输入内容发生变化时，触发该回调。
onSubmit(callback: (enterKey: EnterKeyType, event: SubmitEvent) => void)按下输入法回车键触发该回调。
onEditChanged(callback: (isEditing: boolean) => void)输入状态变化时，触发该回调。deprecated
onEditChange(callback: (isEditing: boolean) => void)输入状态变化时，触发该回调。有光标时为编辑态，无光标时为非编辑态。isEditing为true表示正在输入。
onCopy(callback: (value: string) => void)进行复制操作时，触发该回调。
onCut(callback: (value: string) => void)进行剪切操作时，触发该回调。
onPaste(callback: (value: string, event: PasteEvent) => void)进行粘贴操作时，触发该回调。
onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void)文本选择的位置发生变化或编辑状态下光标位置发生变化时，触发该回调。
onContentScroll(callback: (totalOffsetX: number, totalOffsetY: number) => void)文本内容滚动时，触发该回调。
onSecurityStateChange(callback: Callback)密码显隐状态切换时，触发该回调。
onWillInsert(callback: Callback<InsertValue, boolean>)在将要输入时，触发该回调。
onDidInsert(callback: Callback)在输入完成时，触发该回调。
onWillDelete(callback: Callback<DeleteValue, boolean>)在将要删除时，触发该回调。
onDidDelete(callback: Callback)在删除完成时，触发该回调。

内联模式？

如图，嵌入输入框
在这里插入图片描述

键盘避让？

显示图片 (Image)

Image通过调用接口来创建，接口调用形式如下：

Image(src: PixelMap | ResourceStr | DrawableDescriptor)
src新增ImageContent类型，可指定对应的图形内容。

Image支持多种图片格式，包括png、jpg、bmp、svg和gif。
图片的数据源，支持本地图片和网络图片。

PixelMap格式为像素图，常用于图片编辑的场景。
ResourceStr包含Resource和string格式。

string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image(“common/test.jpg”)，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。

支持Base64字符串。格式data:image/[png|jpeg|bmp|webp|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。
支持file://路径前缀的字符串，应用沙箱URI：file:///。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。

Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。

当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。
传入ImageContent类型，指定图像内容。

说明：

ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。
ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。
ArkTS卡片上不支持 PixelMap类型。
加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。
网络图片必须支持RFC 9113标准，否则会导致加载失败。
如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用HTTP工具提前预下载，提高图片加载性能，方便应用侧管理数据。
如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。
如果SVG图片通过image标签引用本地其他图片，被引用的图片不支持svg格式和gif格式。

Image(src: PixelMap | ResourceStr | DrawableDescriptor, imageAIOptions: ImageAIOptions)
Image新增imageAIOptions参数，为组件设置AI分析选项。

加载图片资源

Image支持加载存档图、多媒体像素图两种类型。

存档图类型数据源

存档图类型的数据源可以分为本地资源、网络资源、Resource资源、媒体库资源和base64。

本地资源
创建文件夹，将本地图片放入ets文件夹下的任意位置。
Image组件引入本地图片路径，即可显示图片（根目录为ets文件夹）。
Image('images/view.jpg')
网络资源
Image('https://www.example.com/example.JPG') // 实际使用时请替换为真实地址
Resource资源
使用资源格式可以跨包/跨模块引入图片，resources文件夹下的图片都可以通过$r资源接口读 取到并转换到Resource格式。
Image($r('app.media.icon'))
还可以将图片放在rawfile文件夹下。
Image($rawfile('example1.png'))
媒体库file://data/storage
支持file://路径前缀的字符串，用于访问通过媒体库提供的图片路径。
	a.调用接口获取图库的照片url。
	b.从媒体库获取的url格式通常如下。
	Image('file://media/Photos/5')
base64
路径格式为data:image/[png|jpeg|bmp|webp];base64,[base64 data]，其中[base64 data]为Base64字符串数据。
Base64格式字符串可用于存储图片的像素数据，在网页上使用较为广泛。

多媒体像素图

显示矢量图

Image组件可显示矢量图（svg格式的图片），支持的svg标签为：svg、rect、circle、ellipse、path、line、polyline、polygon和animate。
svg格式的图片可以使用fillColor属性改变图片的绘制颜色。

属性

1.== alt==(value: string | Resource | PixelMap)设置图片加载时显示的占位图。当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。
2. objectFit(value: ImageFit) 设置图片的填充效果。可以使图片缩放到高度和宽度确定的框内。

 // 保持宽高比进行缩小或者放大，使得图片完全显示在显示边界内。
.objectFit(ImageFit.Contain)
 // 保持宽高比进行缩小或者放大，使得图片两边都大于或等于显示边界。
.objectFit(ImageFit.Cover)
// 自适应显示。
.objectFit(ImageFit.Auto)
// 不保持宽高比进行放大缩小，使得图片充满显示边界。
.objectFit(ImageFit.Fill)
// 保持宽高比显示，图片缩小或者保持不变。
.objectFit(ImageFit.ScaleDown)
// 保持原有尺寸显示。
.objectFit(ImageFit.None)

objectRepeat(value: ImageRepeat)设置图片的重复样式，从中心点向两边重复，剩余空间不足放下一张图片时会截断。svg、AnimatedDrawableDescriptor 不支持。
interpolation(value: ImageInterpolation)设置图片的插值效果，即缓解图片在缩放时的锯齿问题。svg、AnimatedDrawableDescriptor 不支持。
renderMode(value: ImageRenderMode)设置图片的渲染模式。通过renderMode属性设置图片的渲染模式为原色或黑白。svg、AnimatedDrawableDescriptor 、ColorFilter 不支持。
sourceSize(value: { width: number; height: number })设置图片解码尺寸。仅在目标尺寸小于图源尺寸时生效。
matchTextDirection(value: boolean)设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。
fitOriginalSize(value: boolean)设置图片的显示尺寸是否跟随图源尺寸。图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。默认值：false。
fillColor(value: ResourceColor)设置填充颜色，设置后填充颜色会覆盖在图片上。仅对svg图源生效，设置后会替换svg图片的填充颜色。如需对png图片进行修改颜色，可以使用colorFilter。
autoResize(value: boolean)设置图片解码过程中是否对图源自动缩放。
syncLoad(value: boolean)设置是否同步加载图片。建议加载尺寸较小的本地图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。默认值：false。
colorFilter(value: ColorFilter | DrawingColorFilter)为图像设置颜色滤镜效果。
draggable(value: boolean)设置组件默认拖拽效果。不能和onDragStart事件同时使用。
enableAnalyzer(enable: boolean)设置组件支持AI分析。不能和overlay属性同时使用
resizable(value: ResizableOptions)设置图像拉伸时可调整大小的图像选项。
dynamicRangeMode(value: DynamicRangeMode)设置期望展示的图像动态范围。该属性仅在手机设备上生效。

图片的解码尺寸sourceSize，图片的宽高，图片的缩放填充objectFit，图片的autoResize？？？

如何设置图片的尺寸？

事件

除支持通用事件外，还支持以下事件：

onComplete图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。
onError(callback: ImageErrorCallback)图片加载异常时触发该回调。
onFinish(event: () => void)当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。

自定义弹窗 (CustomDialog)

使用@CustomDialog装饰器装饰自定义弹窗。
@CustomDialog装饰器用于装饰自定义弹框，此装饰器内进行自定义内容（也就是弹框内容）。

@CustomDialog //
struct CustomDialogExample {
  controller: CustomDialogController = new CustomDialogController({
    builder: CustomDialogExample({}),
  })
  build() {
    Column() {
      Text('我是内容')
        .fontSize(20)
        .margin({ top: 10, bottom: 10 })
    }
  }
}

创建构造器，与装饰器呼应相连。

 @Entry
 @Component
 struct CustomDialogUser {
 //创建构造器，与装饰器呼应相连。
   dialogController: CustomDialogController = new CustomDialogController({
     builder: CustomDialogExample(),
   })
 }

点击与onClick事件绑定的组件使弹窗弹出。

@Entry
@Component
struct CustomDialogUser {
//创建构造器，与装饰器呼应相连。
  dialogController: CustomDialogController = new CustomDialogController({
    builder: CustomDialogExample(),
  })

  build() {
    Column() {
      Button('click me')
        .onClick(() => {
          this.dialogController.open()//点击与onClick事件绑定的组件使弹窗弹出。
        })
    }.width('100%').margin({ top: 5 })
  }
}

弹窗的交互

在@CustomDialog装饰器内添加按钮，同时添加数据函数。
页面内需要在构造器内进行接收，同时创建相应的函数操作。
可通过弹窗中的按钮实现路由跳转，同时获取跳转页面向当前页传入的参数。

弹窗的动画

弹窗通过定义openAnimation控制弹窗出现动画的持续时间，速度等参数。

弹窗的样式

弹窗通过定义宽度、高度、背景色、阴影等参数来控制样式。

@CustomDialog
struct CustomDialogExample {
  controller?: CustomDialogController
  build() {
    Column() {
      Text('我是内容').fontSize(16).margin({ bottom: 10 })
    }
  }
}

@Entry
@Component
struct CustomDialogUser {
  @State textValue: string = ''
  @State inputValue: string = 'click me'
  dialogController: CustomDialogController | null = new CustomDialogController({
    builder: CustomDialogExample(),
    autoCancel: true,
    alignment: DialogAlignment.Center,
    offset: { dx: 0, dy: -20 },
    gridCount: 4,
    customStyle: false,
    //自定义弹窗样式
    backgroundColor: 0xd9ffffff,
    cornerRadius: 20,
    width: '80%',
    height: '100px',
    borderWidth: 1,
    borderStyle: BorderStyle.Dashed,//使用borderStyle属性，需要和borderWidth属性一起使用
    borderColor: Color.Blue,//使用borderColor属性，需要和borderWidth属性一起使用
    shadow: ({ radius: 20, color: Color.Grey, offsetX: 50, offsetY: 0}),
  })

  // 在自定义组件即将析构销毁时将dialogController置空
  aboutToDisappear() {
    this.dialogController = null // 将dialogController置空
  }

  build() {
    Column() {
      Button(this.inputValue)
        .onClick(() => {
          if (this.dialogController != null) {
            this.dialogController.open()
          }
        }).backgroundColor(0x317aff)
    }.width('100%').margin({ top: 5 })
  }
}