跳到內容
調色盤星雲光譜
選擇版面配色

即時套用,保留目前的亮暗模式。

Dialog (am-dialog)

am-dialog 使用原生 <dialog>,適合需要暫停目前流程的確認、設定與內容預覽。開啟時限制焦點在視窗內,關閉後將焦點還給觸發按鈕。

請先完成安裝與樣式匯入。以下範例含完整 imports、取消與模擬確認流程。

可取消與確認的 Alert

互動預覽

預覽與下方程式碼來自同一個 Astro 元件。複製到已載入 Astromer 樣式的頁面即可執行。

刪除示範專案?

這是互動示範,不會刪除任何資料。

請明確選擇取消或確認。正式刪除操作應先說明影響範圍。

尚未執行操作。

查看程式碼可複製完整範例
---
import Button from "@astromer/core/components/Button.astro";
import Dialog from "@astromer/core/components/Dialog.astro";
import DialogClose from "@astromer/core/components/DialogClose.astro";
import DialogFooterActions from "@astromer/core/components/DialogFooterActions.astro";
---
<alert-dialog-example>
<Dialog variant="alert" size="sm">
<Button slot="trigger">試用刪除確認</Button>
<Fragment slot="title">刪除示範專案?</Fragment>
<Fragment slot="description">這是互動示範,不會刪除任何資料。</Fragment>
<p>請明確選擇取消或確認。正式刪除操作應先說明影響範圍。</p>
<DialogFooterActions slot="footer" stackOnMobile={true}>
<DialogClose autofocus>取消</DialogClose>
<Button class="am-dialog-action am-dialog-action--danger" data-confirm>
確認(僅模擬)
</Button>
</DialogFooterActions>
</Dialog>
<p role="status" aria-live="polite" data-result>尚未執行操作。</p>
</alert-dialog-example>
<script>
class AlertDialogExample extends HTMLElement {
connectedCallback() {
if (this.dataset.initialized) return;
const dialog = this.querySelector<HTMLDialogElement>("dialog");
const trigger = this.querySelector<HTMLButtonElement>("[data-dialog-trigger] button");
const confirm = this.querySelector<HTMLButtonElement>("[data-confirm]");
const result = this.querySelector<HTMLElement>("[data-result]");
if (!dialog || !trigger || !confirm || !result) return;
this.dataset.initialized = "true";
trigger.addEventListener("click", () => {
dialog.returnValue = "";
});
confirm.addEventListener("click", () => {
// 示範只有本機狀態;真實 API 應成功後才關閉,失敗時留在視窗內顯示錯誤。
dialog.close("confirmed");
});
dialog.addEventListener("close", () => {
result.textContent =
dialog.returnValue === "confirmed"
? "已完成模擬確認,沒有刪除資料。"
: "已取消,專案保留。";
// Dialog 元件會將焦點還給本次開啟它的按鈕。
});
}
}
if (!customElements.get("alert-dialog-example")) {
customElements.define("alert-dialog-example", AlertDialogExample);
}
</script>

alert 預設停用 Esc、背景點擊與右上角關閉圖示,因此必須提供明確的退出操作。範例讓「取消」先取得焦點,以免誤觸確認;「確認(僅模擬)」呼叫原生 dialog.close("confirmed"),再由 close 事件更新畫面狀態。

DialogClose 只負責關閉,不會執行刪除或儲存。真實操作由頁面自己的事件處理器執行:送出時停用重複操作,成功後再關閉,失敗時保留對話框並提供可讀的錯誤與重試方式。不要將 data-dialog-close 加在需要等待 API 回應的確認按鈕上,否則會立即關閉。

PreviewDialog.astro
---
import Button from "@astromer/core/components/Button.astro";
import Dialog from "@astromer/core/components/Dialog.astro";
import DialogClose from "@astromer/core/components/DialogClose.astro";
import DialogFooterActions from "@astromer/core/components/DialogFooterActions.astro";
---
<Dialog variant="preview" size="xl" closeLabel="關閉預覽">
<Button slot="trigger" variant="outline">預覽草稿</Button>
<Fragment slot="title">活動草稿</Fragment>
<Fragment slot="description">確認內容後,關閉視窗繼續編輯。</Fragment>
<p>這裡放置活動內容、摘要或圖片。</p>
<DialogFooterActions slot="footer">
<DialogClose emphasis="primary">繼續編輯</DialogClose>
</DialogFooterActions>
</Dialog>
variant 用途 預設關閉方式
modal 一般確認、短表單 關閉圖示、背景點擊、Esc
alert 需要明確選擇的重要確認 由 footer 提供取消與確認
sheet 設定、側邊編輯 關閉圖示、背景點擊、Esc;預設靠右
preview 內容、圖片或摘要預覽 關閉圖示、背景點擊、Esc
屬性 型別/可選值 預設
variant modal、alert、sheet、preview modal
size sm、md、lg、xl、full md
placement center、top、bottom、left、right sheet 為 right,其餘 center
showCloseButton boolean alert 為 false,其餘 true
closeLabel string,關閉圖示的無障礙名稱 Close dialog,中文頁面請覆寫
closeOnClickOutside boolean alert 為 false,其餘 true
closeOnEsc boolean alert 為 false,其餘 true
role dialog、alertdialog alert 為 alertdialog,其餘 dialog
titleId string title slot 的自動 ID
descriptionId string description slot 的自動 ID
ariaLabel string,沒有 title slot 或 titleId 時使用 無
class string 無

使用自訂 header 時,titleId 與 descriptionId 可指向自己提供的標題、說明元素。每個視窗都應使用 title slot、titleId 或 ariaLabel 提供名稱。

Slot 用途
trigger 開啟視窗的按鈕;請使用可取得焦點的元素
header 額外標頭內容,例如狀態標籤
title 視窗標題,自動連結 aria-labelledby
description 簡短說明,自動連結 aria-describedby
default 主要內容
footer 取消、確認或其他操作

DialogClose 使用標準 Button,保留 am-dialog-action 樣式與 data-dialog-close 行為。emphasis="primary" 對應實心主色;secondary(預設)使用外框;danger 使用錯誤色。圓角、40px 高度與字重和中尺寸 Button 一致,也支援原生 button 屬性,例如 autofocus、disabled 與 aria-label。

DialogFooterActions 的 align 支援 start | center | end | between(預設 end);stackOnMobile={true} 會在窄螢幕將操作按鈕垂直排列。既有 .am-dialog-action--primary / --secondary / --danger class 仍可用於自己的按鈕。

  • 觸發按鈕支援 Enter、Space;開啟後以 Tab/Shift+Tab 在視窗內移動。
  • 一般視窗可按 Esc 關閉;alert 預設必須使用自己的取消或確認操作。
  • 關閉後焦點會回到本次觸發按鈕。重要確認應讓非破壞性的操作先取得焦點。
  • 元件使用瀏覽器原生 modal dialog 行為,沒有框架專用的受控 open API。需要自行控制時可取得內部 HTMLDialogElement,使用 showModal()、close() 與 close 事件。
  • 驗證、非同步送出、成功/失敗狀態及資料異動由應用程式負責;元件不會自動儲存。

完整版型比較見 Dialog Playground。