# window（視窗）
下面範例為 `window` 的常用功能：
```javascript
await eagle.window.show(); // 顯示插件視窗
await eagle.window.hide(); // 隱藏插件視窗
await eagle.window.minimize(); // 縮小視窗
await eagle.window.restore(); // 還原縮小
await eagle.window.maximize(); // 最大化視窗
await eagle.window.unmaximize(); // 還原最大化
await eagle.window.setFullScreen(true); // 設為全螢幕
await eagle.window.setFullScreen(false); // 離開全螢幕
```
***
#### 方法
## show()
顯示並聚焦於視窗。
* 返回 `Promise<>`
```javascript
await eagle.window.show();
```
***
## showInactive()
顯示但不聚焦於視窗。
* 返回 `Promise<>`
```javascript
await eagle.window.showInactive();
```
***
## hide()
隱藏插件視窗。
* 返回 `Promise<>`
```javascript
await eagle.window.hide();
```
***
## focus()
使插件視窗取得焦點。
* 返回 `Promise<>`
```javascript
await eagle.window.focus();
```
***
## minimize()
最小化插件視窗。
* 返回 `Promise<>`
```javascript
await eagle.window.minimize();
```
***
## isMinimized()
判斷視窗是否最小化。
* 返回 `Promise`
* `minimized` boolean - 視窗是否最小化
```javascript
let isMinimized = await eagle.window.isMinimized();
```
***
## restore()
將插件視窗從最小化狀態恢復到以前的狀態。
* 返回 `Promise<>`
```javascript
await eagle.window.restore();
```
***
## maximize()
最大化插件視窗。 如果視窗尚未顯示，該方法也會將其顯示 (但不會聚焦)。
* 返回 `Promise<>`
```javascript
await eagle.window.maximize();
```
***
## unmaximize()
取消插件視窗最大化
* 返回 `Promise<>`
```javascript
await eagle.window.unmaximize();
```
***
## isMaximized()
判斷視窗是否最大化
* 返回 `Promise`
* `maximized` boolean - 視窗是否最大化
```javascript
let isMaximized = await eagle.window.isMaximized();
```
***
## setFullScreen(flag)
設定視窗是否應處於全屏模式。
* `flag` boolean - 是否設為全屏
* 返回 `Promise<>`
```javascript
await eagle.window.setFullScreen(true); // 進入全屏
await eagle.window.setFullScreen(false); // 退出全屏
```
***
## isFullScreen()
判斷視窗是否全屏
* 返回 `Promise`
* `fullscreen` boolean - 視窗是否全屏
```javascript
let isMaximized = await eagle.window.isMaximized();
```
***
## setAspectRatio(aspectRatio)
這將使視窗保持長寬比。
* `aspectRatio` Float - 保持的寬高比（寬 / 高）
* 返回 `Promise<>`
```javascript
await eagle.window.setAspectRatio(16/9); // 將視窗寬高比例限制為 16:9
```
***
## setBackgroundColor(backgroundColor)
設定視窗的背景顏色。
* `backgroundColor` String - 此參數代表您所希望的背景顏色的HEX代碼。
* 返回 `Promise<>`
```javascript
await eagle.window.setBackgroundColor("#FFFFFF");
```
{% hint style="info" %}
注1：此屬性可以直接在 manifest.json 進行設定。
注2：這個設定主要用來設定在 HTML / CSS 內容尚未完成前，視窗預設的背景顏色，適當的設定可以避免發生視窗顯示出現閃爍的狀況。
{% endhint %}
***
## setSize(width, height)
設定視窗大小
* `width` Integer - 視窗寬度
* `height` - Integer - 視窗高度
* 返回 `Promise<>`
```javascript
await eagle.window.setSize(720, 480);
```
{% hint style="info" %}
注：此屬性可以直接在 manifest.json 進行設定。
{% endhint %}
***
## getSize()
取得視窗大小。
* 回傳 `Promise`
```javascript
await eagle.window.getSize();
```
## setBounds(**bounds**)
調整視窗大小並移動至指定的邊界位置。未提供的屬性將會保留目前的值。
```javascript
await eagle.window.setBounds({ x: 440, y: 225, width: 800, height: 600 })
```
## getBounds()
取得視窗的邊界資訊。
* 回傳 `Promise` - 表示視窗邊界的物件
```javascript
await eagle.window.getBounds()
```
## setResizable(resizable)
設定視窗是否支援調整大小
* `resizable` boolean - 是否支援調整大小
* 返回 `Promise<>`
```javascript
await eagle.window.setResizable(true);
await eagle.window.setResizable(false);
```
{% hint style="info" %}
注：此屬性可以直接在 manifest.json 進行設定。
{% endhint %}
***
## isResizable()
視窗是否支援調整大小
* 返回 `Promise`
* `resizable` boolean
```javascript
let isResizable = await eagle.window.isResizable();
```
***
## setAlwaysOnTop(flag)
設定視窗是否應始終顯示在其他視窗的前面。
* `flag` boolean
* 返回 `Promise<>`
```javascript
await eagle.window.setAlwaysOnTop(true);
await eagle.window.setAlwaysOnTop(false);
```
***
## isAlwaysOnTop()
視窗是否應始終顯示在其他視窗的前面
* 返回 `Promise`
* `alwaysOnTop` boolean
```javascript
let isAlwaysOnTop = await eagle.window.isAlwaysOnTop();
```
***
## setPosition(x, y)
將視窗移動到 x 和 y。
* `x` Integer
* `y` Integer
* 返回 `Promise<>`
```javascript
await eagle.window.setPosition(100, 200);
```
***
## getPosition()
取得插件視窗座標 x 和 y。
* 返回 `Promise`
* `position` Integer\[]
* x - position\[0]
* y - position\[1]
```javascript
let position = await eagle.window.getPosition(); // [100, 200]
```
***
## setOpacity(opacity)
設定視窗的不透明度， 超出界限的數值被限制在\[0, 1] 範圍內。
* `opacity` number - 介於0.0 ( 完全透明 ) 和1.0 ( 完全不透明 ) 之間
* 返回 `Promise<>`
```javascript
await eagle.window.setOpacity(0.5);
```
***
## getOpacity()
取得視窗透明度，介於0.0 (完全透明) 和1.0 (完全不透明) 之間。
* 返回 `Promise`
* `opacity` number
```javascript
let opacity = await eagle.window.getOpacity();
```
***
## flashFrame(flag)
啓動或停止閃爍視窗, 以吸引使用者的注意。
* `flag` boolean - 是否閃爍
* 返回 `Promise<>`
```javascript
await eagle.window.flashFrame(true);
await eagle.window.flashFrame(false);
```
***
## setIgnoreMouseEvents(ignore)
忽略視窗內的所有滑鼠事件。在此視窗中發生的所有滑鼠事件將被傳遞到此視窗下面的視窗，但如果此視窗具有焦點，它仍然會接收鍵盤事件。
* `ignore` boolean - 是否忽略滑鼠事件
* 返回 `Promise<>`
```javascript
await eagle.window.setIgnoreMouseEvents(true);
await eagle.window.setIgnoreMouseEvents(false);
```
{% hint style="info" %}
搭配 setAlwaysOnTop() 功能，將可以新增一個懸浮在螢幕最上方且可穿透滑鼠點擊的特殊視窗。
{% endhint %}
## capturePage(rect)
捕獲 `rect` 指定區域的頁面快照。省略 `rect` 將捕獲整個可見頁面。
* `rect` 物件 - 可選，截圖範圍
* `x` 數字
* `y` 數字
* `width` 數字
* `height` 數字
* 返回 `Promise<[NativeImage](https://www.electronjs.org/docs/latest/api/native-image)>`
```javascript
const image = await eagle.window.capturePage();
const base64 = image.toDataURL("image/jpeg");
const image2 = await eagle.window.capturePage({ x: 0, y: 0, width: 100, height: 50 });
const buffer = image2.toPNG();
```
## setReferer(url)
函式用來設定目前的引用來源網址（referer URL）。當您設定了引用來源後，後續的請求都會使用這個設定的引用來源。
* `url` 文字 - 引用來源的網址
* 返回 `void`
```javascript
eagle.window.setReferer("https://tw.eagle.cool");
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.eagle.cool/plugin-api/zh-tw/api/window.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.