# PlayDrop 遊戲的全螢幕、安全區域與 HUD 角落

讓 PlayDrop 遊戲填滿螢幕，並用 SDK 實際測量的 reservedCorners，讓 HUD 保持在 CSS 安全區域內、避開主機端的控制項。

Source: https://www.playdrop.ai/zh-hant/create/learn/viewport

PlayDrop 會把整個螢幕交給你的遊戲：網站的遊戲頁面有自己的全螢幕控制項，App 也會以全螢幕遊玩遊戲。在手機上，PlayDrop 會在遊戲上方兩角放置小型的暫停與音訊控制項（派對期間還有語音控制項）。SDK 會告訴你它們的確切位置，讓 HUD 能避開它們，又不浪費空間。

## 填滿可視區域

從邊緣畫到邊緣，並防止頁面捲動、縮放或選取文字：

```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, user-scalable=no">
<style>
  html, body { margin: 0; width: 100%; height: 100%; overflow: hidden; background: #000; }
  body { touch-action: none; user-select: none; -webkit-user-select: none; -webkit-touch-callout: none; }
  canvas { display: block; width: 100vw; height: 100dvh; }
</style>
```

以 canvas 的顯示尺寸乘以 `devicePixelRatio` 來設定它的大小，並在 `resize` 時重新繪製；在電腦、平板、折疊手機上，以及手機旋轉時，視窗大小都會改變。背景圖和遊戲場地要鋪滿各處，包括瀏海和主機端控制項的下方。只有可互動和需要閱讀的 HUD 元素需要避開它們。你不需要自己的全螢幕按鈕。

## 讓 HUD 保持清楚

有兩種東西可能會遮住邊緣：

- **硬體安全區域**，例如瀏海或主畫面指示條，來自 CSS 的 `env(safe-area-inset-top|right|bottom|left)`。
- **主機端的控制項**，來自 `sdk.host.reservedCorners`：`{ topLeft: { width, height }, topRight: { width, height } }`，以 CSS 像素表示，從遊戲可視區域的左上角和右上角開始測量。

要避開的是兩者的聯集，絕不是兩者相加。左上角的 HUD 元素可以放在角落矩形的下方或旁邊；無論哪種方式，每個方向都採用較大的間距：

```js
const root = document.documentElement.style;
function layoutHud(corners) {
  const left = corners?.topLeft ?? { width: 0, height: 0 };
  const right = corners?.topRight ?? { width: 0, height: 0 };
  root.setProperty("--pd-tl-h", `${left.height}px`);
  root.setProperty("--pd-tr-h", `${right.height}px`);
}
layoutHud(sdk.host.reservedCorners);
const stop = sdk.host.onReservedCornersChange(layoutHud);
```

```css
.score { position: absolute; left: max(12px, env(safe-area-inset-left));
  top: max(12px, env(safe-area-inset-top), var(--pd-tl-h, 0px)); }
.lives { position: absolute; right: max(12px, env(safe-area-inset-right));
  top: max(12px, env(safe-area-inset-top), var(--pd-tr-h, 0px)); }
```

- 寬度和高度為零代表那個角落沒有被遮住，例如在電腦版網站上，控制項位於遊戲外面。
- `null` 代表不回報角落的舊版主機端：請保留你現有、使用安全區域的版面。
- 這些值來自實際出現在畫面上的控制項，例如手機上至少 44 點的觸控目標，並會隨旋轉、調整大小和派對而改變。請讀取它們；絕不要寫死尺寸，或保留一整條全寬的頂部區域。

卸載遊戲時，請用傳回的函式取消訂閱。

## 方向與顯示環境

在 [catalogue.json](https://www.playdrop.ai/zh-hant/create/learn/catalogue-json) 中宣告遊戲在哪裡可以運作：`surfaceTargets` 列出 `desktop`、`mobileLandscape` 和 `mobilePortrait`，`primarySurface` 則指定遊戲設計時採用的那一個。只啟用你測試過的項目。直向遊戲顯示在寬螢幕上時，仍應以協調的背景填滿畫面，而不是留下黑邊；[即玩](https://www.playdrop.ai/zh-hant/create/learn/instant-games)遊戲則必須以直向為主。

## 觸控螢幕上的輸入

讓操控方便拇指使用：至少 44 CSS 像素，並遠離保留的角落和系統手勢起始的螢幕邊緣。使用指標事件，在遊戲觸控上呼叫 `preventDefault()`，並在電腦上支援鍵盤和滑鼠。控制器說明請參閱[本機派對與控制器](https://www.playdrop.ai/zh-hant/create/learn/local-party)。

## 相關指南

- [載入、暫停與音訊](https://www.playdrop.ai/zh-hant/create/learn/lifecycle): 初始化 PlayDrop SDK，在第一個可遊玩的畫面發出就緒訊號，順暢地暫停與恢復，遵循主機端的音訊政策，並為原生 App 與離線遊玩預先載入檔案。
- [本機派對與控制器](https://www.playdrop.ai/zh-hant/create/learn/local-party): 透過 sdk.device 讀取實體手把與 PlayDrop 手機控制器，追蹤本機玩家插槽，並宣告控制器支援與本機派對人數。
- [用戶端 SDK](https://www.playdrop.ai/zh-hant/create/learn/sdk): PlayDrop 瀏覽器 SDK 參考：初始化、主機端生命週期、玩家身分與存檔、裝置與控制器、社群、多人連線、商店、廣告、排行榜、成就、素材與 AI。