文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载导读ImageSpan是仓颉 ArkUI 声明式 UI 框架中作为Text组件子组件使用的行内图片组件用于在文本流中嵌入图片实现图文混排效果。本文基于开源仓库 cj-text-input-imagespan.md 展开系统讲解 ImageSpan 的组件创建、三种核心属性颜色滤镜、缩放类型、对齐方式与两种加载事件并结合 cj-common-types.md、cj-image-video-image.md 等仓库文档给出类型级细节。读完本文你将能够独立编写图文混排的 Text 界面并正确配置图片的缩放、对齐、滤镜与加载失败兜底逻辑。ImageSpan 组件定位与使用前提ImageSpan作为 Text 组件的子组件用于显示行内图片。根据 cj-text-input-text.md 中的说明Text组件可以包含 Span 与ImageSpan两类子组件因此它承担的是文本流中的图片占位职责——与普通Image组件独立渲染不同ImageSpan必须嵌套在Text组件内部使用且不允许再包含任何子组件。导入模块使用前需要导入 ArkUI 声明式开发包import kit.ArkUI.*同时ImageSpan在 cj-common-types.md 中属于SystemCapability.ArkUI.ArkUI.Full系统能力起始版本为22使用时需确认运行环境满足该系统能力与版本要求。创建 ImageSpan 组件ImageSpan提供两种初始化方式分别对应字符串/资源引用与位图对象两种图片数据源。init(?ResourceStr)以资源或路径创建public init(value: ?ResourceStr)功能创建 ImageSpan 组件value为图片的数据源支持本地图片和网络图片。参数名类型必填默认值说明value?ResourceStr是-图片的数据源支持本地图片和网络图片。ResourceStr是 cj-common-types.md 中定义的字符串类型接口用于描述字符串入参可以使用的类型并通过extend String : ResourceStr {}将String扩展为其子类。因此实际传参时既可以直接传入字符串形式的图片路径也可以通过资源引用形式传入例如示例中的r(app.media.startIcon)。init(?PixelMap)以位图对象创建public init(value: ?PixelMap)功能创建 ImageSpan 组件value同样支持本地图片和网络图片的数据源。参数名类型必填默认值说明value?PixelMap是-图片的数据源支持本地图片和网络图片。PixelMap定义于 cj-apis-image.md是图像像素类用于读取或写入图像数据以及获取图像信息系统能力为SystemCapability.Multimedia.Image.Core。文档同时提示在调用 PixelMap 的方法前需要先通过createPixelMap构建实例PixelMap 序列化大小最大 128MB按宽 × 高 × 每像素占用字节数计算超过会送显失败。当需要把运行期生成的位图如相机拍摄、Canvas 绘制、解码得到的图片插入文本时可优先选用此构造方式。通用属性与通用事件ImageSpan支持三类通用属性与一种通用事件继承自 ArkUI 通用能力体系通用属性支持尺寸设置、背景设置、边框设置。这意味着可以像普通组件一样通过.width()、.height()、.backgroundColor()、.border()等链式调用控制图片的显示尺寸与外观。通用事件仅支持点击事件。与 Span 组件因无尺寸信息导致点击事件 target 属性无效不同ImageSpan具备明确的尺寸信息可正常响应点击交互适合作为文本内可点击的图片入口。组件属性详解func colorFilter(?ColorFilter)颜色滤镜public func colorFilter(filter: ?ColorFilter): This功能设置图像的颜色滤镜效果。参数名类型必填默认值说明filter?ColorFilter是-颜色滤镜效果初始值ColorFilter([])。ColorFilter定义于 cj-image-video-image.md本质是一个4×5 的颜色滤镜矩阵通过构造方法public init(value: ?ArrayFloat32)传入 20 个浮点数4 行 × 5 列构建时初始值为[]。矩阵作用于图像像素的 RGBA 通道可实现色调偏移、通道交换、透明度调整等效果。示例 2 中给出了两个典型矩阵blueColor对 R、G、B 通道分别乘以 0.38、0.81、0.43产生蓝色系色调colorFilter对通道进行重排与交换如 R 通道叠加 B 分量形成色彩置换效果。func objectFit(?ImageFit)缩放类型public func objectFit(value: ?ImageFit): This功能设置图片的缩放类型。参数名类型必填默认值说明value?ImageFit是-图片的缩放类型初始值ImageFit.Cover。ImageFit枚举定义于 cj-common-types.md共 6 个取值全部支持/!相等性比较operator func 、operator func !枚举值显示行为Fill不保持宽高比进行缩放图片被拉伸填满整个显示边界Contain保持宽高比缩小或放大使图片完全显示在显示边界内Cover保持宽高比缩小或放大使图片两边都大于或等于显示边界默认值Auto默认保持原图比例不变None图片不进行任何缩放保持原始尺寸显示ScaleDown图片按比例缩小但不会放大保持宽高比实际使用时建议与.width()、.height()配合Contain适合完整展示整张图Cover适合撑满区域并裁剪ScaleDown适合大图缩小、小图原样的保真场景。func verticalAlign(?ImageSpanAlignment)行内对齐方式public func verticalAlign(value: ?ImageSpanAlignment): This功能设置图片基于行高的对齐方式。参数名类型必填默认值说明value?ImageSpanAlignment是-图片基于文本的对齐方式初始值ImageSpanAlignment.Bottom。ImageSpanAlignment枚举定义于 cj-common-types.md共 4 个取值枚举值对齐行为Top图片上边沿与行上边沿对齐Center图片中间与行中间对齐Bottom图片下边沿与行下边沿对齐默认值Baseline图片下边沿与文本 BaseLine 对齐其中Baseline用于让图片与文字基线对齐是图文排版中最常用的选项之一Top/Center则适合行高较大、需要居中的场景。该枚举同样实现EquatableImageSpanAlignment支持相等性比较。组件事件详解func onComplete(?ImageCompleteCallback)加载完成回调public func onComplete(callback: ?ImageCompleteCallback): This功能图片数据加载成功和解码成功时均触发该事件。参数名类型必填默认值说明callback?ImageCompleteCallback是-回调函数图片数据加载成功和解码成功时触发。参数成功加载的图片尺寸。初始值{ _ }。ImageCompleteCallback定义于 cj-image-video-image.md类型为public type ImageCompleteCallback (ImageLoadResult) - Unit回调入参ImageLoadResult见 cj-image-video-image.md包含以下字段可用于获取实际渲染结果字段类型说明width / heightFloat64图片的宽、高pxcomponentWidth / componentHeightFloat64组件的宽、高pxcontentWidth / contentHeightFloat64图片实际绘制的宽、高px仅在 loadingStatus 返回 1 时有效contentOffsetX / contentOffsetYFloat64实际绘制内容相对组件自身的 x/y 轴偏移px仅在 loadingStatus 返回 1 时有效loadingStatusInt32图片加载成功的状态func onError(?ImageErrorCallback)加载异常回调public func onError(callback: ?ImageErrorCallback): This功能图片加载异常时触发该事件。参数名类型必填默认值说明callback?ImageErrorCallback是-回调函数图片加载出现异常时触发。参数图片加载异常信息。初始值{ _ }。ImageErrorCallback定义于 cj-image-video-image.md类型为public type ImageErrorCallback (ImageError) - Unit回调入参ImageError见 cj-image-video-image.md包含三个字段componentWidth、componentHeight组件宽高px与message错误信息可在回调中记录错误日志或执行降级展示。完整示例代码示例 1对齐方式与缩放效果该示例通过verticalAlign、objectFit属性展示了 ImageSpan 的对齐方式以及缩放效果将四张图片与带删除线的 Span 文本混合排布直观对比Contain/Fill/Auto缩放与Center/Top/Baseline/Bottom对齐的差异package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* import ohos.i18n.* import ohos.resource_manager.* import ohos.resource.__GenerateResource__ Entry Component class EntryView { func build() { Column { Flex(direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center) { Text() { //以设定大小和排布方式加载图片资源 ImageSpan(r(app.media.startIcon)) .width(150.px) .height(250.px) .objectFit(ImageFit.Contain) .verticalAlign(ImageSpanAlignment.Center) //对图片进行文本修饰 Span(This is the Span and ImageSpan component) .decoration(decorationType: TextDecorationType.LineThrough, color: Color.Red).fontSize(25) ImageSpan(r(app.media.startIcon)) .width(150.px) .height(50.px) .objectFit(ImageFit.Contain) .verticalAlign(ImageSpanAlignment.Top) Span(I am Underline-span2) .decoration(decorationType: TextDecorationType.LineThrough, color: Color.Red).fontSize(25) ImageSpan(r(app.media.startIcon)) .width(150.px) .height(250.px) .objectFit(ImageFit.Fill) .verticalAlign(ImageSpanAlignment.Baseline) Span(I am Underline-span3) .decoration(decorationType: TextDecorationType.LineThrough, color: Color.Red).fontSize(25) ImageSpan(r(app.media.startIcon)) .width(150.px) .height(50.px) .objectFit(ImageFit.Auto) .verticalAlign(ImageSpanAlignment.Bottom) Span(I am Underline-span4) .decoration(decorationType: TextDecorationType.LineThrough, color: Color.Red).fontSize(25) }.textAlign(TextAlign.Center) } } .height(720) .width(360) .padding(left:0, right: 0, top: 0) } }代码要点说明图片资源通过r(app.media.startIcon)引用需配合import ohos.resource.__GenerateResource__使用.width()/.height()使用.px单位显式指定图片显示区域同一行内ImageSpan与Span按声明顺序依次排布decoration(TextDecorationType.LineThrough, Color.Red)为相邻文本添加红色删除线便于观察对齐基准线.textAlign(TextAlign.Center)控制整段文本居中。示例 2颜色滤镜效果该示例通过colorFilter实现给图像设置颜色滤镜效果并利用onClick在两种滤镜之间动态切换package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* import ohos.i18n.* import ohos.resource_manager.* import ohos.resource.__GenerateResource__ Entry Component class EntryView { let blueColor ColorFilter([0.38, 0.0, 0.0, 0.0, 0.0, 0.0, 0.81, 0.0, 0.0, 0.0, 0.0, 0.0, 0.43, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0]) let colorFilter ColorFilter([1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0]) State var DrawingColorFilterFirst: ColorFilter blueColor State var DrawingColorFilterSecond: ColorFilter colorFilter func build() { Column(space: 5){ Text { ImageSpan(r(app.media.startIcon)) .width(100) .height(100) .colorFilter(this.DrawingColorFilterFirst) .onClick({ evt this.DrawingColorFilterFirst colorFilter }) } Text { ImageSpan(r(app.media.startIcon)) .width(110) .height(110) .margin(15) .colorFilter(this.DrawingColorFilterSecond) .onClick({ evt this.DrawingColorFilterSecond blueColor }) } } } }代码要点说明ColorFilter构造入参为 20 个Float32组成的 4×5 矩阵按行填充 RGBA 通道系数使用State修饰的ColorFilter状态变量绑定滤镜点击图片后在blueColor与colorFilter两套矩阵间切换体现状态驱动的滤镜实时刷新两个Text各自独立包含一个可点击的ImageSpan验证了 ImageSpan 的通用点击事件能力。实战要点与注意事项必须嵌套于 Text 内ImageSpan是Text的子组件不可脱离Text独立存在也不支持自身子组件图文混排时与Span按声明顺序混用即可。图片数据源选择静态资源/网络路径使用init(?ResourceStr)字符串或r()资源引用运行期位图使用init(?PixelMap)注意 PixelMap 需先经createPixelMap创建且序列化大小上限为 128MB宽 × 高 × 每像素字节数。缩放与对齐的配合objectFit默认CoververticalAlign默认Bottom。需要完整展示图片用Contain撑满区域用Cover/Fill保持原比例用Auto与文字基线对齐推荐Baseline。滤镜矩阵维度ColorFilter必须是 4×520 元素的Float32数组通道系数按 R、G、B、A 顺序排列示例 2 的矩阵可直接复用或改造。加载状态兜底建议同时注册onComplete与onError前者可通过ImageLoadResult获取实际绘制尺寸与loadingStatus后者可通过ImageError.message记录失败原因并做降级处理。版本与能力约束ImageSpan相关 API 起始版本均为 22系统能力为SystemCapability.ArkUI.ArkUI.FullPixelMap数据源则依赖SystemCapability.Multimedia.Image.Core部署前需确认运行环境满足对应版本与系统能力要求。总结ImageSpan是仓颉 ArkUI 实现文本行内图文混排的核心组件通过init(?ResourceStr)/init(?PixelMap)接入资源或位图数据源借助objectFit控制缩放、verticalAlign控制对齐、colorFilter实现滤镜并通过onComplete/onError感知加载结果。结合 cj-common-types.md、cj-image-video-image.md 与 cj-apis-image.md 中的类型定义开发者可精准掌握每个属性的取值范围与底层数据结构快速落地聊天表情、行内图标、富文本插图等场景。赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐CangjieCorpus仓颉 ArkUI TextPicker 文本选择器组件全解——创建、属性配置与 onChange 事件实战CangjieCorpus仓颉 ArkUI TextPicker 文本选择器组件全解——创建、属性配置与 onChange 事件实战 本文基于 Cangjie文档知识库教程OpenHarmony仓颉 ArkUI Button 按钮组件创建方式、ButtonOptions 配置与常用属性详解仓颉 ArkUI Button 按钮组件创建方式、ButtonOptions 配置与常用属性详解 本文基于仓颉Cangjie语言在 OpenHarmony文档知识库教程OpenHarmony仓颉 ArkUI PatternLock 图案密码锁组件详解创建、属性配置与密码验证实战仓颉 ArkUI PatternLock 图案密码锁组件详解创建、属性配置与密码验证实战 PatternLock 是仓颉语言 ArkUI方舟 UI 框架提文档知识库教程OpenHarmony上一篇big-AGI 深度集成指南Gemini Deep Research Agent 自主研究任务的完整实战手册下一篇offlineinsiderenrollWindows Insider计划离线退出工具使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考