【HarmonyOS】富文本编辑器 RichEditor 详解
作者：GeorgeGcs
- 2025-07-06 上海
本文字数：11204 字
阅读完需：约 37 分钟
【HarmonyOS】富文本编辑器 RichEditor 详解
一、前言
在信息化高速发展的今天，普通的文本容器，已经不能够承载用户丰富的表达欲。富文本展示已经是移动开发中，必备要解决的问题，在鸿蒙中，通过在系统层提供 RichEditor 控件，来解决富文本展示的问题。
HarmonyOS 推出的 RichEditor 控件，提供了从基础文本输入到复杂图文混排的完整解决方案。
从 API version 10 开始支持的 RichEditor 控件，不仅具备文本输入、样式设置等基础能力，还创新性地支持自定义键盘、图文混排、事件回调等高级特性。
随着版本迭代，RichEditor 不断进化，从 API version 11 开始支持元服务调用，到 API version 20 引入 AI 菜单和撤销样式保留等功能，已发展为一个成熟稳定的富文本解决方案。
本文将从实际使用流程和完整实战 Demo 出发，详细解析 RichEditor 控件的核心功能与应用场景，帮助开发者快速掌握这一强大工具的使用方法。
二、使用流程
1、组件创建方式
RichEditor 控件提供了两种创建方式：
（1）使用属性字符串构建
这种方式一般用于比较简单的富文本场景，例如上图颜色不同的一段话。基于属性字符串(StyledString/MutableStyledString)构建，持有属性字符串对象来管理数据，通过修改属性字符串对象的内容、样式，再传递给组件，实现对富文本组件内容的更新。相比于使用 controller 接口进行内容样式更新，使用起来更加灵活便捷。
@Entry@Componentstruct Index {
// 定义字体样式对象，设置字体颜色为粉色 fontStyle: TextStyle = new TextStyle({ fontColor: Color.Pink });
// 创建可变样式字符串，用于存储富文本内容及其样式 // 初始文本为"使用属性字符串构建的RichEditor组件" // 并为前5个字符("使用属性字")应用上面定义的粉色字体样式 mutableStyledString: MutableStyledString = new MutableStyledString("使用属性字符串构建的RichEditor组件", [{ start: 0, // 样式起始位置（从0开始） length: 5, // 样式作用的字符长度 styledKey: StyledStringKey.FONT, // 样式类型为字体样式 styledValue: this.fontStyle // 具体的样式值 }]);
// 初始化属性字符串模式的RichEditor控制器 // 该控制器专门用于处理基于属性字符串的富文本操作 controller: RichEditorStyledStringController = new RichEditorStyledStringController();
// 配置RichEditor组件的选项，将控制器传入 options: RichEditorStyledStringOptions = { controller: this.controller };
build() { Column() { // 构建RichEditor组件，使用上面配置的选项 RichEditor(this.options) // 组件初始化完成回调 // 当RichEditor组件准备好后，将之前创建的可变样式字符串设置到编辑器中 .onReady(() => { this.controller.setStyledString(this.mutableStyledString); }) } .height('100%') // Column高度占满整个父容器 .width('100%') // Column宽度占满整个父容器 .justifyContent(FlexAlign.Center) // 垂直方向居中对齐子组件 }}
复制代码
（2）使用 RichEditorController 构建
这种方式一般用于复杂内容场景，通过 RichEditorController 提供的接口实现内容、样式的管理。
@Entry@Componentstruct IndexPage2 { // 初始化富文本编辑器控制器，用于管理RichEditor组件 controller: RichEditorController = new RichEditorController();
// 配置RichEditor组件选项，传入控制器实例 options: RichEditorOptions = { controller: this.controller };
build() { Column() { Column() { // 创建RichEditor组件并应用配置选项 RichEditor(this.options) // 组件初始化完成回调，用于设置初始内容 .onReady(() => { // 1. 添加第一段文本内容 // 使用addTextSpan方法添加文本，并设置橙色字体、16px大小 this.controller.addTextSpan('使用RichEditorController', { style: { fontColor: Color.Orange, fontSize: 16 } });
// 2. 添加符号内容 // 使用addSymbolSpan方法添加系统内置符号（篮球图标） // 设置符号大小为30px this.controller.addSymbolSpan($r("sys.symbol.basketball_fill"), { style: { fontSize: 30 } });
// 3. 添加第二段文本内容 // 使用addTextSpan方法添加文本，并设置红色字体、20px大小 this.controller.addTextSpan('构建富文本！！！', { style: { fontColor: Color.Red, fontSize: 20 } }); }) }.width('100%') // 内部Column宽度占满父容器 }.height('100%') // 外部Column高度占满父容器 }}
复制代码
2、组件的属性配置参数效果
RichEditor 提供了丰富的属性来定制编辑体验，下面介绍几个常用属性的配置方法。
（1）自定义选择菜单
通过 bindSelectionMenu 属性可以设置自定义选择菜单，替代组件默认的文本选择菜单，实现更丰富的菜单功能，如翻译、加粗等。
// 自定义菜单构建器@BuilderCustomMenu() { Column() { Menu() { MenuItemGroup() { MenuItem({ startIcon: $r('app.media.icon_bold'), content: "加粗" }) MenuItem({ startIcon: $r('app.media.icon_italic'), content: "斜体" }) MenuItem({ startIcon: $r('app.media.icon_underline'), content: "下划线" }) } } .radius(8) .backgroundColor(Color.White) .width(200) }}
// 在RichEditor中绑定自定义菜单RichEditor(this.options) .onReady(() => { this.controller.addTextSpan('长按触发自定义菜单', { style: { fontColor: Color.Black, fontSize: 16 } }) }) .bindSelectionMenu(RichEditorSpanType.TEXT, this.CustomMenu, ResponseType.LongPress) .width(300) .height(200)
复制代码
（2）光标和手柄颜色设置
通过 caretColor 属性可以设置输入框光标和手柄的颜色，提高视觉辨识度，使光标颜色与应用整体风格相协调。
RichEditor(this.options) .onReady(() => { this.controller.addTextSpan('设置了橙色光标和手柄的富文本', { style: { fontColor: Color.Black, fontSize: 16 } }) }) .caretColor(Color.Orange) .width(300) .height(100)
复制代码
（3）占位文本设置
通过 placeholder 属性可以设置无输入时的提示文本，引导用户正确操作。
RichEditor(this.options) .placeholder("请输入您的内容...", { fontColor: Color.Gray, font: { size: 14, family: "HarmonyOS Sans" } }) .width(300) .height(80)
复制代码
3、组件的事件监听与交互控制逻辑
RichEditor 提供了丰富的事件监听接口，实现更灵活的编辑交互逻辑。
（1）初始化完成事件
初始化回调函数，一般在这里进行数据的加载，或者组件文本的拼接等。
RichEditor(this.options) .onReady(() => { console.info('RichEditor初始化完成');
})
复制代码
（2）选择变化事件
内容选择区域或光标位置变化时触发，可用于实时更新工具栏状态。
RichEditor(this.options) .onSelectionChange((range) => { console.info(`选中范围变化: start=${range.start}, end=${range.end}`); // 根据选中范围更新工具栏按钮状态 this.updateToolbarState(range); })
复制代码
（3）粘贴事件
粘贴操作前触发，可用于自定义粘贴内容处理。
RichEditor(this.options) .onPaste((event) => { // 阻止默认粘贴行为 event.preventDefault(); // 自定义粘贴处理逻辑 this.handleCustomPaste(event); })
复制代码
4、内容操作与管理
通过控制器可以实现对编辑内容的程序化操作。
添加文本内容
// 添加普通文本this.controller.addTextSpan('新添加的文本内容', { style: { fontSize: 16, fontColor: Color.Blue }});
// 在指定位置添加文本this.controller.addTextSpan('在指定位置添加的文本', { style: { fontSize: 16, fontStyle: FontStyle.Italic }, offset: 10 // 在偏移量10的位置添加});
复制代码
5、添加图片内容
this.controller.addImageSpan($r('app.media.image'), { imageStyle: { size: [300, 200], // 图片大小 objectFit: ImageFit.Contain, // 图片缩放类型 verticalAlign: ImageSpanAlignment.MIDDLE // 垂直对齐方式 }});
复制代码
6、更新文本样式
// 更新指定范围的文本样式this.controller.updateSpanStyle({ start: 0, end: 5, textStyle: { fontWeight: 700, // 加粗 decoration: { type: TextDecorationType.Underline, // 下划线 color: Color.Red } }});
复制代码
三、DEMO 源码
DEMO 实现了一个富文本编辑器界面，支持字体样式设置、段落缩进控制、内容选中与编辑等功能，并通过自定义标记生成器实现列表缩进的可视化展示。
const canvasWidth = 1000;const canvasHeight = 100;const Indentation = 40;
// 段落缩进标记生成器类class LeadingMarginCreator { private settings: RenderingContextSettings = new RenderingContextSettings(true); // 渲染上下文设置 private offscreenCanvas: OffscreenCanvas = new OffscreenCanvas(canvasWidth, canvasHeight); // 离屏画布 private offContext: OffscreenCanvasRenderingContext2D = this.offscreenCanvas.getContext("2d", this.settings); // 离屏画布渲染上下文 public static instance: LeadingMarginCreator = new LeadingMarginCreator(); // 单例实例
// 获得字体字号级别（0-4级） public getFontSizeLevel(fontSize: number) { const fontScaled: number = Number(fontSize) / 16; // 字体缩放比例（相对于16px基准）
enum FontSizeScaleThreshold { SMALL = 0.9, // 小字体阈值 NORMAL = 1.1, // 正常字体阈值 LEVEL_1_LARGE = 1.2, // 1级大字体阈值 LEVEL_2_LARGE = 1.4, // 2级大字体阈值 LEVEL_3_LARGE = 1.5 // 3级大字体阈值 }
let fontSizeLevel: number = 1; // 初始字号级别为1
// 根据缩放比例确定字号级别 if (fontScaled < FontSizeScaleThreshold.SMALL) { fontSizeLevel = 0; } else if (fontScaled < FontSizeScaleThreshold.NORMAL) { fontSizeLevel = 1; } else if (fontScaled < FontSizeScaleThreshold.LEVEL_1_LARGE) { fontSizeLevel = 2; } else if (fontScaled < FontSizeScaleThreshold.LEVEL_2_LARGE) { fontSizeLevel = 3; } else if (fontScaled < FontSizeScaleThreshold.LEVEL_3_LARGE) { fontSizeLevel = 4; } else { fontSizeLevel = 1; }
return fontSizeLevel; }
// 获得缩进级别比例（根据缩进宽度计算比例） public getmarginLevel(width: number) { let marginlevel: number = 1; // 初始缩进比例为1 // 根据不同缩进宽度设置对应的比例 if (width === 40) { marginlevel = 2.0; } else if (width === 80) { marginlevel = 1.0; } else if (width === 120) { marginlevel = 2/3; } else if (width === 160) { marginlevel = 0.5; } else if (width === 200) { marginlevel = 0.4; } return marginlevel; }
// 生成文本标记（将文本转换为像素图） public genStrMark(fontSize: number, str: string): PixelMap { this.offContext = this.offscreenCanvas.getContext("2d", this.settings); // 重新获取渲染上下文 this.clearCanvas(); // 清空画布 this.offContext.font = fontSize + 'vp sans-serif'; // 设置字体样式 this.offContext.fillText(str + '.', 0, fontSize * 0.9); // 绘制文本（末尾加点以确保宽度） // 获取像素图（根据文本长度计算宽度） return this.offContext.getPixelMap(0, 0, fontSize * (str.length + 1) / 1.75, fontSize); }
// 生成方形标记（绘制正方形并转换为像素图） public genSquareMark(fontSize: number): PixelMap { this.offContext = this.offscreenCanvas.getContext("2d", this.settings); // 重新获取渲染上下文 this.clearCanvas(); // 清空画布 const coordinate = fontSize * (1 - 1 / 1.5) / 2; // 计算起始坐标 const sideLength = fontSize / 1.5; // 计算正方形边长 this.offContext.fillRect(coordinate, coordinate, sideLength, sideLength); // 绘制正方形 // 获取正方形像素图 return this.offContext.getPixelMap(0, 0, fontSize, fontSize); }
// 生成圆圈符号标记（根据缩进级别、字体大小等参数绘制圆形标记） public genCircleMark(fontSize: number, width: number, level?: number): PixelMap { const indentLevel = level ?? 1; // 缩进级别（默认1） const offsetLevel = [22, 28, 32, 34, 38]; // 不同字号级别的垂直偏移量 const fontSizeLevel = this.getFontSizeLevel(fontSize); // 获取字号级别 const marginlevel = this.getmarginLevel(width); // 获取缩进比例 const newCanvas = new OffscreenCanvas(canvasWidth, canvasHeight); // 创建新的离屏画布 const newOffContext: OffscreenCanvasRenderingContext2D = newCanvas.getContext("2d", this.settings); // 新画布的渲染上下文 const centerCoordinate = 50; // 圆心水平坐标基准 const radius = 10; // 圆半径基准 this.clearCanvas(); // 清空画布 // 绘制椭圆（根据参数计算位置和大小） newOffContext.ellipse( 100 * (indentLevel + 1) - centerCoordinate * marginlevel, // 圆心x坐标 offsetLevel[fontSizeLevel], // 圆心y坐标（根据字号级别） radius * marginlevel, // 水平半径（根据缩进比例） radius, // 垂直半径 0, 0, 2 * Math.PI // 椭圆参数（起始角度、结束角度） ); newOffContext.fillStyle = '66FF0000'; // 填充颜色（半透明红色） newOffContext.fill(); // 填充图形 // 获取圆形标记的像素图（根据缩进级别计算宽度） return newOffContext.getPixelMap(0, 0, 100 + 100 * indentLevel, 100); }
private clearCanvas() { this.offContext.clearRect(0, 0, canvasWidth, canvasHeight); // 清空画布 }}
@Entry@Componentstruct IndexPage3 { // 富文本控制器（用于操作编辑器内容和样式） controller: RichEditorController = new RichEditorController(); options: RichEditorOptions = { controller: this.controller }; // 富文本编辑器选项
// 缩进标记生成器实例（使用单例模式） private leadingMarkCreatorInstance = LeadingMarginCreator.instance; private fontNameRawFile: string = 'MiSans-Bold'; // 自定义字体名称
// 状态变量（用于界面交互和数据展示） @State fs: number = 30; // 字体大小 @State cl: number = Color.Black; // 字体颜色 @State start: number = -1; // 选中起始位置 @State end: number = -1; // 选中结束位置 @State message: string = "[-1, -1]"; // 选中范围提示信息 @State content: string = ""; // 选中内容 private leftMargin: Dimension = 0; // 左缩进量 private richEditorTextStyle: RichEditorTextStyle = {}; // 富文本样式
// 新增：光标颜色和选中背景色状态 @State cursorColor: Color|string = Color.Black; // 光标颜色 @State selectionColor: Color|string = Color.Gray; // 选中背景色
aboutToAppear() { // 注册自定义字体（应用启动时加载字体文件） this.getUIContext().getFont().registerFont({ familyName: 'MiSans-Bold', familySrc: '/font/MiSans-Bold.ttf' }); }
build() { Scroll() { Column() { // 颜色控制区域（切换界面主题颜色） Row() { Button("红色主题").onClick(() => { this.cursorColor = Color.Red; // 设置红色光标 this.selectionColor = "#FFCCCC"; // 设置红色选中背景 }).width("30%");
Button("绿色主题").onClick(() => { this.cursorColor = Color.Green; // 设置绿色光标 this.selectionColor = "#CCFFCC"; // 设置绿色选中背景 }).width("30%");
Button("蓝色主题").onClick(() => { this.cursorColor = Color.Blue; // 设置蓝色光标 this.selectionColor = "#CCCCFF"; // 设置蓝色选中背景 }).width("30%"); } .width("100%") .justifyContent(FlexAlign.SpaceBetween) .margin({ bottom: 10 });
// 选中范围和内容显示区域（展示当前选中的位置和内容） Column() { Text("selection range:").width("100%").fontSize(16); // 选中范围标题 Text() { Span(this.message) // 显示选中范围信息 }.width("100%").fontSize(16); Text("selection content:").width("100%").fontSize(16); // 选中内容标题 Text() { Span(this.content) // 显示选中内容 }.width("100%").fontSize(16); } .borderWidth(1) .borderColor(Color.Red) .width("100%") .padding(10) .margin({ bottom: 10 });
// 样式操作按钮区域（对选中内容进行样式修改） Row() { Button("加粗").onClick(() => { // 更新选中区域文本样式（设置为加粗） this.controller.updateSpanStyle({ start: this.start, end: this.end, textStyle: { fontWeight: FontWeight.Bolder } }); }).width("25%");
Button("获取选中内容").onClick(() => { this.content = ""; // 清空内容显示 // 获取选中范围内的所有文本片段 this.controller.getSpans({ start: this.start, end: this.end }).forEach(item => { if (typeof(item as RichEditorImageSpanResult)['imageStyle'] !== 'undefined') { // 处理图片片段 this.content += (item as RichEditorImageSpanResult).valueResourceStr + "\n"; } else { if (typeof(item as RichEditorTextSpanResult)['symbolSpanStyle'] !== 'undefined') { // 处理符号片段（显示字号） this.content += (item as RichEditorTextSpanResult).symbolSpanStyle?.fontSize + "\n"; } else { // 处理普通文本片段（显示文本内容） this.content += (item as RichEditorTextSpanResult).value + "\n"; } } }); }).width("25%");
Button("删除选中内容").onClick(() => { // 删除选中区域内容 this.controller.deleteSpans({ start: this.start, end: this.end }); this.start = -1; // 重置选中起始位置 this.end = -1; // 重置选中结束位置 this.message = "[" + this.start + ", " + this.end + "]"; // 更新选中范围提示 }).width("25%");
Button("设置样式1").onClick(() => { // 设置输入时的默认样式 this.controller.setTypingStyle({ fontWeight: 'medium', // 中等粗细 fontFamily: this.fontNameRawFile, // 自定义字体 fontColor: Color.Blue, // 蓝色 fontSize: 50, // 字号50 fontStyle: FontStyle.Italic, // 斜体 decoration: { type: TextDecorationType.Underline, color: Color.Green } // 绿色下划线 }); }).width("25%"); } .borderWidth(1) .borderColor(Color.Red) .width("100%") .height("10%") .margin({ bottom: 10 });
// 富文本编辑器区域（核心编辑界面） Column() { RichEditor(this.options) .onReady(() => { // 编辑器准备就绪时初始化内容 this.controller.addTextSpan("0123456789\n", { style: { fontWeight: 'medium', // 中等粗细 fontFamily: this.fontNameRawFile, // 自定义字体 fontColor: Color.Red, // 红色 fontSize: 50, // 字号50 fontStyle: FontStyle.Italic, // 斜体 decoration: { type: TextDecorationType.Underline, color: Color.Green } // 绿色下划线 } });
this.controller.addTextSpan("abcdefg", { style: { fontWeight: FontWeight.Lighter, // 更细 fontFamily: 'HarmonyOS Sans', // HarmonyOS默认字体 fontColor: 'rgba(0,128,0,0.5)', // 半透明绿色 fontSize: 30, // 字号30 fontStyle: FontStyle.Normal, // 正常样式 decoration: { type: TextDecorationType.Overline, color: 'rgba(169, 26, 246, 0.50)' } // 半透明紫色上划线 } }); }) .onSelect((value: RichEditorSelection) => { // 选中事件回调（更新选中范围状态） this.start = value.selection[0]; this.end = value.selection[1]; this.message = "[" + this.start + ", " + this.end + "]"; }) .caretColor(this.cursorColor) // 设置光标颜色（来自状态变量） .selectedBackgroundColor(this.selectionColor) // 设置选中背景色（来自状态变量） .borderWidth(1) .borderColor(Color.Green) .width("100%") .height("30%") .margin({ bottom: 10 }); } .borderWidth(1) .borderColor(Color.Red) .width("100%") .padding(10);
// 缩进操作按钮区域（控制段落缩进） Column() { Row({ space: 5 }) { Button("向右列表缩进").onClick(() => { let margin = Number(this.leftMargin); // 当前左缩进量 if (margin < 200) { margin += Indentation; // 增加缩进量（40像素） this.leftMargin = margin; } // 更新段落样式（设置带标记的缩进） this.controller.updateParagraphStyle({ start: -10, end: -10, style: { leadingMargin: { pixelMap: this.leadingMarkCreatorInstance.genCircleMark(100, margin, 1), // 圆形缩进标记 size: [margin, 40] // 缩进标记大小 } } }); }).width("48%");
Button("向左列表缩进").onClick(() => { let margin = Number(this.leftMargin); // 当前左缩进量 if (margin > 0) { margin -= Indentation; // 减少缩进量（40像素） this.leftMargin = margin; } // 更新段落样式（设置带标记的缩进） this.controller.updateParagraphStyle({ start: -10, end: -10, style: { leadingMargin: { pixelMap: this.leadingMarkCreatorInstance.genCircleMark(100, margin, 1), // 圆形缩进标记 size: [margin, 40] // 缩进标记大小 } } }); }).width("48%"); } .margin({ bottom: 10 });
Row({ space: 5 }) { Button("向右空白缩进").onClick(() => { let margin = Number(this.leftMargin); // 当前左缩进量 if (margin < 200) { margin += Indentation; // 增加缩进量（40像素） this.leftMargin = margin; } // 更新段落样式（设置纯空白缩进） this.controller.updateParagraphStyle({ start: -10, end: -10, style: { leadingMargin: margin } // 仅设置缩进宽度 }); }).width("48%");
Button("向左空白缩进").onClick(() => { let margin = Number(this.leftMargin); // 当前左缩进量 if (margin > 0) { margin -= Indentation; // 减少缩进量（40像素） this.leftMargin = margin; } // 更新段落样式（设置纯空白缩进） this.controller.updateParagraphStyle({ start: -10, end: -10, style: { leadingMargin: margin } // 仅设置缩进宽度 }); }).width("48%"); } .margin({ bottom: 10 });
Button("获取当前样式").onClick(() => { this.richEditorTextStyle = this.controller.getTypingStyle(); console.info("RichEditor getTypingStyle:" + JSON.stringify(this.richEditorTextStyle)); }) .width("100%") .margin({ bottom: 10 }); } .width("100%") .padding(10); } .width("100%") .padding(10); } }}
复制代码
划线
评论
复制
发布于: 刚刚阅读数: 3
版权声明: 本文为 InfoQ 作者【GeorgeGcs】的原创文章。
原文链接:【http://xie.infoq.cn/article/9bba7e5917bf31e06ecd98a12】。文章转载请联系作者。
GeorgeGcs
关注
路漫漫其修远兮，吾将上下而求索。 2024-12-24 加入
鸿蒙创作先锋，华为HDE专家，鸿蒙讲师，作者。 目前任职鸿蒙应用架构师。历经腾讯，宝马，研究所，金融。 待过私企，外企，央企。 深耕大应用开发领域十年。 OpenHarmony，HarmonyOS，Flutter，H5，Android，IOS。
评论