fuchsia.ui.views

新增日期：7

通訊協定

焦點

在 fuchsia.ui.views/focuser.fidl 中定義

透過程式輔助方式轉移檢視畫面焦點的方法。

通訊協定用戶端可直接存取要求者 ViewRef，做為要求授權的基礎。

RequestFocus

要求伺服器將焦點轉移至 view_ref 指定的 View，並由要求者 ViewRef 授權。這類要求可能會遭到拒絕或拒絕。

如果要求受到接受且觸發了焦點變更，則 FocusEvent (with focus=true) 會發出到新聚焦的 View，而 FocusEvent (with focus=false) 則會發送至先前的 View。

結果回呼會指出系統已收到並遵循要求。但不保證要求的檢視畫面確實及時收到 FocusEvent。

系統拒絕要求的原因有很多，包括：

  • 如果 view_ref 無效
  • 表示沒有由 view_ref 支援的檢視畫面
  • (如果沒有要求者 ViewRef 存取)
  • 如果要求者 ViewRef 缺少 view_ref 的檢視畫面授權
  • 表示 view_ref 的 View 無法達成或可能無法接收焦點等項目。遭拒的要求會以「錯誤」表示。

要求

名稱類型
view_ref ViewRef

回應

名稱類型
payload Focuser_RequestFocus_Result

SetAutoFocus

將自動對焦目標設為 view_ref 指定的檢視畫面。如要取消設定目標，請傳入空白資料表。

如果已設定目標，則每當呼叫端的檢視畫面收到聚焦時，系統就會嘗試立即將焦點轉移到目標。如果目標無法聚焦，新目標就會是目標的第一個可聚焦祖系。設定自動對焦目標不會對同時使用 RequestFocus() 造成任何限制。

自動對焦目標只有在 ViewTree 中呼叫端檢視畫面的子系時才會設為「有效」。允許指定無效的自動對焦目標，因為該目標可能之後可能會失效。客戶必須負責確保目標是有效的自動對焦接收器。

如果自動聚焦行為觸發時目標無效，則嘗試移動焦點時會失敗，且焦點會留在呼叫端的檢視畫面。目標可能會失效，並在任意次數後變成有效狀態；只要目標處於有效狀態，自動對焦功能就會繼續運作，且在目標處於無效狀態時會繼續忽略目標。

如果其他自動機制會將焦點移回呼叫端的檢視畫面 (例如目標無法聚焦)，則焦點仍會保留在呼叫端的 View。

AutoFocusError 目前則一律不會傳回，並保留供日後使用。

新增日期：9

要求

名稱類型
payload FocuserSetAutoFocusRequest

回應

名稱類型
payload Focuser_SetAutoFocus_Result

檢視模式

在 fuchsia.ui.views/view.fidl 中定義

淘汰了建立檢視畫面的 API。請勿使用。

已淘汰

展示

提供具有「景觀」場景圖的連接點。

當 Present() 呼叫 View 的實作時，應透過提供 view_token (使用 fuchsia.ui.gfx.CreateResourceCmd 和 fuchsia.ui.gfx.ViewArgs)，在 View 內建立 View 資源。

接著，實作應使用 fuchsia.ui.gfx.AddChildCmd 將其圖形內容附加至新建立的 View 資源。

如果實作已經擁有 View 資源 (因為先前已呼叫了 Present())，則應因為發生錯誤而終止連線。

TODO(https://fxbug.dev/42098670)：允許透過新的 Present() 呼叫重新父項 View。

要求

名稱類型
view_token ViewToken

ViewRefFocused

在 fuchsia.ui.views/view_ref_focus.fidl 中定義

啟用 ViewRef 建立者的方法，用於判斷 ViewRef 是否已獲得或失去檢視畫面樹狀結構的焦點。

通訊協定用戶端具有隱含存取權的 ViewRef 存取權；通訊協定本身不接受 ViewRef 參數。無論用戶端是受信任或其他用戶端，都需要存取聚焦狀態，因此通訊協定的確是最低限度。持有 ViewRef (和此通訊協定) 的保留並未授權瞭解 ViewRef 的焦點狀態。

觀看

設定在隱式 ViewRef 取得或失去聚焦時觸發的回呼。一般來說，焦點變更會以緩慢的速度發生，因此回呼會擷取每次轉換。不過，焦點變更可能很快就會發生，因此回呼可能會「壓縮」焦點變更記錄到最新的已知焦點狀態。

回呼會回報上次的焦點變更，時間涵蓋從發出內容到上一個回呼的核發期間。用戶端可能會觀察到下列四種轉場效果：

  • true -> true：ViewRef 失去了至少一次焦點，而且現在專注在發出回呼的時間。
  • true -> false：ViewRef 失去至少一次焦點，且在發出回呼時失去焦點。
  • false -> true：ViewRef 已聚焦至少一次，並在發出回呼時引起焦點。
  • false -> false：ViewRef 已聚焦至少一次，且在發出回呼時失去焦點。

用戶端會避免「聚焦閃爍」，而且一律會看到最新狀態。每次發出回呼都很有意義，且用戶端應適當重新協商聚焦相關服務，例如 IME。

流程控制：系統一次最多允許呼叫端正在進行 |觀察| 呼叫：後續的 |Watch| 呼叫必須等待確認傳回。違反規定會使管道遭關閉。

要求

<EMPTY>

回應

名稱類型
state FocusState

ViewRefInstalled

在 fuchsia.ui.views/view_ref_INSTALL.fidl 定義

啟用 ViewRef 持有者的方法，用於判斷 ViewRef 是否已「安裝」在檢視畫面樹狀結構中：第一次 (以連帶方式) 連線至根層級檢視畫面。一般而言，安裝完成後，檢視畫面焦點可能會轉移至該 ViewRef。

注意：請務必區別 ViewRef 的安裝狀態和目前連線至檢視畫面的樹狀結構狀態。前者會經歷一次狀態變更，從「no」變更為「是」。後者可能會持續變更，視檢視區塊樹狀結構的拓撲而定。因此，「已安裝」不得暗示「目前連線至檢視樹狀結構」，即使以假想的「ViewRefConnected」通訊協定來說，也屬於兒童不宜。

觀看

設定在安裝所要求的 |view_ref| 時觸發的回呼。

  • 如果尚未安裝 |view_ref|，則 |Watch| 回應會在安裝時觸發。
  • 如已安裝 |view_ref|，系統會立即觸發 |Watch| 回應。
  • 如果 |view_ref| 無效或失效 (可能是因為檢視畫面被刪除)，|Watch| 呼叫會傳回錯誤。這項錯誤不保證會立即發生，但 ViewRef 容器可以藉由監聽 ZX_EVENTPAIR_PEER_CLOSED 自行判斷 ViewRef 是否有效。

流程控制：呼叫端可在多個 ViewRefs 上進行多個 |Watch| 呼叫。每次呼叫用戶端最多只有一則回應。

注意：安裝前，只要 ViewRef 有效，這個 |Watch| 呼叫就會保持運作。

要求

名稱類型
view_ref ViewRef

回應

名稱類型
payload ViewRefInstalled_Watch_Result

結構化

Focuser_RequestFocus_Response

定義於 fuchsia.ui.views/focuser.fidl

<EMPTY>

Focuser_SetAutoFocus_Response

定義於 fuchsia.ui.views/focuser.fidl

<EMPTY>

ViewCreationToken 資源

在 fuchsia.ui.views/flatland_tokens.fidl 中定義

兩個 Flatland 實例可透過父項/子項關係建立連結。子端點會保存在 View 中。這個檢視畫面與 ViewRef 和其他相關通訊協定密切關聯。

ViewCreationToken 是管道類型的包裝函式，代表兩個 Flatland 執行個體之間連線的子端點。由於這個管道只會做為與對等點的不可衝突物件使用，因此系統不會透過這個管道傳送任何訊息。

欄位類型說明預設
value handle<channel> 無預設

ViewHolderToken 資源

在 fuchsia.ui.views/view_token.fidl 中定義

專門用於在全域場景圖表中識別 View 附件點的權杖。每個 ViewHolderToken 都有一個對應的 ViewToken。

景觀用戶端可以使用這個憑證建立 ViewHolder 資源，藉此參照其他用戶端的內容。其他用戶端也必須使用對應的 ViewToken 建立 View 資源。

欄位類型說明預設
value handle<eventpair> 無預設

ViewIdentityOnCreation 資源

在 fuchsia.ui.views/view_ref.fidl 中定義

在建立檢視表時，方便自行識別檢視畫面的資料類型。

ViewRef 可用於識別檢視畫面，可自由複製並發布至其他元件。

ViewRefControl 用於實作生命週期通知，不得複製，也無法發布至其他元件。檢視區塊會將 ViewRefControl 物件繫結至檢視畫面，因此刪除檢視畫面時，ViewRefControl 會觸發 ZX_EVENTPAIR_PEER_CLOSED 信號給所有 ViewRef 容器，從而通知檢視畫面死亡。

用途：建立檢視畫面時，請將 ViewRef 和 ViewRefControl 放在這個結構中，讓兩者可以一個單位前往目的地元件。這個便利結構可讓通訊協定作者將這段旅行組合描述為一個引數。可提升可讀性並減少處理錯誤的問題。

欄位類型說明預設
view_ref ViewRef

要建立檢視表的穩定 ID。

 無預設
view_ref_control ViewRefControl

生命週期通知的機制。

 無預設

ViewRef 資源

在 fuchsia.ui.views/view_ref.fidl 中定義

ViewRef 是核心物件的控制代碼，用於識別整個系統中的唯一 View。兩個 ViewRef 至同一個檢視畫面，都具有相同的 KOID。

用戶端會使用 ViewRef 來識別 View、驗證 View，以及接收 View 撤銷信號。

建立 View 時，用戶端會建立一個已連結的 ViewRef/ViewRefControl 組合，並將配對提供給 View (詳情請參閱下文)。用戶端必須移除 ViewRef 的信號功能，否則不會建立 View。

用戶端可以自由複製並分享 ViewRef 檔案，甚至在傳送至 View 之前。

範例 1：無障礙功能接受用戶端傳送的 ViewRef，將語意節點和語意作業分組，然後與用戶端的 View 建立關聯。而是必須使用 View 驗證用戶端的 ViewRef。

範例 2：我們使用 ViewRefs 建立 FocusChain，並在檢視畫面階層下找出判定為「聚焦」的檢視畫面。View 遭到刪除時，Scenic 會向所有 FocusChain 容器發出訊號，指出 ViewRef 現已無效。

欄位類型說明預設
reference handle<eventpair> 無預設

ViewRefControl 資源

在 fuchsia.ui.views/view_ref.fidl 中定義

ViewRefControl 與 ViewRef 的對等項目。孩子的 reference 已連結。

和 ViewRef 一樣，ViewRefControl 是事件配對的型別控點。與 ViewRef 不同，ViewRefControl 的控點是唯一的。景觀在將 ViewRefControl 與 View 建立關聯時，會使用這個屬性，並安排共用命運級別。當檢視畫面刪除時，相關聯的 ViewRefControl 會觸發自動 ZX_EVENTPAIR_PEER_CLOSED 信號傳送給所有 ViewRef 持有者，因此 ViewRef 容器可以追蹤 View 生命週期。

建立 View 時，用戶端會建立一個已連結的 ViewRef/ViewRefControl 組合，並將配對提供給 View (如前文所述)。用戶端不得複製 ViewRefControl。不得移除或修改 ViewRefControl 的功能，否則不會建立 View。

欄位類型說明預設
reference handle<eventpair> 無預設

ViewRefInstalled_Watch_Response

在 fuchsia.ui.views/view_ref_INSTALL.fidl 定義

<EMPTY>

ViewToken 資源

在 fuchsia.ui.views/view_token.fidl 中定義

可明確識別 View 的權杖，這是全域場景圖中子圖表的根點。每個 ViewToken 都有一個對應的 ViewHolderToken。

景觀用戶端可以使用這個憑證建立 View 資源，以從其他用戶端參照其內容。其他用戶端也必須使用對應的 ViewHolderToken 建立 ViewHolder 資源。

欄位類型說明預設
value handle<eventpair> 無預設

ViewportCreationToken 資源

在 fuchsia.ui.views/flatland_tokens.fidl 中定義

兩個 Flatland 實例可透過父項/子項關係建立連結。父項端點會保存在可視區域。

ViewportCreationToken 是管道類型的包裝函式，代表兩個 Flatlands 頻道之間連線的父項端點。由於這個管道只能做為與對等點的不可衝突物件使用，因此系統不會透過這個管道傳送任何訊息。

欄位類型說明預設
value handle<channel> 無預設

ENUMS

AutoFocusError 彈性

類型：uint32

在 fuchsia.ui.views/focuser.fidl 中定義

新增日期：9

名稱值說明

錯誤：strict

類型：uint32

在 fuchsia.ui.views/focuser.fidl 中定義

Focuser.RequestFocus 上發生的問題情況。

名稱值說明
1

RequestFocus 遭拒時傳回的值。

ViewRefInstalledError 嚴格

類型：uint32

在 fuchsia.ui.views/view_ref_INSTALL.fidl 定義

與 |ViewRefInstalled| 相關的錯誤代碼。

名稱值說明
1

觀看的 ViewRef 無效或已失效。

資料表

FocusState

在 fuchsia.ui.views/view_ref_focus.fidl 中定義

ViewRef 的焦點狀態。

序數欄位類型說明
focused bool

說明 ViewRef 是否已取得焦點 (true) 或失去聚焦 (false)。

必填欄位。

FocuserSetAutoFocusRequest 資源

定義於 fuchsia.ui.views/focuser.fidl

序數欄位類型說明
view_ref ViewRef

聯合國

指令：嚴格

定義於 fuchsia.ui.views/commands.fidl

請勿使用 - 在 fuchsia.ui.scenic.Command 中保留 ABI 穩定性

已淘汰：10
序數Variant類型說明
empty int32

Focuser_RequestFocus_Result 嚴格

在 fuchsia.ui.views/focuser.fidl 中定義

序數Variant類型說明
response Focuser_RequestFocus_Response
err Error

Focuser_SetAutoFocus_Result 嚴格

在 fuchsia.ui.views/focuser.fidl 中定義

序數Variant類型說明
response Focuser_SetAutoFocus_Response
err AutoFocusError

ViewRefInstalled_Watch_Result 嚴格

在 fuchsia.ui.views/view_ref_INSTALL.fidl 定義

序數Variant類型說明
response ViewRefInstalled_Watch_Response
err ViewRefInstalledError