应用扩展索引API | Quasar Framework 中文网

应用扩展索引API

此页面引用src/index.js文件，该文件在quasar dev和quasar build上执行。这是主进程，您可以在其中修改构建以适合您的应用扩展的需求。例如，注册启动文件、修改Webpack进程、注册CSS、注册UI组件、注册Quasar CLI命令等。

文件的基本结构示例：

module.exports = function (api) {
  // 如下所述的“api”对象的属性和方法
}

api.ctx

与/quasar.config.js中的ctx相同。帮助您根据quasar dev或quasar build运行的上下文做出决策。

示例：如果仅在electron模式下运行，则可能要使用一种api方法。

if (api.ctx.dev === true && api.ctx.mode.electron === true) {
  api.beforeDev((api) => {
    // 在运行quasar dev并使用电子模式时
    // 做一些事情
  })
}

api.engine

包含正在使用的Quasar CLI引擎（作为字符串）。示例：@quasar/app-vite或@quasar/app-webpack。

api.hasVite

布尔值-是否在@quasar/app-vite上运行。

api.hasWebpack

布尔值-是否在@quasar/app webpack上运行。

api.extId

包含此应用扩展的ext-id（字符串）。

api.prompts

是一个对象，具有在安装此应用扩展后提示的答案。有关提示的更多信息，请查看提示API。

api.resolve

解析此应用扩展运行的应用内的路径。无需导入path并自己解析路径。

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

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

// 解析为应用的root/public
// (@quasar/app-webpack v3.4+ 或 @quasar/app-vite v1+)
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-electron
api.resolve.electron('some-file.js')

api.appDir

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

api.compatibleWith

通过一个semver条件确定应用扩展与宿主应用程序中安装的软件包兼容。

如果不满足semver条件，则@quasar/app将出错并暂停执行。

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

/**
 * @param {string} 包名
 * @param {string} semver条件
 */
api.compatibleWith('@quasar/app', '1.x')

// 一个更复杂的例子：
if (api.hasVite === true) {
  api.compatibleWith('@quasar/app-vite', '^1.0.0-beta.0')
}
else {
  api.compatbileWith('@quasar/app-webpack', '^3.4.0')
}

api.hasPackage

通过一个semver条件确定宿主应用程序中是否安装了某些软件包。

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

/**
 * @param {string} 包名
 * @param {string} (optional) semver条件
 * @return {boolean} 软件包已安装并且符合可选的semver条件
 */
if (api.hasPackage('vuelidate')) {
  // 嘿，这个应用有（任何版本）
}
if (api.hasPackage('quasar', '^1.0.0')) {
  // 嘿，这个应用已安装v1版本
}

api.hasExtension

检查是否已npm安装了另一个应用扩展，并且Quasar CLI已调用它。

/**
 * 检查是否安装了另一个应用扩展
 *
 * @param {string} extId
 * @return {boolean} 已安装并调用扩展
 */
if (api.hasExtension(extId)) {
  // 嘿，我们有它
}

api.getPackageVersion

获取宿主应用程序包的版本。

/**
 * @param {string} 包名
 * @return {string|undefined} 应用程序包的版本
 */
console.log( api.getPackageVersion(packageName) )
// 输出示例：
//   1.1.3
//   undefined (当包找不到的时候)

api.extendQuasarConf

扩展quasar.config.js

/**
 * @param {function} 函数
 *   (cfg: Object, ctx: Object) => undefined
 */
api.extendQuasarConf ((conf, api) => {
  //用quasar.config.js做一些事情：
  //添加、更改任何内容
})

// 一个更复杂的例子：
api.extendQuasarConf ((conf, api) => {
  if (api.hasVite === true) {
    // 用quasar.config.js做点什么。
    // 特定于@quasar/app-vite
  }
  else { // api.hasWebpack === true
    // 用quasar.config.js做点什么。
    // 特定于@quasar/app-webpack
  }
})

注册启动和CSS文件

module.exports = function (api, ctx) {
  api.extendQuasarConf((conf, api) => {
    // 确保已注册my-ext启动文件
    conf.boot.push('~quasar-app-extension-my-ext/src/boot/my-ext-bootfile.js')

    if (api.hasVite !== true) {
      // 确保启动文件转译
      conf.build.transpileDependencies.push(/quasar-app-extension-my-ext[\\/]src[\\/]boot/)
      // 如果启动文件导入任何内容，
      // 请确保上面的正则表达式也与这些文件匹配！
    }

    // 确保my-ext css通过webpack
    conf.css.push('~quasar-app-extension-my-ext/src/component/my-ext.sass')
  })
}

TIP

注意路径前面的波浪号（~）。这告诉Quasar CLI该路径是来自node_modules的依赖关系，而不是应用扩展索引脚本文件的相对路径。

api.registerCommand

注册一个命令，该命令将变为quasar run<ext-id><cmd>[args]（或缩写：quasar<ext-id_<cmd>[args]）。

/**
 * @param {string} commandName
 * @param {function} fn
 *   ({ args: [ string, ... ], params: {object} }) => ?Promise
 */
api.registerCommand('start', ({ args, params }) => {
  // 在这里做点什么

  //  这将注册“start”命令，
  //  并在运行 $ quasar run <ext-id> start 时
  //  执行该处理程序
})

api.registerDescribeApi

/**
 * @param {string} name
 * @param {string} relativePath
 *   (从进行此调用的文件开始的相对路径)
 */
api.registerDescribeApi(
  'MyComponent',
  './relative/path/to/my/component/file.json'
)

然后，上面的内容将响应$quasar describe MyComponent。

有关此类JSON文件的语法，请查看/node_modules/quasar/dist/api（在项目文件夹中）。请注意，JSON必须包含type属性（“component”、“directive”、“plugin”）。例如：

{
  "type": "component",
  "props": {
  },
  ...
}

TIP

始终用quasar describe命令进行测试，以确保你的语法正确，没有错误。

api.getPersistentConf

获取该扩展的内部持久化配置。如果没有，则返回空对象。

/**
 * @return {object} cfg
 */
api.getPersistentConf()

api.setPersistentConf

设置该扩展的内部持久性配置。如果它已经存在，将被覆盖。

/**
 * @param {object} cfg
 */
api.setPersistentConf({
  // ....
})

api.mergePersistentConf

深度合并到该扩展的内部持久性配置中。如果扩展没有任何已经设置的配置，这基本上等同于第一次设置它。

/**
 * @param {object} cfg
 */
api.mergePersistentConf({
  // ....
})