對話框插件 | Quasar 框架

Dialog 插件

Quasar Dialogs 是提供使用者選擇特定動作或一系列動作的絕佳方式。它們還可以向使用者提供重要資訊，或要求他們做出決定（或多項決定）。

從 UI 的角度來看，您可以將 Dialogs 視為一種浮動式模組，僅覆蓋螢幕的一部分。這表示 Dialogs 應僅用於快速使用者動作。

提示

Dialogs 也可以在您的 Vue 檔案範本中作為元件使用（用於複雜的使用案例，例如特定的表單元件、可選選項等）。為此，請前往 QDialog 頁面。

使用 Dialogs 作為 Quasar 插件而不是 QDialog 元件的優勢在於，該插件也可以從 Vue 空間外部調用，並且不需要您管理其範本。但因此，它們的自訂程度無法與元件版本相比。

然而，您也可以為 Dialog 插件提供要渲染的元件（請參閱「調用自訂元件」章節），這是一種避免使用內嵌對話框弄亂 Vue 範本的好方法（這也有助於您更好地組織專案檔案並重複使用對話框）。

使用 QDialog 插件，您可以使用以下表單內容以程式設計方式建置三種類型的對話框

提示對話框 - 要求使用者在輸入欄位中填寫某種類型的資料。
一組選項，供使用者使用單選按鈕或切換鈕（僅限單選）或複選框（用於多選）進行選擇。
簡單的確認對話框，使用者可以在其中取消或對特定動作或輸入給予「確定」。

為了建立 #1，即提示輸入表單，您需要在 opts 物件中使用 prompt 屬性。

為了建立 #2，即選項選擇表單，您需要在 opts 物件中使用 options 屬性。

Quasar CLI

Vite 插件 / Vue CLI

UMD

// quasar.config file

return {
  framework: {
    plugins: [
      'Dialog'
    ]
  }
}

內建元件

import { Dialog } from 'quasar'
(Object) Dialog.create({ ... })

// inside of a Vue file
import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar()
  $q.dialog({ ... }) // returns Object
}

請查看 API 卡，以了解傳回的物件是什麼。

用法

提示

對於以下所有範例，在您查看它們時，也請查看瀏覽器控制台。

警告

這不是您可以使用 Dialogs 作為 Quasar 插件所能做的一切的完整列表。如需進一步探索，請查看 API 章節。

原生屬性

您也可以將原生 HTML 屬性提供給內部的 QInput 或 QOptionGroup 元件，如下例所示。

使用者輸入驗證

有一個基本的驗證系統供您使用，以便在填寫預期值之前，使用者將無法提交對話框（點擊/點擊「確定」或按 Enter 鍵）。

進度

使用 HTML

如果您指定 html: true 屬性，則可以在標題和訊息中使用 HTML。請注意，這可能會導致 XSS 攻擊，因此請務必自行清理訊息。

調用自訂元件

您也可以調用自己的自訂元件，而不是依賴 Dialog 插件預設提供的元件。但在這種情況下，您將負責處理所有事情（包括您自己的元件 props）。

此功能實際上是 Dialog 插件的「命脈」。它透過輕鬆分離和重複使用對話框的功能，幫助您保持其他 vue 元件 html 範本的清潔。

觸發自訂元件

透過匯入 Dialog

使用 useQuasar()

/**
 * This way of using it can reside outside
 * of a Vue component as well
 */

import { Dialog } from 'quasar'
import CustomComponent from '..path.to.component..'

Dialog.create({
  component: CustomComponent,

  // props forwarded to your custom component
  componentProps: {
    text: 'something',
    persistent: true,
    // ...more..props...
  }
}).onOk(() => {
  console.log('OK')
}).onCancel(() => {
  console.log('Cancel')
}).onDismiss(() => {
  console.log('Called on OK or Cancel')
})

上述使用 Options API 的等效方法是直接使用 this.$q.dialog({ ... })。

警告

然而，您的自訂元件必須遵循以下描述的介面，才能完美地掛鉤到 Dialog 插件。請注意「REQUIRED」註解，並按原樣理解 - 這只是一個最基本的範例，僅此而已。

編寫自訂元件

具有「script setup」和 Composition API 變體的 SFC

我們將使用 useDialogPluginComponent composable。

<template>
  <q-dialog ref="dialogRef" @hide="onDialogHide">
    <q-card class="q-dialog-plugin">
      <!--
        ...content
        ... use q-card-section for it?
      -->

      <!-- buttons example -->
      <q-card-actions align="right">
        <q-btn color="primary" label="OK" @click="onOKClick" />
        <q-btn color="primary" label="Cancel" @click="onDialogCancel" />
      </q-card-actions>
    </q-card>
  </q-dialog>
</template>

<script setup>
import { useDialogPluginComponent } from 'quasar'

const props = defineProps({
  // ...your custom props
})

defineEmits([
  // REQUIRED; need to specify some events that your
  // component will emit through useDialogPluginComponent()
  ...useDialogPluginComponent.emits
])

const { dialogRef, onDialogHide, onDialogOK, onDialogCancel } = useDialogPluginComponent()
// dialogRef      - Vue ref to be applied to QDialog
// onDialogHide   - Function to be used as handler for @hide on QDialog
// onDialogOK     - Function to call to settle dialog with "ok" outcome
//                    example: onDialogOK() - no payload
//                    example: onDialogOK({ /*...*/ }) - with payload
// onDialogCancel - Function to call to settle dialog with "cancel" outcome

// this is part of our example (so not required)
function onOKClick () {
  // on OK, it is REQUIRED to
  // call onDialogOK (with optional payload)
  onDialogOK()
  // or with payload: onDialogOK({ ... })
  // ...and it will also hide the dialog automatically
}
</script>

如果您想以物件形式定義 emits，則（需要 Quasar v2.2.5+）

defineEmits({
  // REQUIRED; need to specify some events that your
  // component will emit through useDialogPluginComponent()
  ...useDialogPluginComponent.emitsObject,

  // ...your own definitions
})

具有「script」和 Composition API 變體的 SFC

我們將使用 useDialogPluginComponent composable。

<template>
  <!-- notice dialogRef here -->
  <q-dialog ref="dialogRef" @hide="onDialogHide">
    <q-card class="q-dialog-plugin">
      <!--
        ...content
        ... use q-card-section for it?
      -->

      <!-- buttons example -->
      <q-card-actions align="right">
        <q-btn color="primary" label="OK" @click="onOKClick" />
        <q-btn color="primary" label="Cancel" @click="onCancelClick" />
      </q-card-actions>
    </q-card>
  </q-dialog>
</template>

<script>
import { useDialogPluginComponent } from 'quasar'

export default {
  props: {
    // ...your custom props
  },

  emits: [
    // REQUIRED; need to specify some events that your
    // component will emit through useDialogPluginComponent()
    ...useDialogPluginComponent.emits
  ],

  setup () {
    // REQUIRED; must be called inside of setup()
    const { dialogRef, onDialogHide, onDialogOK, onDialogCancel } = useDialogPluginComponent()
    // dialogRef      - Vue ref to be applied to QDialog
    // onDialogHide   - Function to be used as handler for @hide on QDialog
    // onDialogOK     - Function to call to settle dialog with "ok" outcome
    //                    example: onDialogOK() - no payload
    //                    example: onDialogOK({ /*.../* }) - with payload
    // onDialogCancel - Function to call to settle dialog with "cancel" outcome

    return {
      // This is REQUIRED;
      // Need to inject these (from useDialogPluginComponent() call)
      // into the vue scope for the vue html template
      dialogRef,
      onDialogHide,

      // other methods that we used in our vue html template;
      // these are part of our example (so not required)
      onOKClick () {
        // on OK, it is REQUIRED to
        // call onDialogOK (with optional payload)
        onDialogOK()
        // or with payload: onDialogOK({ ... })
        // ...and it will also hide the dialog automatically
      },

      // we can passthrough onDialogCancel directly
      onCancelClick: onDialogCancel
    }
  }
}
</script>

如果您想以物件形式定義 emits，則（需要 Quasar v2.2.5+）

emits: {
  // REQUIRED; need to specify some events that your
  // component will emit through useDialogPluginComponent()
  ...useDialogPluginComponent.emitsObject,

  // ...your own definitions
}

具有「script」和 Options API 變體的 SFC

<template>
  <q-dialog ref="dialog" @hide="onDialogHide">
    <q-card class="q-dialog-plugin">
      <!--
        ...content
        ... use q-card-section for it?
      -->

      <!-- buttons example -->
      <q-card-actions align="right">
        <q-btn color="primary" label="OK" @click="onOKClick" />
        <q-btn color="primary" label="Cancel" @click="onCancelClick" />
      </q-card-actions>
    </q-card>
  </q-dialog>
</template>

<script>
export default {
  props: {
    // ...your custom props
  },

  emits: [
    // REQUIRED
    'ok', 'hide'
  ],

  methods: {
    // following method is REQUIRED
    // (don't change its name --> "show")
    show () {
      this.$refs.dialog.show()
    },

    // following method is REQUIRED
    // (don't change its name --> "hide")
    hide () {
      this.$refs.dialog.hide()
    },

    onDialogHide () {
      // required to be emitted
      // when QDialog emits "hide" event
      this.$emit('hide')
    },

    onOKClick () {
      // on OK, it is REQUIRED to
      // emit "ok" event (with optional payload)
      // before hiding the QDialog
      this.$emit('ok')
      // or with payload: this.$emit('ok', { ... })

      // then hiding dialog
      this.hide()
    },

    onCancelClick () {
      // we just need to hide the dialog
      this.hide()
    }
  }
}
</script>

Cordova/Capacitor 返回按鈕

Quasar 預設會為您處理返回按鈕，因此它可以隱藏任何已開啟的 Dialogs，而不是返回上一頁的預設行為（這不是一個好的使用者體驗）。

但是，如果您希望停用此行為，請編輯您的 /quasar.config 檔案

適用於 Capacitor

適用於 Cordova

// quasar.config file
return {
  framework: {
    config: {
      capacitor: {
        // Quasar handles app exit on mobile phone back button.
        backButtonExit: true/false/'*'/['/login', '/home', '/my-page'],

        // On the other hand, the following completely
        // disables Quasar's back button management.
        backButton: true/false
      }
    }
  }
}

發現錯誤了嗎？在瀏覽器中編輯此頁面

1. 介紹

2. Dialog API

3. 安裝

4. 內建元件

4.1. 用法

4.2. 原生屬性

4.3. 使用者輸入驗證

4.4. 進度

4.5. 使用 HTML

5. 調用自訂元件

5.1. 觸發自訂元件

5.2. 編寫自訂元件

6. Cordova/Capacitor 返回按鈕