Dialog (am-dialog)

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

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

可操作範例

預覽與下方程式碼來自同一個 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 回應的確認按鈕上，否則會立即關閉。

內容預覽

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

Props

屬性	型別／可選值	預設
`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 提供名稱。

Slots

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。