> For the complete documentation index, see [llms.txt](https://developer.eagle.cool/plugin-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.eagle.cool/plugin-api/zh-tw/api/dialog.md).

# 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>