useModal()

useModal() 提供命令式彈窗 API——在任意業務邏輯中直接 await 使用者的操作結果，無需在模板裡維護 v-model 狀態。彈窗由版面層註冊的 SwModalHost 負責渲染，業務代碼無需關心 DOM 掛載位置。

前提： 需在 app.vue 或當前版面中放置一次 <SwModalHost />。由 sw create 生成的專案已內建，無需手動添加。

基本用法

加载中...

<script setup lang="ts">
const modal = useModal()

async function handleDelete() {
  const confirmed = await modal.open({
    title: '確認刪除',
    description: '此操作不可撤銷，確定要繼續嗎？',
    confirmText: '刪除',
    cancelText: '取消',
  })
  if (confirmed) await deleteItem()
}
</script>

open() 返回 Promise<boolean>：使用者點確認 resolve true，點取消或關閉 resolve false。

常用場景

加载中...

純提示（隱藏取消按鈕）

傳空字串給 cancelText 隱藏取消按鈕：

await modal.open({
  title: '溫馨提示',
  description: '活動已結束，感謝參與。',
  confirmText: '知道了',
  cancelText: '',
})

自訂按鈕文字

const ok = await modal.open({
  title: '提交訂單',
  description: `本次金額：¥${total}`,
  confirmText: '立即付款',
  cancelText: '再想想',
})

回傳值

名稱	類型	說明
`state`	`DeepReadonly<Ref<ModalState \| null>>`	當前彈窗狀態（`null` 表示無彈窗，唯讀響應式）
`open`	`(options: ModalOptions) => Promise<boolean>`	打開彈窗，resolve 為使用者是否點擊確認
`close`	`(confirmed?: boolean) => void`	手動關閉彈窗，可傳結果（預設 `false`）

ModalOptions 參數

參數	類型	說明
`title`	`string`	彈窗標題
`description`	`string`	彈窗描述文字
`confirmText`	`string`	確認按鈕文字，預設 `"確認"`
`cancelText`	`string`	取消按鈕文字，預設 `"取消"`；傳 `''` 則隱藏按鈕

注意事項

同一時刻只有一個命令式彈窗，多次呼叫 open() 會覆蓋前一個
如需自訂複雜內容的彈窗（如表單），請改用宣告式 <SwModal> + v-model:open
close() 可在業務代碼中手動呼叫，預設傳 false（等同使用者點取消）