fuchsia.input.virtualKeyboard

新增：7

PROTOCOLS

控場

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

可控制虛擬鍵盤。

抽象模型

虛擬鍵盤一次最多只能由一個遙控器「擁有」。擁有者是與所選 View 相關聯的控制者。如果沒有這類控制器，虛擬鍵盤就會沒有擁有者 (並隱藏)。

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

角色

這個通訊協定通常會： * 由控制鍵盤顯示狀態的平台元件實作。* 供應用程式執行階段使用。例如 Flutter、Chromium。

相關通訊協定

* 這個通訊協定無法存取虛擬鍵盤的輸出內容。如需相關資訊，請參閱下列其中一個通訊協定： * fuchsia.ui.input3.Keyboard (適用於按鍵) * fuchsia.ui.input.InputMethodEditor (適用於文字編輯) * 這個通訊協定適用於虛擬鍵盤的消費者/使用者。 鍵盤實作人員/擁有者應使用下方的 Manager。

實作者注意事項

理想情況下，只有在相關聯的 View 具有焦點時，才允許呼叫這個通訊協定的方法。不過，這個通訊協定的實作方和取用方會各自收到焦點變更通知，無法保證實作方會在取用方之前得知焦點變更。ControllerController

因此，如果 View 未處於焦點狀態，禁止呼叫可能會因上述競爭狀況，而錯誤地拒絕有效呼叫。實作方式應緩衝處理要求，如各方法註解所述。

RequestHide

要求隱藏鍵盤。

  • 如果受呼叫者判斷這個 Controller 的 View 為焦點，受呼叫者會立即套用變更。
  • 如果被呼叫者判斷這個控制器的 View「未聚焦」：
    • 如有待處理的 RequestShow()，接聽者會取消該要求。
    • 否則呼叫不會產生作用。
  • 呼叫這個方法是等冪的。

要求

<EMPTY>

RequestShow

要求顯示鍵盤。

  • 如果受呼叫者判斷這個 Controller 的 View 為焦點，受呼叫者會立即套用變更。
  • 如果受呼叫者判斷這個 Controller 的 View「並未」處於焦點狀態，受呼叫者會在 View 重新取得焦點時套用變更。不過，呼叫 RequestHide() 會使這類待處理要求失效。
  • 呼叫這個方法是等冪的。

要求

<EMPTY>

SetTextType

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

  • 如果受呼叫者判斷這個 Controller 的 View 為焦點，受呼叫者會立即套用變更。
  • 如果受呼叫者判斷這個 Controller 的 View 不是焦點，受呼叫者會在 View 重新取得焦點時套用變更。
  • 如果受呼叫者在 View 重新取得焦點前收到多通電話，受呼叫者會套用最近一次通話的值。

要求

名稱類型
text_type TextType

WatchVisibility

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

  • 當這個 Controller 尚未要求顯示鍵盤時，如果接聽端從這個 Controller 收到 RequestShow() 呼叫，就會傳回 true。

    • 這可能發生在鍵盤顯示於畫面前。
    • 這個 可能會在 Controller 聚焦前發生。View

  • 當受呼叫者決定隱藏這個控制器要求顯示的鍵盤時，會傳回 false。

    • 這可能是因為呼叫 RequestHide()，或是 View 失去焦點時隱含發生。
    • 鍵盤仍顯示在畫面上時，函式可能會傳回。

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

    • true 如果受呼叫者已決定應顯示鍵盤 (因為這個控制器 的要求)，這不保證鍵盤會顯示在畫面上
    • 其他情況則為 false

要求

<EMPTY>

回應

名稱類型
is_visible bool

ControllerCreator

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

提供取得 Controller 的功能。

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

請注意，Controller 本身允許設定虛擬鍵盤的呈現方式 (顯示和版面配置)，但不屬於文字事件。詳情請參閱 Controller 說明文件。

角色

這個通訊協定通常是：

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

建立

要求與管道另一端的 Controller 相關聯的請求，Controller由 view_ref 參照。ViewControllerserver_end:Controller

呼叫 Controller.RequestShow() 時，Controller 實作人員會嘗試提供適合輸入 text_type 的鍵盤 (除非類型遭呼叫 Controller.SetType() 覆寫)。

ControllerCreator 的實作人員應瞭解相關聯 View 的焦點狀態，以便對 Controller 上的呼叫套用存取權控管設定。詳情請參閱 Controller 方法的說明文件。

ControllerCreator 的消費者可以自由捨棄 Creator 連線，不會影響其控制器。

要求

名稱類型
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

回應

<EMPTY>

WatchTypeAndVisibility

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

第一次呼叫會立即傳回目前預期的 text_type 和可見度。

如果系統不支援 text_type，呼叫端應實作備援機制，盡可能提供必要金鑰。

要求

<EMPTY>

回應

名稱類型
text_type TextType
is_visible bool

ENUMS

TextType flexible

類型：uint32

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

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

名稱值說明
0

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

文字可能只包含數字字元。
2

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

VisibilityChangeReason flexible

類型：uint32

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

說明虛擬鍵盤可能新增至或從向使用者顯示的介面中移除的原因。

名稱值說明
1

曝光率因程式輔助請求而變更。舉例來說，GUI 元件呼叫 WatchTypeAndVisibility() 時，會傳回 is_visible 的新值。
2

使用者與 GUI 元件互動，導致可見度變更。例如，使用者輕觸了關閉按鈕。