应用扩展安装API

此页面引用src/install.js文件,该文件仅在安装扩展安装时执行。 并非所有扩展安装都需要安装-这是可选步骤。

文件的基本结构示例:

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

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')

api.appDir

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

api.compatibleWith

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

如果不满足semver条件,则Quasar CLI将出错并暂停执行。

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

/**
 * @param {string} 包名
 * @param {string} semver条件
 */
api.compatibleWith(packageName, '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', '^2.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.extendPackageJson

使用新属性扩展package.json的辅助方法。 如果指定现有属性,将覆盖它们。

/**
 * @param {object|string} extPkg - JSON文件的扩展对象或相对路径
 */
api.extendPackageJson({
  scripts: {
    'electron': 'quasar dev -m electron'
  }
})

上面的示例在应用程序的package.json中添加了一个npm脚本,因此您可以执行 yarn electron(或等效的npm run electron)。

api.extendJsonFile

使用新属性扩展JSON文件(深度合并)。 如果指定现有属性,它将覆盖它们。

/**
 * @param {string} 文件(应用程序根文件夹的相对路径)
 * @param {object} 新数据(要合并的对象)
 */
api.extendJsonFile('src/some.json', {
  newProp: 'some-value'
})

api.render

将文件夹从您的应用扩展模板(指定的任何文件夹)渲染(复制)到应用程序的根目录中。 保持与模板文件夹相同的文件夹结构。

如果某些文件已存在于应用程序中,则它将询问用户是否应覆盖它们。

需要一个调用render()的文件所在文件夹的相对路径。

/**
 * 将扩展模板中的文件夹渲染到devland中
 * 需要一个文件夹路径,相对于调用render()文件的路径
 *
 * @param {string} 模板路径(要在应用程序中渲染的文件夹的相对路径)
 * @param {object} 作用域(可选;呈现作用域变量)
 */
api.render('./path/to/a/template/folder')

文件名边缘情况

如果要渲染以点(如.env)开头的模板文件,则必须遵循特定的命名约定,因为在将插件发布到npm时会忽略点文件:

# 包含点文件的模板必须使用
# 下划线而不是名称中的点:

some-folder/_env

# 当调用api.render('./some-folder')时,这将是
# 在项目文件夹中显示为:

/.env

如果要渲染一个实际上以下划线开头的文件,则文件名必须以__开头(两个下划线字符而不是一个)。

some-folder/__my.css

# 调用api.render('./template')时,这将
# 在项目文件夹中显示为:

/_my.css

使用作用域

您还可以通过使用lodash.template 语法进行插值,向要渲染的文件中注入一些决策代码。

Example:

// src/install.js
// (我的文件夹与进行后续调用的文件
// 位于同一文件夹中)
api.render('./my-folder', {
  prompts: api.prompts
})

假设我们也使用了提示API文件。 它询问用户是否需要“功能X”,并将答案存储在名为“featureX”的变量中。

在渲染文件时,我们可以决定渲染文件的外观。 这样就无需创建两个文件夹并根据某些决策来决定要呈现哪个文件夹。

// src/my-folder/some-file.js

<% if (prompts.featureX) { %>
const message = 'This is content when "Feature X" exists'
<% } else { %>
const message = 'This is content when we don\'t have "Feature X"'
<% } %>

可能性仅受您的想象力限制。

api.renderFile

与api.render()类似,不同之处在于此方法渲染单个文件。

/**
 * 将扩展模板中的文件渲染到devland中
 * 需要一个文件路径,相对于调用renderFile()文件的路径
 *
 * @param {string} relativeSourcePath (相对于调用安装脚本的文件夹的文件路径)
 * @param {string} relativeTargetPath (相对于应用程序根目录的文件路径-包括文件名!)
 * @param {object} scope (可选的; 渲染范围变量)
 */
api.renderFile('./path/to/a/template/filename', 'path/relative/to/app/root/filename', {
  prompts: api.prompts
})

api.renderFile('./my-file.json', 'src/my-file.json')

api.getPersistentConf

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

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

api.setPersistentConf

设置此扩展的内部持久配置。 如果已经存在,则将其覆盖。

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

api.mergePersistentConf

深度合并到此扩展的内部持久配置中。 如果扩展尚未设置任何配置,则从本质上讲,这等同于首次设置。

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

api.onExitLog

添加一条消息,以在应用CLI完成应用扩展安装并即将退出后打印。 可以多次调用以注册多个退出日志。

/**
 * @param {string} 消息
 */
api.onExitLog('Thanks for installing my awesome extension')