自訂文字編輯器

自訂文字編輯器是下列項目的檢視畫面 EditText 元件或 WebView 文字小工具，但 不過只要實作 onCreateInputConnection() 回呼，系統會在聚焦檢視畫面且系統要求 InputConnection 以及檢視畫面

對 onCheckIsTextEditor()敬上 自訂文字編輯器應傳回 true。

支援在自訂文字編輯器中使用觸控筆手寫

Android 14 (API 級別 34) 以上版本支援標準 Android 中的觸控筆輸入功能 預設文字輸入元件 (請參閱「以觸控筆輸入文字 欄位)。 不過，自訂文字輸入欄位 (或編輯器) 需要額外開發。

如要建立自訂文字編輯器，請執行下列步驟：

1. 啟用手寫輸入功能
2. 宣告手寫支援
3. 支援手寫手勢 (選取、刪除、插入等)
4. 將遊標位置和其他位置資料提供給輸入法編輯器
5. 顯示觸控筆手寫懸停圖示

啟用手寫輸入功能

如果檢視區塊僅由單一文字編輯器組成，View 系統可以 自動為檢視畫面啟動觸控筆手寫。否則，檢視區塊必須 實作自己的手寫啟動邏輯

自動啟動手寫功能

如果檢視畫面只顯示一個文字編輯器，且沒有其他內容，該檢視畫面可選擇 藉由呼叫 setAutoHandwritingEnabled(true)。

啟用自動手寫功能後，以觸控筆在檢視畫面中的任何位置執行觸控筆動作 系統會自動啟動手寫界限。輸入法 編輯者 (IME) 收到 觸控筆動作事件，並提交系統辨識的文字。

圖 1. 在 EditText 欄位邊界內手寫。

自訂手寫內容

如果檢視區塊包含單一文字，還包含多個文字編輯器或內容 編輯器時，檢視畫面必須實作自己的手寫啟動邏輯，如下所示：

1. 如要停用檢視系統的自動手寫輸入功能，請撥號至 setAutoHandwritingEnabled(false)。

2. 追蹤在檢視畫面中顯示的所有文字編輯器。

3. 監控以下檢視畫面收到的動作事件： dispatchTouchEvent()。

   • 當文字編輯器的手寫輸入出現觸控筆動作時， 將焦點移至文字編輯器 (如果尚未聚焦)。

   • 如果編輯器尚未聚焦，請重新啟動編輯器的 IME，並使用新的 呼叫 InputMethodManager#restartInput()。

   • 如要啟動觸控筆手寫工作階段，請呼叫 InputMethodManager#startStylusHandwriting()。

，瞭解如何調查及移除這項存取權。

注意： 根據預設，EditText 的手寫邊界包含 垂直邊框間距和水平邊框間距 10 dp (如圖 1 所示)。匹配 自訂編輯器檢視畫面中的邊界。

如果在可捲動的檢視畫面中使用文字編輯器，該文字編輯器內的觸控筆動作 請把編輯器的手寫邊界視為手寫輸入，而非捲動畫面。使用 ViewParent#requestDisallowInterceptTouchEvent()敬上 防止可捲動的祖系檢視畫面攔截文字的觸控事件 編輯。

API 詳細資料

• MotionEvent#getToolType() — 指出 MotionEvent 是否來自觸控筆，在此情況下 傳回值 TOOL_TYPE_STYLUS 或 TOOL_TYPE_ERASER。

  注意： 使用者按下觸控筆上的橡皮擦按鈕，然後開始動作時 如果使用觸控筆，動作事件傳回類型為 TOOL_TYPE_ERASER。起始 讓輸入法編輯器決定如何辨識觸控筆 動作

• InputMethodManager#isStylusHandwritingAvailable() - 指出輸入法編輯器是否支援觸控筆手寫。呼叫此項目 方法，每次呼叫 InputMethodManager#startStylusHandwriting() 因為手寫方式可能有所變更。

• InputMethodManager#startStylusHandwriting() - 讓輸入法編輯器進入手寫模式。一個 ACTION_CANCEL敬上 動作事件會分派給應用程式，以取消目前的手勢。觸控筆 系統不再將動作事件分派給應用程式。

  目前派出的手勢的觸控筆動作事件 應用程式會轉交給 IME。必須提供 IME 才能顯示觸控筆墨水 輸入法編輯器接收所有後續 MotionEvent 物件。 IME 使用 InputConnection敬上 相互整合

  如果輸入法編輯器無法進入手寫模式，此方法呼叫會是免人工管理。

  注意： 您只能在startStylusHandwriting() 檢視引數含有焦點和有效的輸入連線。窗戶 包含檢視畫面的項目也必須聚焦。

宣告手寫支援

填寫 EditorInfo 引數 / View#onCreateInputConnection(EditorInfo) 通話 setStylusHandwritingEnabled() 可告知輸入法編輯器，文字編輯器支援手寫功能。 使用以下字詞宣告支援的手勢： setSupportedHandwritingGestures()敬上 和 setSupportedHandwritingGesturePreviews()。

支援手寫手勢

IME 可支援多種手寫手勢，例如圈選要選取的文字 或在文字上塗鴉即可刪除。

圖 2. 畫圈選取文字。

，瞭解如何調查及移除這項存取權。

，瞭解如何調查及移除這項存取權。

圖 3.劃掉即可刪除文字。

自訂編輯器 InputConnection#performHandwritingGesture()敬上 和 InputConnection#previewHandwritingGesture()。 支援不同的 HandwritingGesture 例如 SelectGesture、 DeleteGesture和 InsertGesture。

填入 EditorInfo 引數時，宣告支援的手寫手勢 的 View#onCreateInputConnection(EditorInfo) (請參閱宣告手寫字) 支援區段)。

API 詳細資料

• InputConnection#performHandwritingGesture(HandwritingGesture, Executor, IntConsumer) - 實作手勢。HandwritingGesture 引數包含 位置資訊，可用來決定 做出該手勢舉例來說，SelectGesture 提供 RectF 物件，該物件會 會指定所選的文字範圍，而 InsertGesture 會提供 PointF 物件 指定要插入文字的位置偏移量。

  使用 Executor 和 IntConsumer 參數 傳回作業結果當執行程式和 此時，請使用執行程式呼叫 IntConsumer#accept()、 例如：

  
  executor.execute { consumer.accept(HANDWRITING_GESTURE_RESULT_SUCCESS) }
  
  

• HandwritingGesture#getFallbackText() - 如果沒有，提供輸入法編輯器在遊標位置修訂的備用文字 適用的文字會顯示在手寫手勢區域下方。

  有時 IME 無法判斷觸控筆手勢 用於執行手勢作業或手寫文字。自訂文字 編輯者負責確定使用者的意圖 使用者做出表情時應採取的適當動作 (視情境而定)。

  舉例來說，如果 IME 無法判斷使用者是否原本想繪製 向下插入 ⋁ 執行插入空格手勢或手寫 字母「v」IME 可以傳送含有「v」備用文字的 InsertGesture。

  編輯器應先嘗試執行插入空格手勢。如果 無法執行手勢 (例如該地點沒有文字 編輯器會改回插入「v」在遊標處 位置。

• InputConnection#previewHandwritingGesture(PreviewableHandwritingGesture, CancellationSignal) - 預覽使用中的手勢。舉例來說，當使用者開始繪圖 圈選輸入文字的即時預覽畫面 並在使用者繼續繪圖時持續更新。僅限特定程度 可預覽的手勢類型 (詳情請參閱 PreviewableHandwritingGesture)。

  輸入法編輯器可以使用 CancellationSignal 參數取消 預覽。如果其他事件幹擾了預覽作業 (例如文字發生變更， 以程式輔助方式或新的 InputConnection 指令時)，自訂編輯器 可以取消預覽

  預覽手勢僅供顯示，且不應變更編輯器的 時間。舉例來說，SelectGesture 預覽畫面會隱藏編輯器目前的 選取範圍並醒目顯示手勢預覽範圍。但一旦 已取消預覽，編輯器會還原先前的選取範圍。

提供遊標位置和其他定位資料

在手寫模式中，輸入法編輯器可以要求取得遊標位置和其他定位資料 使用 InputConnection#requestCursorUpdates()。 自訂編輯器以呼叫 InputMethodManager#updateCursorAnchorInfo(View, CursorAnchorInfo)。 您在 CursorAnchorInfo敬上 與觸控筆手寫有關的資訊如下： CursorAnchorInfo.Builder。 方法：

• setInsertionMarkerLocation() — 設定遊標的位置。IME 會根據這個值建立動畫 手寫輸入遊標位置。
• setEditorBoundsInfo() — 設定編輯器的邊界和手寫邊界。輸入法編輯器會使用 以便在螢幕上放置輸入法編輯器的手寫工具列。
• addVisibleLineBounds() —設定所有可見 (或部分顯示) 文字行的邊界。 編輯文件IME 使用線條邊界提高辨識準確度 手寫手勢。
• setTextAppearanceInfo() — 使用從文字擷取的資訊來設定文字外觀 輸入欄位輸入法編輯器會根據這項資訊設定手寫墨水的樣式。

顯示觸控筆手寫懸停圖示

觸控筆懸停在觸控筆懸停時，顯示觸控筆懸停圖示 自訂文字編輯器和所選輸入法編輯器支援的手寫邊界 觸控筆手寫 (InputMethodManager#isStylusHandwritingAvailable())。

覆寫 View#onResolvePointerIcon()敬上 取得觸控筆手寫功能的懸停圖示在覆寫值中，呼叫 PointerIcon.getSystemIcon(context, PointerIcon.TYPE_HANDWRITING)敬上 存取系統的觸控筆手寫懸停圖示。

其他資源

• 文字欄位中的觸控筆輸入內容