# dialog（對話框）

下面是一個選擇多個檔案的對話框範例：

```javascript
let result = await eagle.dialog.showOpenDialog({ 
    properties: ['openFile', 'multiSelections'] 
});
```

#### 方法 <a href="#z1a5y" id="z1a5y"></a>

## showOpenDialog(options) <a href="#tkp0d" id="tkp0d"></a>

顯示開啓檔案對話框。

* `options` Object
  * `title` string (可選) - 對話框視窗的標題
  * `defaultPath` string (可選) - 對話框的預設展示路徑
  * `buttonLabel` string (可選) - 「確認」按鈕的自定標籤, 當為空時, 將使用預設標籤。
  * `filters` [FileFilter](https://www.electronjs.org/zh/docs/latest/api/structures/file-filter)\[] (可選)
    * `name` string
    * `extensions` string\[]
  * `properties` string\[] (可選) - 包含對話框相關屬性。 支援以下屬性值:
    * `openFile` - 允許選擇檔案
    * `openDirectory` - 允許選擇資料夾
    * `multiSelections`- 允許多選。
    * `showHiddenFiles`- 顯示對話框中的隱藏檔案。
    * `createDirectory` `macOS` - 允許你透過對話框的形式新增新的目錄。
    * `promptToCreate` `Windows`- 如果輸入的檔案路徑在對話框中不存在, 則提示新增。 這並不是真的在路徑上新增一個檔案，而是允許返回一些不存在的地址交由應用程式去創
  * `message` string (可選) `macOS` - 顯示在輸入框上方的消息。
* 返回 `Promise<result: Object>`
  * `result`Object
    * `canceled` boolean - 對話框是否被取消
    * `filePaths` string\[] - 使用者選擇的檔案路徑的陣列。如果對話框被取消，這將是一個空的陣列。

```javascript
{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}
```

```javascript
let result = await eagle.dialog.showOpenDialog({
    properties: ['openFile', 'openDirectory']
});
```

{% hint style="info" %}
備註：此功能與 Electron API 的 [dialog.showOpenDialog](https://www.electronjs.org/zh/docs/latest/api/dialog#dialogshowopendialogbrowserwindow-options) 功能類似。
{% endhint %}

## showSaveDialog(options) <a href="#g872m" id="g872m"></a>

顯示儲存檔案對話框。

* `options` Object
  * `title` string (可選) - 對話框視窗的標題
  * `defaultPath` string (可選) - 對話框的預設展示路徑
  * `buttonLabel` string (可選) - 「確認」按鈕的自定標籤, 當為空時, 將使用預設標籤。
  * `filters` [FileFilter](https://www.electronjs.org/zh/docs/latest/api/structures/file-filter)\[] (可選)
    * `name` string
    * `extensions` string\[]
  * `properties` string\[] (可選) - 包含對話框相關屬性。 支援以下屬性值:
    * `openDirectory` - 允許選擇資料夾
    * `showHiddenFiles`- 顯示對話框中的隱藏檔案。
    * `createDirectory` `macOS` - 允許你透過對話框的形式新增新的目錄。
* 返回 `Promise<result: Object>`
  * `result`Object
    * `canceled` boolean - 對話框是否被取消
    * `filePath` string - 如果對話框被取消，該值為 `undefined`。

```javascript
{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}
```

```javascript
let result = await eagle.dialog.showSaveDialog({
    properties: ['openDirectory']
});
```

{% hint style="info" %}
備註：此功能與 Electron API 的 [dialog.showSaveDialog](https://www.electronjs.org/zh/docs/latest/api/dialog#dialogshowsavedialogbrowserwindow-options) 功能類似。
{% endhint %}

## showMessageBox(options) <a href="#grq5h" id="grq5h"></a>

顯示訊息對話框。

* `options`Object
  * `message` string - 對話框主要內容
  * `title` string (可選) - 對話框標題
  * `detail` string (可選) - 額外資訊
  * `buttons` strings\[] (可選) - 按鈕文字陣列
  * `type` string (可選) - 可以為 `none`、 `info`、 `error`、`question` 或者 `warning`
* 返回 `Promise<result: Object>`
  * `result`Object
    * `response` Interger - 點擊按鈕的索引

```javascript
let result = await eagle.dialog.showMessageBox({
    title: "Messagebox title",
    message: "Message from the Plugin process",
    detail: "Ultra message here",
    buttons: ["確定", "取消"],
    type: "info"
});

console.log(result);		// {response: 0}
```

{% hint style="info" %}
此功能與 Electron API 的 [dialog.showSaveDialog](https://www.electronjs.org/zh/docs/latest/api/dialog#dialogshowsavedialogbrowserwindow-options) 功能類似。
{% endhint %}

## showErrorBox(title, content) <a href="#erokr" id="erokr"></a>

顯示錯誤訊息的對話框。

* `title` string - 顯示在錯誤框中的標題
* `content` string - 顯示在錯誤框中的文字內容
* 返回 `Promise<void>`

{% code overflow="wrap" %}

```javascript
await eagle.dialog.showErrorBox("Error box title", "Error message from the Plugin process");
```

{% endcode %}

{% hint style="info" %}
備註：此功能與 Electron API 的 [dialog.showSaveDialog](https://www.electronjs.org/zh/docs/latest/api/dialog#dialogshowsavedialogbrowserwindow-options) 功能類似。
{% endhint %}

### &#x20;<a href="#nptwx" id="nptwx"></a>


---

# 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/dialog.md?ask=<question>
```

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.