RichEditor 嵌入本地图片实现与适配
【摘要】 前言富文本笔记只有文字会比较单调,插入图片是刚需功能。在 HarmonyOS NEXT 里,RichEditor 支持图片节点渲染,但它不会自动帮我们处理图片选择、权限、图片路径转换、大图缩放、内存回收这些逻辑。本文实现:相册选择图片、权限申请、转为沙盒路径、插入富文本、图片点击预览,同时解决常见的图片变形、路径失效问题。目标效果:在编辑页点击插入图片按钮,拉起相册选择图片;图片成功插入富...
前言
富文本笔记只有文字会比较单调,插入图片是刚需功能。在 HarmonyOS NEXT 里,RichEditor 支持图片节点渲染,但它不会自动帮我们处理图片选择、权限、图片路径转换、大图缩放、内存回收这些逻辑。本文实现:相册选择图片、权限申请、转为沙盒路径、插入富文本、图片点击预览,同时解决常见的图片变形、路径失效问题。
目标效果:在编辑页点击插入图片按钮,拉起相册选择图片;图片成功插入富文本;点击图片可全屏预览;应用卸载后图片跟随清理。
一、方案选型
| 方案 | 说明 | 适用场景 |
|---|---|---|
| 直接使用相册原路径 | 受相册权限管控,重启后大概率无法访问 | 不推荐 |
复制到应用沙盒 cache 目录 |
私有目录,权限稳定,适合临时图片 | 编辑草稿图片 |
复制到 files 持久目录 |
长期保存,笔记入库后绑定图片 | 正式笔记配图 |
笔记场景推荐:选中图片后,先拷贝到应用沙盒目录,再把沙盒路径传给 RichEditor,避免跨目录访问权限问题。
二、依赖导入与权限说明
需要的模块:
import picker from '@ohos.file.picker';
import fs from '@ohos.file.fs';
import common from '@ohos.app.ability.common';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
模块权限说明(module.json5)
"requestPermissions": [
{
"name": "ohos.permission.READ_IMAGEVIDEO"
}
]
说明:HarmonyOS NEXT 使用 PhotoPicker 拉起相册,推荐使用系统照片选择器,不需要完整文件访问权限,用户只授权选中的图片,隐私性更好。
三、封装图片选择 + 沙盒拷贝工具
export class ImageInsertUtil {
private static ctx: common.UIAbilityContext;
static setContext(context: common.UIAbilityContext) {
this.ctx = context;
}
/**
* 拉起照片选择器,返回沙盒内的图片绝对路径
*/
static async pickImageToSandbox(): Promise<string | null> {
try {
const photoPicker = new picker.PhotoViewPicker();
const result = await photoPicker.select({
MIMEType: picker.PhotoViewMIMETypes.IMAGE_TYPE,
maxSelectNumber: 1
});
if (!result.photoUris.length) return null;
const srcUri = result.photoUris[0];
// 目标沙盒路径,cache目录,适合草稿图片
const cacheDir = this.ctx.cacheDir;
const fileName = `img_${Date.now()}.jpg`;
const destPath = `${cacheDir}/${fileName}`;
// 复制文件到沙盒
await fs.copyFile(srcUri, destPath);
return destPath;
} catch (err) {
const e = err as BusinessError;
console.error(`图片选择拷贝失败: ${e.code}, ${e.message}`);
return null;
}
}
}
四、RichEditor 插入图片核心代码
RichEditor 通过 addImage 接口插入图片节点,可以设置初始宽高。
@Entry
@Component
struct NoteEditPage {
@State richContent: string = '';
private richEditorController: RichEditorController = new RichEditorController();
aboutToAppear() {
ImageInsertUtil.setContext(getContext(this) as common.UIAbilityContext);
}
// 插入图片按钮点击事件
async insertImage() {
const sandboxPath = await ImageInsertUtil.pickImageToSandbox();
if (!sandboxPath) return;
// 在光标位置插入图片,设置宽高
this.richEditorController.addImage({
value: sandboxPath,
imageWidth: 300,
imageHeight: 200
});
}
build() {
Column() {
Row() {
Button("插入图片")
.onClick(() => this.insertImage())
}
RichEditor(this.richEditorController)
.onChange((val: string) => {
this.richContent = val;
})
.imageOnClick((imgSrc: string) => {
// 点击图片,跳转到预览页面,传递图片路径
router.pushUrl({
url: 'pages/ImagePreviewPage',
params: { imgUrl: imgSrc }
})
})
}
.width('100%')
.height('100%')
.padding(12)
}
}
五、图片预览页面简单实现 ImagePreviewPage.ets
@Entry
@Component
struct ImagePreviewPage {
@State imgUrl: string = router.getParams()?.['imgUrl'] as string;
build() {
Column() {
Image(this.imgUrl)
.objectFit(ImageFit.Contain)
.width('100%')
.layoutWeight(1)
Button("关闭")
.margin(16)
.onClick(() => router.back())
}
.width('100%')
.height('100%')
.backgroundColor('#000000')
}
}
六、关键踩坑点
- 不能直接把 photoPicker 的 uri 传给 RichEditor
选中的 uri 是临时授权 uri,页面重建、应用重启之后权限失效,图片直接空白,必须复制到应用私有沙盒。 - cache 目录图片会被系统清理
cache 目录是缓存目录,系统存储空间不足时自动删除里面的文件。如果是正式保存的笔记配图,需要拷贝到this.ctx.filesDir持久目录,并且把图片路径存入RDB和笔记绑定。 - 大图内存溢出
相册原图分辨率很高,直接加载容易OOM。可以增加一步:使用 image 模块压缩图片后再保存到沙盒。 - 富文本序列化存储
RichEditor 的 onChange 返回的字符串会包含图片路径,存入数据库时一并保存;打开笔记时,再把字符串 setValue 回填到编辑器。 - 图片删除逻辑
用户在编辑器里删除图片节点时,需要解析富文本字符串,拿到对应的沙盒路径,调用 fs.unlink 删除文件,避免沙盒内垃圾图片堆积。
七、进阶优化方向
- 图片压缩:选择图片后先压缩,控制长边不超过1080px,减少存储占用和加载耗时;
- 多图批量选择:修改 PhotoPicker 的 maxSelectNumber,循环批量插入;
- 图片拖拽调整大小:监听图片手势,动态修改图片宽高;
- 图片上传端云:同步笔记时,上传图片到对象存储,沙盒路径替换成远端URL;
- 垃圾图片巡检:打开笔记页的时候,异步扫描沙盒图片,删除没有被任何笔记引用的孤立图片。
结语
RichEditor 的图片能力本身基础能力齐全,但配套的权限、文件管理、生命周期清理都需要上层业务补齐。这套方案可以直接嵌入前面的笔记草稿、RDB存储流程,形成「文字+图片」完整富文本笔记链路,是笔记类应用非常核心的一环。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)