最新Quasar 指南6：9527字带你了解Quasar vue组合式函数核心用法及实战 - Quasar 完全教程：从基础到实战 --Ryan

最新推荐文章于 2025-12-18 14:39:46 发布

原创最新推荐文章于 2025-12-18 14:39:46 发布 · 1.5k 阅读

25 ·

CC 4.0 BY-SA版权

文章标签：

#vue.js #前端 #javascript

useQuasar 组合式函数核心总结

一、核心作用

useQuasar 是 Quasar 框架提供的组合式函数，核心用途是在 Vue 3 的 setup 语法中获取 $q 全局对象，进而访问 Quasar 的平台信息、版本号、插件实例等核心能力。

二、基础用法

1. 导入与调用

import { useQuasar } from 'quasar'

setup () {
  const $q = useQuasar() // 获取 $q 实例
}

2. 核心访问能力

平台判断：通过 $q.platform.is 访问设备 / 浏览器信息（如 $q.platform.is.ios 判断是否为 iOS 设备）；
版本查询：$q.version 可获取当前 Quasar 框架版本；
插件访问：直接通过 $q.插件名 调用已启用的插件（如 $q.notify、$q.dialog）。

3. 模板中使用

获取 $q 实例后可直接在模板中引用相关属性：

<template>
  <!-- 仅在 iOS 设备上渲染 -->
  <div v-if="$q.platform.is.ios">iOS 专属内容</div>
</template>

三、关键特性

适配 Vue 3 组合式 API：专为 setup 语法设计，替代 Vue 2 中的 this.$q；
全局能力集中访问：无需单独导入平台判断、插件等模块，通过 $q 一站式获取；
轻量无依赖：仅用于实例访问，不额外增加项目体积。

useDialogPluginComponent 组合式函数教程（Quasar CLI 版）

一、核心作用

useDialogPluginComponent 是 Quasar 专为自定义弹窗组件设计的组合式函数，用于快速对接 Quasar 的 Dialog 插件体系，让自定义组件具备 Dialog 插件的核心能力（如关闭逻辑、数据传递、弹窗生命周期管理），无需手动封装关闭 / 确认回调。

二、适用场景

当默认 Dialog 插件的预定义弹窗（Alert/Confirm/Prompt）无法满足需求（如复杂表单、自定义布局）时，用该函数封装自定义 Vue 组件，使其能通过 $q.dialog() 调用，和原生 Dialog 插件用法一致。

三、基础使用步骤（Quasar CLI 项目）

在 src/page/ 下新建自定义弹窗组件（如 CustomDialog.vue）：

<template>
  <!-- 绑定 dialogRef，监听 hide 事件 -->
  <q-dialog ref="dialogRef" @hide="onDialogHide">
    <q-card class="q-dialog-plugin" style="width: 500px; max-width: 90vw;">
      <!-- 弹窗标题 -->
      <q-card-section>
        <h5 class="text-subtitle1">新增用户</h5>
      </q-card-section>

      <!-- 表单内容 -->
      <q-card-section>
        <q-input
          v-model="form.name"
          label="用户名"
          placeholder="请输入用户名"
          :rules="[val => !!val || '用户名不能为空']"
          class="mb-4"
        />
        <q-input
          v-model="form.email"
          label="邮箱"
          placeholder="请输入邮箱"
          :rules="[
            val => !!val || '邮箱不能为空',
            /*val => /^\\w+([.-]?\\w+)*@\\w+([.-]?\\w+)*(.\\w{2,3})+$/.test(val) || '邮箱格式错误'*/
          ]"
        />
      </q-card-section>

      <!-- 操作按钮 -->
      <q-card-actions align="right" class="p-4">
        <q-btn color="grey" label="取消" @click="onCancelClick" flat />
        <q-btn color="primary" label="确认提交" @click="onOKClick" />
      </q-card-actions>
    </q-card>
  </q-dialog>
</template>

<script>
import { ref } from 'vue'
import { useDialogPluginComponent, useQuasar } from 'quasar'

export default {
  // 接收外部传入的初始数据（可选）
  props: {
    initUser: {
      type: Object,
      default: () => ({ name: '', email: '' })
    }
  },

  // 必须声明 useDialogPluginComponent 所需的事件
  emits: [
    ...useDialogPluginComponent.emits
  ],

  setup (props) {
    const $q = useQuasar()
    // 1. 调用组合式函数，获取核心方法/引用
    const { dialogRef, onDialogHide, onDialogOK, onDialogCancel } = useDialogPluginComponent({
      // 弹窗挂载时初始化表单数据（可选）
      onDialogMounted: () => {
        form.value = { ...props.initUser }
      }
    })

    // 2. 定义表单数据
    const form = ref({
      name: '',
      email: ''
    })

    // 3. 确认按钮点击逻辑（带表单校验）
    const onOKClick = () => {
      // 手动触发表单校验（简化版，也可结合 QForm 组件校验）
      if (!form.value.name) {
        $q.notify({ type: 'negative', message: '请填写用户名' })
        return
      }
      /*if (!/^\\w+([.-]?\\w+)*@\\w+([.-]?\\w+)*(.\\w{2,3})+$/.test(form.value.email)) {
        $q.notify({ type: 'negative', message: '邮箱格式错误' })
        return
      }*/

      // 校验通过：触发 OK 事件，传递表单数据给外部
      onDialogOK({
        name: form.value.name,
        email: form.value.email,
        id: Date.now() // 模拟生成唯一ID
      })
    }

    // 4. 弹窗隐藏后的清理逻辑（可选）
    const handleDialogHide = () => {
      onDialogHide() // 执行内置的 hide 逻辑
      form.value = { name: '', email: '' } // 重置表单
    }

    return {
      // 必须暴露的核心引用/方法
      dialogRef,
      onDialogHide: handleDialogHide, // 覆盖为自定义的 hide 逻辑

      // 表单数据与操作方法
      form,
      onOKClick,
      onCancelClick: onDialogCancel // 直接透传取消方法
    }
  }
}
</script>

<template>
  <q-page class="row items-center justify-center">
    <!-- 触发弹窗的按钮 -->
    <q-btn
      label="打开新增用户弹窗"
      color="primary"
      @click="openCustomDialog"
    />

    <!-- 展示弹窗返回的数据 -->
    <div class="mt-6">
      <h6>已新增用户：</h6>
      <pre>{{ userList }}</pre>
    </div>
  </q-page>
</template>

<script>
import { ref } from 'vue'
import { useQuasar } from 'quasar'
import CustomFormDialog from './CustomFormDialog.vue'

export default {
  setup () {
    const $q = useQuasar()
    // 模拟用户列表
    const userList = ref([])

    // 打开自定义弹窗
    const openCustomDialog = () => {
      $q.dialog({
        component: CustomFormDialog, // 指定自定义弹窗组件
        // 传递初始数据给弹窗（可选）
        initUser: { name: '默认名称', email: 'demo@test.com' },
        // Dialog 基础配置（可选）
        persistent: true, // 点击外部不关闭弹窗
        maximized: false
      })
        // 弹窗确认回调（接收子组件传递的参数）
        .onOk((userData) => {
          userList.value.push(userData)
          $q.notify({
            type: 'positive',
            message: `新增用户 ${userData.name} 成功`
          })
        })
        // 弹窗取消回调
        .onCancel(() => {
          $q.notify({
            type: 'info',
            message: '已取消新增用户'
          })
        })
    }

    return {
      userList,
      openCustomDialog
    }
  }
}
</script>

四、核心 API 解析

1. useDialogPluginComponent 返回值

方法 / 属性	作用
`dialogRef`	必须绑定到 `<q-dialog>` 的 ref，用于 Dialog 插件控制弹窗显示 / 隐藏
`onDialogOK(data)`	触发弹窗 “确认”，可传递数据给外部，自动关闭弹窗
`onDialogCancel()`	触发弹窗 “取消”，自动关闭弹窗
`onDialogHide(cb)`	注册弹窗隐藏后的回调（清理数据、重置状态）

2. useDialogPluginComponent 配置项

配置项	类型	作用
`onDialogMounted(opts)`	函数	弹窗挂载时触发，`opts` 为外部调用时传入的所有参数（如 initData）
`onDialogBeforeShow(opts)`	函数	弹窗显示前触发，可修改弹窗配置
`onDialogHide()`	函数	弹窗隐藏时触发，用于清理状态

五、关键注意事项

模板必选结构：自定义弹窗组件外层必须用 <q-dialog> 包裹，且 ref 必须绑定为 dialogRef（组合式函数返回的 ref）；
数据传递：外部向弹窗传值用 initData，弹窗向外部传值通过 onDialogOK(data)；
关闭逻辑：必须通过 onDialogOK/onDialogCancel 关闭弹窗，不能直接调用 dialogRef.value.hide()；
样式适配：自定义弹窗建议设置 max-width: 90vw，适配移动端屏幕；
SSR 兼容：该组合式函数完全支持服务端渲染，无需额外配置。

六、高级用法：异步确认逻辑

若弹窗确认需要异步操作（如接口请求），可在 onConfirm 中处理：

// CustomDialog.vue 中修改确认逻辑
const onConfirm = async () => {
  if (!form.value.name) {
    return $q.notify({ type: 'negative', message: '姓名不能为空' })
  }
  
  // 显示加载中
  $q.loading.show('提交中...')
  try {
    // 模拟接口请求
    await new Promise(resolve => setTimeout(resolve, 1000))
    onDialogOK(form.value) // 异步完成后触发确认
  } catch (err) {
    $q.notify({ type: 'negative', message: '提交失败' })
  } finally {
    $q.loading.hide()
  }
}

useFormChild 组合式函数教程（Quasar CLI 版）

一、核心作用

useFormChild 是 Quasar 专为表单组件拆分设计的组合式函数，解决 “父表单 + 子表单组件” 的联动问题：让子表单组件能接入父表单的验证、提交、重置逻辑，无需手动传递表单状态 / 方法，实现表单的模块化拆分与统一管理。

二、适用场景

当表单结构复杂（如包含多个业务模块：用户信息、收货地址、支付方式），需要拆分为多个子组件时，用该函数让子表单 “融入” 父表单，父表单可统一控制所有子表单的验证、重置，子表单的校验状态也会同步到父表单。

三、核心原理

父表单通过 Quasar 的 useForm（或 QForm 组件）管理整体状态，子表单组件通过 useFormChild 注册到父表单上下文，自动关联校验规则、提交 / 重置事件，实现父子表单的 “无缝联动”。

四、完整使用示例（Quasar CLI 项目）

步骤 1：创建子表单组件（如 UserInfoForm.vue）

<!-- src/components/UserInfoForm.vue -->
<template>
  <div>
    <!-- 子表单的表单项 -->
    <q-input v-model="form.name" label="姓名" :rules="[$rules.required]" hint="必填项" />
    <q-input
      v-model="form.phone"
      label="手机号"
      :rules="[$rules.required, $rules.phone]"
      style="margin-top: 12px"
    />
  </div>
</template>

<script setup>
import {  ref } from 'vue'
import { useFormChild, useQuasar } from 'quasar'

const $q = useQuasar()
// 1. 定义子表单数据
const form = ref({
  name: '',
  phone: '',
})

// 2. 定义子表单校验规则（可复用 Quasar 内置规则）
const $rules = {
  required: (val) => !!val || '此项不能为空',
  phone: (val) => /^1[3-9]\d{9}$/.test(val) || '手机号格式错误',
}

// 3. 调用 useFormChild，注册到父表单上下文
 useFormChild({
  // 必传：子表单的校验方法（触发父表单验证时会调用）
  validate: () => {
    // 手动校验所有表单项（也可通过 QForm 内置校验）
    const nameValid = $rules.required(form.value.name)
    const phoneValid = $rules.phone(form.value.phone)
    if (nameValid !== true) {
      $q.notify({ type: 'negative', message: nameValid })
      return false
    }
    if (phoneValid !== true) {
      $q.notify({ type: 'negative', message: phoneValid })
      return false
    }
    return true
  },
})

// 可选：暴露子表单数据（父表单可主动获取）
defineExpose({ form })
</script>

步骤 2：创建父表单页面（如 OrderFormPage.vue）

<!-- src/pages/OrderFormPage.vue -->
<template>
  <!-- 父表单：用 QForm 组件管理整体状态 -->
  <q-form ref="formRef" @submit="onSubmit" @reset="onReset">
    <q-card style="padding: 20px; max-width: 600px; margin: 0 auto;">
      <!-- 引入子表单组件（自动接入父表单上下文） -->
      <UserInfoForm />

      <!-- 父表单自有表单项 -->
      <q-input
        v-model="parentForm.address"
        label="收货地址"
        :rules="[$rules.required]"
        style="margin-top: 12px;"
      />

      <!-- 表单操作按钮 -->
      <div style="margin-top: 20px; display: flex; gap: 10px;">
        <q-btn label="重置" type="reset" color="grey" />
        <q-btn label="提交" type="submit" color="primary" />
      </div>
    </q-card>
  </q-form>
</template>

<script setup>
import { ref } from 'vue'
import { useQuasar } from 'quasar'
import UserInfoForm from './UserInfoForm.vue'

const $q = useQuasar()
// 1. 父表单 ref（关联 QForm 组件）
const formRef = ref(null)

// 2. 父表单数据
const parentForm = ref({
  address: ''
})

// 3. 父表单校验规则
const $rules = {
  required: val => !!val || '此项不能为空'
}

// 4. 父表单提交逻辑（会自动触发所有子表单的 validate + onSubmit）
const onSubmit = () => {
  // 父表单校验通过 + 所有子表单校验通过，才会执行到这里
  console.log('表单提交成功：', {
    userInfo: formRef.value?.$children[0]?.form, // 获取子表单数据
    address: parentForm.value.address
  })
  $q.notify({ type: 'positive', message: '表单提交成功' })
}

// 5. 父表单重置逻辑（会自动触发所有子表单的 reset）
const onReset = () => {
  parentForm.value = { address: '' }
  $q.notify({ type: 'info', message: '表单已重置' })
}
</script>

五、核心 API 解析

1. useFormChild 入参（必选 / 可选）

配置项	类型	是否必选	作用
`validate`	Function	是	子表单的校验方法，返回 `true` 表示校验通过，`false` 表示失败；父表单提交 / 校验时会自动调用
`reset`	Function	否	子表单的重置方法，父表单触发重置（`type="reset"` 或 `formRef.value.reset()`）时自动调用
`onSubmit`	Function	否	子表单提交前钩子，返回 `true` 允许父表单继续提交，`false` 终止提交；父表单提交时触发
`onReset`	Function	否	子表单重置后钩子，父表单重置完成后触发

2. useFormChild 返回值

方法	作用
`validate`	手动触发子表单校验（同入参的 validate 方法）
`reset`	手动触发子表单重置（同入参的 reset 方法）
`isValid`	响应式布尔值，标识子表单当前校验状态（需手动更新）

六、关键注意事项

上下文关联：子表单组件必须嵌套在父表单的 QForm 组件内部，否则 useFormChild 无法找到父表单上下文；
校验逻辑：子表单的 validate 方法必须返回布尔值（true/false），父表单会根据所有子表单的校验结果决定是否提交；
重置逻辑：父表单的 type="reset" 按钮或 formRef.value.reset() 会自动触发所有子表单的 reset 方法；
数据通信：父表单可通过组件 ref 获取子表单暴露的数据（如示例中 formRef.value?.$children[0]?.form），也可通过 Vue 的 provide/inject 自定义传参；
多个子表单：支持在一个父表单中嵌套多个 useFormChild 注册的子表单，父表单会依次校验所有子表单；
与 useForm 配合：若父表单使用 useForm 组合式函数（而非 QForm 组件），子表单的 useFormChild 仍可正常关联上下文。

useMeta 组合式函数核心总结

一、核心作用

useMeta 是 Quasar 框架中用于管理页面元信息的组合式函数，作为 Meta 插件的补充，专为 Vue 3 setup 语法设计，支持静态 / 动态配置页面标题、<meta> 标签等元信息，适配 SSR 和 SPA 项目，优化 SEO 表现。

二、基础用法

1. 静态配置（非响应式）

直接传入元信息配置对象，适用于无需动态变更的场景：

import { useMeta } from 'quasar'

setup () {
  useMeta({
    title: '静态页面标题',
    meta: {
      description: { name: 'description', content: '静态页面描述' },
      keywords: { name: 'keywords', content: 'Quasar,useMeta,SEO' }
    }
  })
}

2. 动态配置（响应式）

传入函数（内部转为 Vue 计算属性），依赖组件内响应式数据，数据变化时自动更新元信息：

import { ref } from 'vue'
import { useMeta } from 'quasar'

setup () {
  const pageTitle = ref('初始标题')

  // 响应式配置：pageTitle 变化时自动更新页面标题
  useMeta(() => ({
    title: pageTitle.value,
    meta: {
      description: { name: 'description', content: `当前页面：${pageTitle.value}` }
    }
  }))

  // 修改响应式数据，触发元信息更新
  const updateTitle = () => {
    pageTitle.value = '更新后的标题'
  }

  return { updateTitle }
}

三、核心特性

适配组合式 API：专为 Vue 3 setup 语法设计，替代组件选项中的 meta 属性；
响应式联动：动态配置依赖的响应式数据变更时，元信息自动同步更新，无需手动触发；
配置格式兼容：支持的元信息配置项与 Meta 插件一致（title、meta、link、script 等）；
场景适配：同时支持 SSR（服务器端渲染）和 SPA（单页应用），SSR 中可由服务器直接输出元信息。

四、关键注意事项

配置优先级：与 Meta 插件的组件选项 meta 冲突时，useMeta 配置优先级更高；
静态 vs 动态：静态配置仅初始化一次，动态配置需通过函数返回对象，确保响应式生效；
数据依赖：动态配置函数内可引用组件内的响应式数据（ref/reactive）、计算属性等；
兼容性：需确保已在 quasar.config.js 中启用 Meta 插件，否则 useMeta 无法生效。

五、实战示例（结合路由动态更新

// src/pages/ProductPage.vue
import { ref, onMounted } from 'vue'
import { useMeta } from 'quasar'
import { useRoute } from 'vue-router'

setup () {
  const route = useRoute()
  const productName = ref('')

  // 监听路由参数，获取产品名称
  onMounted(() => {
    productName.value = route.params.name || '未知产品'
  })

  // 动态设置产品页元信息
  useMeta(() => ({
    title: `${productName.value} - 产品详情`,
    meta: {
      description: { name: 'description', content: `${productName.value}的详细介绍，欢迎选购` },
      keywords: { name: 'keywords', content: `${productName.value},产品详情,Quasar` }
    }
  }))

  return { productName }
}