输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
RelativeContainer
CustomDialogController
animateTo
CTRL+K
文档管理中心

HarmonyOS

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
RelativeContainer
CustomDialogController
animateTo
CTRL+K
FAQ

RichEditor实现添加图文并控制图文间距

更新时间: 2026-06-26 09:07
本文导读

问题现象

要在文本框中实现图片与文字的组合场景，类似于文件符号图片加文件名的组合。

使用有如下诉求：

  • 点击组合，光标自动后移至组合后面。
  • 组合有外间距。

背景知识

  • RichEditor：支持图文混排和文本交互式编辑的组件，实现精美、方便的文本编辑效果。
  • onSelectionChange：组件内所有内容选择区域发生变化或编辑状态下光标位置发生变化时触发该回调。光标位置发生变化回调时，根据当前光标是否处于组合Span，将光标移动指定位置。
  • aboutToIMEInput：输入法输入内容前，触发回调。确保输入的内容不会影响组合Span。

解决方案

  • 点击组合，光标自动后移至组合后面：
    1. 将组合中的Span分别写入RichEditor，然后记录具体的spanIndex。
    2. 当触发onSelectionChange回调时，使用getSpans获取当前光标的位置信息。
    3. 将获取到的光标位置与记录做对比，若存在则将光标移动至组合末尾。
    收起
    自动换行
    深色代码主题
    复制
    1. .onSelectionChange((data) => {
    2.   this.needNewSpan = false;
    3.   // 根据光标位置获取对应Span信息
    4.   let span = this.controller.getSpans(data);
    5.   if (span.length != 0) {
    6.     let spanLocation: number = span[0].spanPosition.spanIndex;
    7.     let res = this.isCombinations(spanLocation);
    8.     if (res) {
    9.       // 判断是否是多选
    10.       if (data.start != data.end) {
    11.         // 判断是否是第一次调整多选位置
    12.         if (!this.isSetSelection) {
    13.           // 将组合全选
    14.           this.isSetSelection = true;
    15.           if (span[0].spanPosition.spanIndex == this.combinationsLocation[this.needUpdateCombinations][0]) {
    16.             let spanText = this.controller.getSpans({ start: span[0].spanPosition.spanRange[1] + 1 });
    17.             this.controller.setSelection(span[0].spanPosition.spanRange[0],
    18.               spanText[0].spanPosition.spanRange[1]);
    19.           } else {
    20.             this.controller.setSelection(span[0].spanPosition.spanRange[0] - 1,
    21.               span[0].spanPosition.spanRange[1]);
    22.           }
    23.         } else {
    24.           this.isSetSelection = false;
    25.         }
    26.       } else {
    27.         // 移动光标至组合末尾
    28.         this.controller.setCaretOffset(span[0].spanPosition.spanRange[1]);
    29.         this.needNewSpan = true;
    30.       }
    31.     }
    32.   }
    33. })
  • 组合有外间距：
    1. 图片Span使用RichEditorLayoutStyle配置margin属性实现外边距。
    2. 文字Span目前无直接配置外边距，建议额外添加空格实现。
    收起
    自动换行
    深色代码主题
    复制
    1. // 写入Span组合
    2. combinations(text: string, img: PixelMap | ResourceStr) {
    3.   this.controller.addImageSpan(img, { imageStyle: { size: [20, 20], layoutStyle: { margin: { left: 5 } } } });
    4.   this.controller.addTextSpan(text + ' ', { style: { fontColor: Color.Blue, fontSize: 18 } });
    5. }
  • 完整示例参考如下：
    收起
    自动换行
    深色代码主题
    复制
    1. @Entry
    2. @Component
    3. struct Index4RichEditor {
    4.   controller: RichEditorController = new RichEditorController();
    5.   option: RichEditorOptions = { controller: this.controller };
    6.   img: Resource = $r('app.media.startIcon');
    7.   // 需要组合的Span记录
    8.   combinationsLocation: Array<Array<number>> = [[0, 1], [3, 4], [6, 7], [8, 9], [11, 12]];
    9.   // 当输入的文字处于组合末尾时，需要新建Span
    10.   needNewSpan: boolean = false;
    11.   // 是否需要更新组合Span记录
    12.   needUpdateCombinations: number = 0;
    13.   // 判断是否已经更新过选中区域
    14.   isSetSelection: boolean = false;
    15. 

    16.   // 写入Span组合
    17.   combinations(text: string, img: PixelMap | ResourceStr) {
    18.     this.controller.addImageSpan(img, { imageStyle: { size: [20, 20], layoutStyle: { margin: { left: 5 } } } });
    19.     this.controller.addTextSpan(text + ' ', { style: { fontColor: Color.Blue, fontSize: 18 } });
    20.   }
    21. 

    22.   // 判断位置是否处于组合内
    23.   isCombinations(spanLocation: number): boolean {
    24.     for (let index = 0; index < this.combinationsLocation.length; index++) {
    25.       if (spanLocation == this.combinationsLocation[index][0] || spanLocation === this.combinationsLocation[index][1]) {
    26.         this.needUpdateCombinations = index;
    27.         return true;
    28.       } else if (spanLocation < this.combinationsLocation[index][1]) {
    29.         return false;
    30.       }
    31.     }
    32.     return false;
    33.   }
    34. 

    35.   // 更新组合所处位置
    36.   updateCombinationsLocation() {
    37.     for (let index = this.needUpdateCombinations; index < this.combinationsLocation.length; index++) {
    38.       this.combinationsLocation[index][0] += 1;
    39.       this.combinationsLocation[index][1] += 1;
    40.     }
    41.   }
    42. 

    43.   build() {
    44.     Column() {
    45.       RichEditor(this.option)
    46.         .onReady(() => {
    47.           this.combinations('@PyLo', this.img);
    48.           this.controller.addTextSpan('请来会议室领取礼品，清单如下');
    49.           this.combinations('领取礼品清单', this.img);
    50.           this.controller.addTextSpan('，请参考清单到指定会议室');
    51.           this.combinations('身体健康', this.img);
    52.           this.combinations('万事如意', this.img);
    53.           this.controller.addImageSpan(this.img, { imageStyle: { size: [20, 20], objectFit: ImageFit.Contain } });
    54.           this.combinations('体锻如武夫', this.img);
    55.           this.controller.addImageSpan(this.img, { imageStyle: { size: [20, 20], objectFit: ImageFit.Contain } });
    56.         })
    57.         .onSelectionChange((data) => {
    58.           this.needNewSpan = false;
    59.           // 根据光标位置获取对应Span信息
    60.           let span = this.controller.getSpans(data);
    61.           if (span.length != 0) {
    62.             let spanLocation: number = span[0].spanPosition.spanIndex;
    63.             let res = this.isCombinations(spanLocation);
    64.             if (res) {
    65.               // 判断是否是多选
    66.               if (data.start != data.end) {
    67.                 // 判断是否是第一次调整多选位置
    68.                 if (!this.isSetSelection) {
    69.                   // 将组合全选
    70.                   this.isSetSelection = true;
    71.                   if (span[0].spanPosition.spanIndex == this.combinationsLocation[this.needUpdateCombinations][0]) {
    72.                     let spanText = this.controller.getSpans({ start: span[0].spanPosition.spanRange[1] + 1 });
    73.                     this.controller.setSelection(span[0].spanPosition.spanRange[0],
    74.                       spanText[0].spanPosition.spanRange[1]);
    75.                   } else {
    76.                     this.controller.setSelection(span[0].spanPosition.spanRange[0] - 1,
    77.                       span[0].spanPosition.spanRange[1]);
    78.                   }
    79.                 } else {
    80.                   this.isSetSelection = false;
    81.                 }
    82.               } else {
    83.                 // 移动光标至组合末尾
    84.                 this.controller.setCaretOffset(span[0].spanPosition.spanRange[1]);
    85.                 this.needNewSpan = true;
    86.               }
    87.             }
    88.           }
    89.         })
    90.         .aboutToIMEInput((value: RichEditorInsertValue) => {
    91.           if (this.needNewSpan) {
    92.             // 处理键入文字时光标位于组合末尾，防止与组合内文字Span拼接
    93.             this.controller.addTextSpan(value.insertValue, { offset: value.insertOffset });
    94.             this.updateCombinationsLocation();
    95.             return false;
    96.           } else if (value.insertOffset === 0) {
    97.             // 处理光标位于行首的特殊情况
    98.             this.needUpdateCombinations = 0;
    99.             this.updateCombinationsLocation();
    100.           }
    101.           return true;
    102.         })
    103.         .padding(6)
    104.         .borderRadius(6)
    105.         .backgroundColor('#d8d8d9')
    106.         .width("100%")
    107.         .height("30%");
    108.     }
    109.     .padding(6)
    110.     .width("100%")
    111.     .height("70%");
    112.   }
    113. }

常见FAQ

Q：为什么addBuilderSpan中信息数量过多的时候会出现当前行还未填充完毕就整体切换到下一行且无法分行？

A：目前addBuilderSpan所生成的Span仅作为一个元素使用，元素不可拆分，因此当前行不可容纳会自动换行且无法分行。

Q：部分图片是由本地HTML生成的，怎么添加到RichEditor里？

A：可以使用web组件加载本地HTML，再通过addBuilderSpan添加自定义布局到RichEditor里。

相关推荐
文档如何获取RichEditor组件中特殊字符
文档RichEditor实现“@XXX”自动替换图片
文档如何选择图文混排的实现方案
文档使用RichEditor实现“@用户名”并获取输入框全部内容
文档RichEditor获取ImageSpan中图片信息
文档RichEditor实现上下角标数字的效果
文档RichEditor组件实现图片插入后换行并横向居中效果
文档RichEditor组件如何添加视频
文档RichEditor设置内容自适应宽度
文档富文本编辑（RichEditor）
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 FAQ 中进行搜索
请输入您想要搜索的关键词