App Extension Prompts API

本页面介绍 /ae/src/prompts.js|ts 文件，它负责处理安装 App Extension 时的交互提示。并非所有 App Extension 都需要提示——这是一个可选步骤。

用户的回答会存储在 /quasar.extensions.json（项目根目录）中，除非你确实清楚自己在做什么，否则不应手动修改该文件。

文件的基本结构示例：

import { definePromptsScript } from '#q-app'

export default definePromptsScript(async (/* api */) => {
  /**
   * 使用 @clack/prompts、inquirer 或任何你喜欢的提示库
   * （确保在 /ae 中通过 PNPM 安装对应的包）
   * 向用户提问，然后返回回答对象
   */

  const answers = /* ...向用户提问... */

  // type PromptsScriptAnswers<Key extends string = string> = Record<Key, any>
  return answers
})

你可以在 Install、Index 和 Uninstall 中通过 api.prompts 访问你的 App Extension 的回答。

API 参数

api.ctx

与 /quasar.config 文件中的 ctx 相同。

{
  appPaths: {
    cliDir: '...absolute path of it',
    appDir: '...absolute path of it',
    srcDir: '...absolute path of it',
    publicDir: '...absolute path of it',
    pwaDir: '...absolute path of it',
    ssrDir: '...absolute path of it',
    cordovaDir: '...absolute path of it',
    capacitorDir: '...absolute path of it',
    electronDir: '...absolute path of it',
    bexDir: '...absolute path of it',
    quasarConfigFilename: '...absolute path of the quasar.config file',
    quasarConfigInputFormat: 'js', // or 'ts'
    resolve: {
      cli: (...paths) => theAbsolutePathToCliDir,
      app: (...paths) => theAbsolutePathToAppDir,
      src: (...paths) => theAbsolutePathToAppSrcDir,
      public: (...paths) => theAbsolutePathToPublicDir,
      pwa: (...paths) => theAbsolutePathToAppSrcPwaDir,
      ssr: (...paths) => theAbsolutePathToAppSrcSsrDir,
      cordova: (...paths) => theAbsolutePathToAppSrcCordovaDir,
      capacitor: (...paths) => theAbsolutePathToAppSrcCapacitorDir,
      electron: (...paths) => theAbsolutePathToAppSrcElectronDir,
      bex: (...paths) => theAbsolutePathToAppSrcBexDir
    }
  }
}

api.extId

包含此 App Extension 的 ext-id（字符串）。

api.resolve

解析运行此 App Extension 的应用中的路径。无需自己导入 path 并解析路径。

// 解析到应用根目录
api.resolve.app('src/my-file.js')

// 解析到应用的 root/src 目录
api.resolve.src('my-file.js')

// 解析到应用的 root/public 目录
api.resolve.public('my-image.png')

// 解析到应用的 root/src-pwa 目录
api.resolve.pwa('some-file.js')

// 解析到应用的 root/src-ssr 目录
api.resolve.ssr('some-file.js')

// 解析到应用的 root/src-cordova 目录
api.resolve.cordova('config.xml')

// 解析到应用的 root/src-electron 目录
api.resolve.electron('some-file.js')

// 解析到应用的 root/src-bex 目录
api.resolve.bex('some-file.js')

api.appDir

包含运行此 App Extension 的应用根目录的完整路径（字符串）。

api.logger

一个作用域为当前 App Extension 的日志工具。每个方法的输出都会标记 AE (<extId>)，方便用户识别哪行日志来自哪个扩展。

api.logger.log('hello') // 绿色横幅行
api.logger.warn('careful') // 黄色横幅警告
api.logger.fatal('boom') // 红色横幅错误；以退出码 1 退出
api.logger.tip('try foo') // TIP 标签提示行
api.logger.info('synced') // INFO 标签行
api.logger.info('synced', 'SYNC') // 自定义标签文本替代 INFO
api.logger.success('built')
api.logger.error('oh no')
api.logger.warning('hmm')

const finish = api.logger.progress({
  tool: 'ssg',
  waitAction: 'building',
  doneAction: 'built'
})
// ...稍后
finish() // 打印 DONE 行及耗时

api.logger.dot // 辅助方法打印的圆点字符

api.hasTypescript

/**
 * @return {Promise<boolean>} 宿主项目是否启用了 TypeScript
 */
await api.hasTypescript()

api.getStorePackageName

/**
 * @return {Promise<string|undefined>} 'pinia' | 'vuex' | undefined
 */
await api.getStorePackageName()

api.getNodePackagerName

/**
 * @return {Promise<'npm' | 'yarn' | 'pnpm' | 'bun'>}
 */
await api.getNodePackagerName()

api.compatibleWith

确保 App Extension 与宿主应用中安装的某个包通过 semver 条件兼容。

如果不满足 semver 条件，Quasar CLI 会报错并停止执行。

semver 条件示例：'1.x || >=2.5.0 || 5.0.0 - 7.2.3'。

/**
 * @param {string} packageName
 * @param {string} semverCondition
 */
api.compatibleWith(packageName, '3.x')

api.compatibleWith('@quasar/app-vite', '^3.0.0-rc.1')

api.hasPackage

通过 semver 条件判断宿主应用中是否安装了某个包。

semver 条件示例：'1.x || >=2.5.0 || 5.0.0 - 7.2.3'。

/**
 * @param {string} packageName
 * @param {string} (optional) semverCondition
 * @return {boolean} 包已安装且满足可选的 semver 条件
 */
if (api.hasPackage('vuelidate')) {
  // 这个应用安装了它（任意版本）
}
if (api.hasPackage('quasar', '^2.0.0')) {
  // 这个应用安装了 Quasar UI v2
}

api.hasExtension

检查另一个 App Extension 是否已通过 npm 安装并被 Quasar CLI 调用。

/**
 * 检查另一个 App Extension 是否已安装
 *
 * @param {string} extId
 * @return {boolean} 该扩展是否已安装并被调用
 */
if (api.hasExtension(extId)) {
  // 已安装
}

api.getPackageVersion

获取宿主应用中某个包的版本。

/**
 * @param {string} packageName
 * @return {string|undefined} 应用中该包的版本
 */
console.log(api.getPackageVersion(packageName))
// 输出示例：
//   1.1.3
//   undefined（未找到该包时）

发现错误？在浏览器中编辑此页

1. Introduction

2. API 参数

2.1. api.ctx

2.2. api.extId

2.3. api.resolve

2.4. api.appDir

2.5. api.logger

2.6. api.hasTypescript

2.7. api.getStorePackageName

2.8. api.getNodePackagerName

2.9. api.compatibleWith

2.10. api.hasPackage

2.11. api.hasExtension

2.12. api.getPackageVersion