一、什麼是 RichEditor？

RichEditor 是 HarmonyOS ArkTS 提供的專用富文本編輯組件，它：

• 支持圖文混排（文字 + 圖片 + 風格樣式）
• 允許用户對輸入內容進行交互式編輯
• 提供事件監聽和內容管理能力

它比 TextInput 更強：不僅僅是輸入純文本，更像是一個可視化的內容編輯區域，用於創建結構化/格式化內容。

二、RichEditor 適合的典型場景

與 TextInput（只能輸入“純文本”）對比，RichEditor 適合可視化富文本場景。

三、核心要素組成

1. RichEditor 組件

這是主控的 UI 區域，你可以直接渲染在頁面裏：

RichEditor(this.options)

其中 this.options 是一個配置對象（官方文檔稱為 RichEditorOptions），用於提供控制器等信息來初始化組件。

2. RichEditorController

它是你操作富文本編輯器內容的“引擎”。常用於：

• 插入文本或圖像
• 控制光標位置
• 獲取當前富文本內容
• 動態修改內容樣式

controller: RichEditorController = new RichEditorController();
options: RichEditorOptions = { controller: this.controller };

在創建 RichEditor 時，把它傳給編輯器實例，後續通過它來操控編輯器。DEV Community

四、基礎使用示例（一步步寫起來）

下面是一個完整的“可運行版”結構示例，展示如何在 ArkTS 頁面裏渲染並使用 RichEditor：

@Component
struct RichEditorDemo {
  controller: RichEditorController = new RichEditorController();
  options = { controller: this.controller };

  build() {
    Column({ space: 12 }) {
      Text('富文本編輯器示例').fontSize(18).fontWeight(FontWeight.Bold);

      RichEditor(this.options)
        .width('100%')
        .height(280)
        .backgroundColor(0xFFFFFFFF)
        .onReady(() => {
          // 編輯器準備好後可以插入初始內容
          this.controller.addTextSpan('歡迎使用富文本編輯器！')
        })
        .onCopy((evt) => {
          // 用户複製事件
          promptAction.showToast({ message: '內容已複製', duration: 1200 })
        });
    }
    .padding(12)
  }
}

功能細節：

• .onReady(...)：編輯器初始化完畢回調
• .onCopy(...)：用户執行文字複製時觸發回調
• controller.addTextSpan(...)：在打開編輯器後動態追加內容（例如引導文本）DEV Community

五、常見 API 與用法

下面是開發過程中你最有可能用到的一些能力：

1. 初始化編輯器內容

當頁面加載時，你可以在 onReady 回調裏通過 controller 設置初始文本、默認樣式等：

.onReady(() => {
  this.controller.addTextSpan('初始內容');
})

這比把字符串直接塞進屬性更靈活，因為它是在編輯器渲染後執行

2. 事件監聽

富文本編輯器通常有不少事件可以監聽，例如：

• onReady：編輯器初始化完成
• onCopy：用户複製選中內容
• onTextChange（如果支持）：文本內容變化時觸發

上面例子裏我們監聽了 onCopy 並彈出提示，這在“用户選中文字做動作”場景特有。3. 插入圖像 / 圖片

RichEditor 一般支持插入富文本圖像。
在一些社區文章和示例裏可以看到這類能力（插入圖片、圖標等元素的位置及樣式需要通過 Controller 提供的接口操作）

示例思路（偽代碼）：

this.controller.insertImage('https://example.com/img.jpg', { width: 200, height: 120 });

上面代碼在光標位置插入圖片（具體 API 名稱/參數請從官方 API 參考查閲對應字段）。

4. 加樣式（粗體/斜體）

通過 Controller 或 Option/Dom 操作，可以為特定段落應用樣式，如粗體、斜體、鏈接等。這類樣式操作通常結合 Span 風格控制（某些社區資源提到 Span 在富文本里同樣能串聯使用）。

六、實戰常見技巧與構建思路

1) 插入初始提示語

在富文本評論/編輯器頁面裏，加入“請輸入內容…”的啓動提示通常比不寫更友好：

.onReady(() => this.controller.addTextSpan('在這裏輸入你的內容...'));

2) 結合按鈕觸發樣式

在 UI 上放幾個按鈕，比如“粗體 / 插入圖片 / 加鏈接”，通過 Controller 操作實現：

Button('插入圖片').onClick(() => {
  this.controller.insertImage(url, { width: 100, height: 100 });
});

這種寫法類似富文本編輯器工具欄，很適合內容創作場景。

3) 獲取當前內容並提交

在用户點擊“提交”按鈕時獲取編輯器內容，然後存回服務器：

const content = this.controller.getContent(); // 得到富文本數據
sendToServer(content);

不同版本的 API 名稱可能略有差異，但思路是“Controller 拿當前實際內容”。

七、注意事項和坑（實戰積累）

1) 性能問題

富文本編輯器在處理大量圖文混排內容時可能較重（尤其是圖片 + 嵌套內容）。因此：

• 在長列表中反覆創建 RichEditor 會有性能損耗
• 儘量避免在短時間內高頻創建/銷燬組件

如果遇到性能瓶頸，可以考慮在背景線程做內容處理([turn0search13])。

2) 內容高度自適應

RichEditor 在某些場景下不會自動根據內容高度變化，要通過容器的佈局約束適配高度，否則可能出現滾動條/裁剪。

3) 版本差異性

官方文檔的 API 可能會隨版本微調，你在使用 controller 或 options 時，要參考對應 SDK 版本的 API 説明（部分回調、方法名、參數結構等可能會變化）。

八、總結（像人寫的結論）

• RichEditor 是 ArkTS 提供的原生富文本編輯組件，適用於用户創作和圖文混排場景。
• 它由 RichEditor + RichEditorController + RichEditorOptions 共同協作實現，可動態插入內容、監聽事件等。
• 典型用法包括初始化內容、事件監聽、插入圖像、樣式控制等。
• 實際開發中還要注意性能、佈局自適應和版本 API 的細節。