fuchsia.input.virtualKeyboard

已新增：7

專家

控制器

定義於「fuchsia.input.virtualkeyboard/virtual_keyboard.fidl」

提供控制虛擬鍵盤的功能。

抽像模型

該虛擬鍵盤一次最多只能「擁有」一個控制器。擁有者是聚焦於相關 View 的控制器。如果沒有這類控制器，虛擬鍵盤為未擁有 (並隱藏)。

只有所屬控制器可以修改虛擬鍵盤設定。當專屬控制器失去焦點時，這個通訊協定的實作程式會自動關閉虛擬鍵盤。

角色

這個通訊協定通常如下：

  • 由控制鍵盤瀏覽權限的平台元件實作。
  • 由應用程式執行階段使用。例如 Flutter、Chromium。

相關通訊協定

  • 此通訊協定不會提供虛擬鍵盤的輸出內容存取權。為此，請參閱下列其中一個通訊協定：
    • fuchsia.ui.input3.Keyboard (適用於按鍵動作)
    • fuchsia.ui.input.InputMethodEditor (用於文字編輯)
  • 這個通訊協定通常用於虛擬鍵盤的消費者/使用者。鍵盤的實作者/擁有者應使用下方的 Manager。

實作者註意事項

理想情況下，只有在相關聯的 View 有焦點時，才能呼叫這個通訊協定的方法。不過，這個通訊協定的實作者和取用端都可獨立接收焦點變更通知，不保證 Controller 實作者能夠在 Controller 取用端之前取得焦點變更。

因此，如果在非聚焦於 View 時禁止呼叫，可能會因為上述競爭狀況而遭到惡意拒絕有效呼叫的風險。而是應依照個別方法的註解所述進行緩衝區要求。

要求隱藏

要求隱藏鍵盤。

  • 如果受呼叫者確定這個控制器的 View 聚焦，呼叫端會立即套用變更。
  • 如果受呼叫者判定這個控制器的 View「未」聚焦：
    • 如果有待處理的 RequestShow()，呼叫端會取消該要求。
    • 否則，呼叫不會有任何作用。
  • 對這個方法的呼叫具有冪等性。

要求

<空白>

要求顯示

要求顯示鍵盤。

  • 如果受呼叫者確定這個控制器的 View 聚焦，呼叫端會立即套用變更。
  • 如果受呼叫端判定這個控制器的 View 未聚焦，則呼叫端會在 View 重新聚焦時套用變更。不過，呼叫 RequestHide() 會使這類待處理的要求失效。
  • 對這個方法的呼叫具有冪等性。

要求

<空白>

設定文字類型

要求變更虛擬鍵盤的文字類型。

  • 如果受呼叫者確定這個控制器的 View 聚焦，呼叫端會立即套用變更。
  • 如果受呼叫端判定這個控制器的 View 未聚焦，則受呼叫端會在 View 重新聚焦時套用變更。
  • 如果呼叫端在 View 重新聚焦前收到多次呼叫，則受呼叫端將套用最新呼叫的值。

要求

名稱類型
text_type TextType

手錶瀏覽權限

等待瀏覽權限變更，然後回報新的值。

  • 如果呼叫端收到此控制器的 RequestShow() 呼叫，則此控制器尚未要求顯示鍵盤時，會傳回 true。

    • 這「可能」會發生在鍵盤顯示在畫面上之前。
    • 這個情況可能在聚焦於這個控制器的 View 之前發生。

  • 當呼叫端決定隱藏這個控制器要求的鍵盤時，系統會傳回 false。

    • 這可能是因呼叫 RequestHide()，或是 View 失去焦點時間接導致。
    • 鍵盤仍顯示在螢幕上時，系統「可」傳回此函式。

  • 第一次呼叫會立即傳回...

    • true (如果呼叫端根據來自此控制器的要求而決定顯示鍵盤 (這並不保證螢幕會顯示鍵盤)
    • false (否則)

要求

<空白>

回應

名稱類型
is_visible bool

控制器建立者

定義於「fuchsia.input.virtualkeyboard/virtual_keyboard.fidl」

提供取得 Controller 的功能。

這個通訊協定是透過 ViewRef 將 Controller 繫結至 View。繫結可讓鍵盤子系統運用對 View 焦點的知識，限制 Controller 會影響虛擬鍵盤設定的時機。

請注意，Controller 本身允許設定虛擬鍵盤的呈現方式 (瀏覽權限和版面配置)，但不適用於文字事件。如需詳細資訊，請參閱 Controller 說明文件。

角色

這個通訊協定通常如下：

  • 由控制 UI 政策的平台元件實作。
  • 由應用程式執行階段使用。例如 Flutter、Chromium。

建立

要求 server_end:Controller 管道另一端的 Controller 與 view_ref 所參照的 View 建立關聯。

呼叫 Controller.RequestShow() 時，Controller 實作器會嘗試提供針對 text_type 項目最佳化的鍵盤 (除非呼叫 Controller.SetType() 覆寫類型)。

ControllerCreator 的實作者應利用相關 View 的焦點狀態知識，將存取權控管套用至在 Controller 上發出的呼叫。詳情請參閱 Controller 方法的說明文件。

ControllerCreator 的消費者可以自由中斷創作者的連線，而不影響控管者。

要求

名稱類型
view_ref fuchsia.ui.views/ViewRef
text_type TextType
controller_request server_end<Controller>

經理

定義於「fuchsia.input.virtualkeyboard/virtual_keyboard.fidl」

啟用虛擬鍵盤 UI，將狀態與平台保持同步。

角色

這個通訊協定通常如下：

  • 由控制 UI 政策的平台元件實作。
  • 由為文字輸入提供 GUI 預設用途的元件消耗。

通知

通知呼叫端虛擬鍵盤的顯示設定已變更，以及觸發變更的原因。

呼叫端應先等待結果，然後再叫用此方法，以免呼叫端超載。

要求

名稱類型
is_visible bool
reason VisibilityChangeReason

回應

<空白>

手錶類型與瀏覽權限

等待預期的 text_type 或瀏覽權限變更，然後回報新值。為回應狀態變更，呼叫端應設定要求的類型和顯示設定，然後呼叫 Notify 來通知平台異動。

第一個呼叫會立即傳回目前預期的 text_type 和瀏覽權限。

如果 text_type 不受支援，呼叫端應實作備用機制，並盡可能提供最多的必要鍵。

要求

<空白>

回應

名稱類型
text_type TextType
is_visible bool

表情符號

TextType 彈性

類型：uint32

定義於「fuchsia.input.virtualkeyboard/virtual_keyboard.fidl」

說明虛擬鍵盤預期可輸入的文字類型。

名稱值說明
0

文字可能會同時包含字母和數字字元。這是列舉的預設值 (零值)，因此未初始化的列舉執行個體可為鍵盤使用者提供最靈活的輸入功能。
1

這段文字可能只包含數字。
2

文字可能包含數字字元，以及與電話號碼搭配使用的標點符號 (例如「*」、「#」)。

VisibilityChangeReason 彈性

類型：uint32

定義於「fuchsia.input.virtualkeyboard/virtual_keyboard.fidl」

說明在轉譯供使用者的介面中加入或移除虛擬鍵盤的原因。

名稱值說明
1

由於程式輔助要求，瀏覽權限已變更。例如，GUI 元件對 WatchTypeAndVisibility() 的呼叫會傳回 is_visible 的新值。
2

由於使用者與 GUI 元件互動，瀏覽權限已變更。例如使用者輕觸關閉按鈕。