本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 內嵌 Amazon WorkSpaces 應用程式串流工作階段的常數、函數和事件
<a name="constants-functions-events-embedded-sessions"></a>

下列主題提供常數、函數和事件的參考資訊，您可以用來設定內嵌 WorkSpaces 應用程式串流工作階段。

**Topics**
+ [使用 `HIDDEN_ELEMENTS`](#constants-hidden-elements)
+ [`AppStream.Embed` 物件的功能](#functions-embed-object)
+ [內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)
+ [新增事件接聽程式和結束內嵌 WorkSpaces 應用程式串流工作階段的範例](#examples-add-event-listeners-end-embedded-streaming-session)

初始化內嵌 WorkSpaces 應用程式串流工作階段時，下列 WorkSpaces 應用程式使用者介面元素可以傳入`HIDDEN_ELEMENTS`組態選項。

## 使用 `HIDDEN_ELEMENTS`
<a name="constants-hidden-elements"></a>

初始化內嵌 WorkSpaces 應用程式串流工作階段時，下列 WorkSpaces 應用程式使用者介面元素可以做為常數傳遞至`HIDDEN_ELEMENTS`組態選項。

```
AppStream.Embed.Elements.TOOLBAR
AppStream.Embed.Elements.FULLSCREEN_BUTTON
AppStream.Embed.Elements.END_SESSION_BUTTON
AppStream.Embed.Elements.TOOLBAR
AppStream.Embed.Elements.CATALOG_BUTTON
AppStream.Embed.Elements.WINDOW_SWITCHER_BUTTON
AppStream.Embed.Elements.FILES_BUTTON
AppStream.Embed.Elements.CLIPBOARD_BUTTON
AppStream.Embed.Elements.COPY_LOCAL_BUTTON
AppStream.Embed.Elements.PASTE_REMOTE_BUTTON
AppStream.Embed.Elements.SETTINGS_BUTTON
AppStream.Embed.Elements.STREAMING_MODE_BUTTON
AppStream.Embed.Elements.SCREEN_RESOLUTION_BUTTON
AppStream.Embed.Elements.REGIONAL_SETTINGS_BUTTON
AppStream.Embed.Elements.FULLSCREEN_BUTTON
AppStream.Embed.Elements.END_SESSION_BUTTON
```

以下三個元素可做為字串傳遞至 HIDDEN\_ELEMENTS，而不是以常數傳遞。


| String | Description | 
| --- | --- | 
| 'adminCommandsButton' | 當您連線到 WorkSpaces 應用程式映像建置器時，WorkSpaces 應用程式工具列右上角會顯示 Admin Commands 按鈕。 WorkSpaces 將此字串傳遞至 HIDDEN\_ELEMENTS 會隱藏 Admin Commands (管理命令) 按鈕。 | 
| 'softKeyboardButton' | 在已啟用觸控功能的裝置上的 WorkSpaces 應用程式串流工作階段期間，使用者可以點選 WorkSpaces 應用程式工具列上的鍵盤圖示，以顯示螢幕鍵盤。將此字串傳遞至 HIDDEN\_ELEMENTS 會隱藏鍵盤圖示。 | 
| 'keyboardShortcutsButton' | 在已啟用觸控功能的裝置上的 WorkSpaces 應用程式串流工作階段期間，使用者可以點選 WorkSpaces 應用程式工具列上的 Fn 圖示，以顯示鍵盤快速鍵。將此字串傳遞至 HIDDEN\_ELEMENTS 會隱藏 Fn 圖示。 | 

## `AppStream.Embed` 物件的功能
<a name="functions-embed-object"></a>

下表列出可在 `AppStream.Embed` 物件上執行的功能。


| 函式 | Description | 
| --- | --- | 
| AppStream.Embed(containerId:string, options:object) | AppStream.Embed 物件建構函數。此建構函數會初始化並與 AppStream.Embed 物件通訊，而且會使用 div 容器 ID。該 ID 會於注入 iframe 時使用，也會注入包含 appstreamOptions ({{sessionURL}} 和 HIDDEN\_ELEMENTS) 組態選項的物件。 | 
| endSession() | 此函數會結束串流工作階段，但不會破壞 iframe。如果您指定一個重新導向 URL，iframe 會嘗試載入 URL。根據頁面的 CORS 標頭，URL 可能無法載入。 | 
| launchApp(appId:string) | 此函數會以程式設計的方式，使用影像建立期間指定的應用程式 ID 啟動應用程式。 | 
| launchAppSwitcher() | 此函數會將 AppSwitcher命令傳送至 WorkSpaces 應用程式入口網站。此操作會觸發執行個體上的 AppSwitcher 命令。 | 
| getSessionState() | 此函數會傳回 sessionStatus 的物件。如需詳細資訊，請參閱[內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)。 | 
| getUserInterfaceState() | 此函數會傳回 `UserInterfaceState` 的物件。此物件包含以下項目的金鑰值配對：<br />`sessionStatus`：狀態列舉<br />`sessionTerminationReason`：String<br />`sessionDisconnectionReason`：String<br /> 如需詳細資訊，請參閱[內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)。 | 
| addEventListener(name, callback) | 此函數會新增回呼功能，以在指定的活動觸發時呼叫。如需可觸發的事件清單，請參閱 [內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)。 | 
| removeEventListener(name, callback) | 此函數會刪除指定事件的回呼。 | 
| destroy() | 此函數會刪除 iframe 並清理資源。此函數不會影響進行中的串流工作階段。 | 

## 內嵌 WorkSpaces 應用程式串流工作階段的事件
<a name="events-embedded-streaming-sessions"></a>

下表列出可在內嵌 WorkSpaces 應用程式串流工作階段期間觸發的事件。


| 事件 | 資料 | Description | 
| --- | --- | --- | 
| AppStream.Embed.Events.SESSION\_STATE\_CHANGE | `sessionStatus`: `State enumeration`<br />`sessionTerminationReason`：String<br />`sessionDisconnectionReason`：String | 此事件會在有任何工作階段狀態變更發生時觸發。此事件包含已變更的狀態的對應。若要擷取完整工作階段狀態，請使用 `getSessionState()` 函數。<br />以下是工作階段狀態：<br />`AppStream.Embed.SessionStatus.Unknown`：工作階段尚未開始且未保留<br />`AppStream.Embed.SessionStatus.Reserved`：工作階段已保留，但尚未開始。<br />`AppStream.Embed.SessionStatus.Started`：使用者已連線至工作階段並開始串流。<br />`AppStream.Embed.SessionStatus Disconnected `：使用者已與工作階段中斷連線。<br />`AppStream.Embed.SessionStatus.Ended`：工作階段已標示為已結束或已過期。 | 
| AppStream.Embed.Events.SESSION\_INTERFACE\_STATE\_CHANGE | `hiddenElements`: 字串陣列<br /> `isFullscreen`：Boolean<br />`isSoftKeyboardVisible`：Boolean | 此事件會在有任何工作階段狀態變更發生時觸發。此事件包含已變更的狀態的對應。若要擷取完整工作階段狀態，請使用 getSessionState() 函數。 | 
| AppStream.Embed.Events.SESSION\_ERROR | `errorCode`: 數字<br />`errorMessage`：String | 工作階段期間發生任何錯誤都會觸發此事件。 | 

## 新增事件接聽程式和結束內嵌 WorkSpaces 應用程式串流工作階段的範例
<a name="examples-add-event-listeners-end-embedded-streaming-session"></a>

本節中的範例說明如何執行以下動作：
+ 新增內嵌 WorkSpaces 應用程式串流工作階段的事件接聽程式。
+ 以程式設計方式結束內嵌 WorkSpaces 應用程式串流工作階段。

### 範例 1：為內嵌 WorkSpaces 應用程式串流工作階段新增事件接聽程式
<a name="example-add-event-listeners"></a>

若要在嵌入串流工作階段期間變更工作階段狀態、變更工作階段介面狀態和新增工作階段錯誤的事件偵聽程式，請使用以下程式碼：

```
appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_STATE_CHANGE, updateSessionStateCallback);

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE, updateUserInterfaceStateCallback);

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_ERROR, errorCallback);
```

在此範例中，`AppStream.Embed.Events.SESSION_STATE_CHANGE`、`AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE` 和 `AppStream.Embed.Events.SESSION_ERROR` 為事件名稱。

`updateSessionStateCallback`、`updateUserInterfaceStateCallback` 和 `errorCallback` 函數是您實作的函數。系統會將這些函數傳送至 `addEventListener` 函數，並在觸發事件時呼叫。

### 範例 2：以程式設計方式結束內嵌 WorkSpaces 應用程式串流工作階段
<a name="programmatically-end-embedded-streaming-session"></a>

若要結束內嵌 WorkSpaces 應用程式串流工作階段，請使用下列函數：

```
appstreamEmbed.endSession();
```