---
type: reference
title: 尺寸与布局
summary: width、height、overlay-width 和 overlay-height 属性如何在 inline、modal 和 fullscreen 布局下为 caputchin-game 元素设定尺寸。
---

`<caputchin-game>` 能以三种布局渲染（用 `layout` 属性设定）：`inline`、`modal` 和 `fullscreen`。怎样为它设尺寸取决于布局，因为 modal 和 fullscreen 布局会显示**两个独立的框**：

- **页内元素**：处在你页面流里的那个东西。在 `inline` 下它是整个游戏面板；在 `modal` / `fullscreen` 下它是访客点击以打开游戏的那个小复选框。
- **游戏框**：在 `modal` / `fullscreen` 下从上层弹出的对话框，里面装着游戏。（在 `inline` 下没有单独的对话框：面板本身就是游戏。）

四个属性为这两个框设尺寸。每个值都是 `auto`（默认）、`full`（撑满可用空间）或像 `480` 这样的正像素数，三者之一。

| 属性 | 设定 | 适用于 |
|---|---|---|
| `width` / `height` | 页内元素 | 所有布局 |
| `overlay-width` / `overlay-height` | 游戏框（对话框 + 游戏） | `modal`、`fullscreen` |

## Inline

Inline 只有一个框，所以 `width` / `height` 为整个面板设尺寸。`overlay-width` / `overlay-height` 在这里不起作用，会被忽略（如果你设了它们，组件会记录一条警告）。

```html
<!-- A panel that spans its container, at a fixed height -->
<caputchin-game sitekey="cpt_pub_..." layout="inline" width="full" height="480"></caputchin-game>
```

## Modal 和 fullscreen

这里两个框是相互独立的。`width` / `height` 为你页面上的**入口复选框**设尺寸；`overlay-width` / `overlay-height` 为访客点击时打开的**对话框和游戏**设尺寸。

```html
<!-- Full-width entry checkbox; the game opens at its natural size, centered -->
<caputchin-game sitekey="cpt_pub_..." layout="modal" width="full"></caputchin-game>

<!-- Compact entry checkbox; the game fills the dialog -->
<caputchin-game sitekey="cpt_pub_..." layout="modal" overlay-width="full" overlay-height="full"></caputchin-game>

<!-- A 500px entry, opening a fixed 900x600 game dialog -->
<caputchin-game
  sitekey="cpt_pub_..."
  layout="modal"
  width="500"
  overlay-width="900"
  overlay-height="600"
></caputchin-game>
```

`overlay-width="full"` 让游戏沿该轴撑满对话框；一个像素值则把游戏固定为那个尺寸（modal 会紧紧裹住它）。在 `fullscreen` 下，对话框已经覆盖整个视口，所以 `overlay-*` 控制的是游戏拉伸填满它，还是按自己的尺寸居中摆放。

## 当你不设游戏框时

如果你不设 `overlay-width` / `overlay-height`，游戏框就采用**游戏作者**为游戏选定的尺寸（它偏好的占位，在游戏的 `caputchin.json` 里声明）。所以大多数时候你只需为你的页面布局设 `width` / `height`，游戏就会把自己的尺寸定得很合理。只有当你想覆盖它时才设 `overlay-*`。

## 像素值

一个纯数字就是 CSS 像素：`width="500"` 和 `width="500px"` 等价。零、负数和非数字值会被拒绝（属性退回其默认值，组件记录一条警告）。

## 另见

- [游戏组件元素](/docs/getting-started/add-a-game)：完整的 `<caputchin-game>` 属性集。
- [组件方法与事件](/docs/references/widget-methods-and-events)：驱动组件并对它作出响应。