应用扩展开发

文档的此部分涉及创建自己的应用扩展。

假定您已经安装了官方的应用扩展之一。 当您开始构建自己的应用扩展时,掌握这些经验将非常有价值。 如果遇到问题,请访问我们的Discord服务器的频道#app-extensions

入门

一个应用扩展是npm软件包。 我们将使用官方的应用扩展入门套件来创建一个。

$ quasar create my-ext --kit app-extension

它将提示您有关您的特定需求。 您是否需要安装脚本、卸载脚本,是否会提示用户一些问题? 仅选择您要使用的内容。 如果您另有决定,可以稍后手动添加。

为了本文档,我们假设我们以my-ext回答了应用扩展“ext-id”问题(对应上述提示)。 请记住,应用扩展源文件夹的文件夹名称可以与实际的my-ext不同。 最后,我们将发布新的npm软件包(quasar-app-extension-my-ext)。

根据您的响应,Quasar CLI将为您的应用扩展的源代码创建一个文件夹,该文件夹具有以下结构:

.
├── package.json
└── src
    ├── index.js      # 在索引API中描述
    ├── install.js    # 在安装API中描述
    ├── prompts.js    # 在提示API中描述
    └── uninstall.js  # 在卸载API中描述

除了src/index.js以外,其他所有文件都是可选的。 您可以随时手动添加或删除它们。

脚本说明

名称说明
src/prompts.js在安装应用扩展时处理提示
src/install.js扩展应用扩展的安装过程
src/index.jsquasar devquasar build上执行
src/uninstall.js扩展了应用扩展的卸载过程

处理软件包依赖关系

如果您的应用扩展对某些软件包具有自己的依赖关系才能运行(除了Quasar CLI提供的软件包,例如“quasar”、“@quasar/extras”,“@quasar/app”,则您应该在/install.js和/index.js脚本中使用“api.compatibleWith()”-查阅安装API索引API),然后将它们yarn/npm安装到您的应用扩展文件夹中,这会将它们提供给托管应用。

示例:您正在创建一个依赖于“my-table”npm软件包的UI组件(名称是假的,只是为了在此处指出),那么您应该在您的应用扩展文件夹中yarn/npm安装“my-table”。

WARNING

绝对不要yarn/npm安装Quasar CLI提供的软件包,因为应用扩展不应具有如此侵入性,并迫使用户使用特定的Quasar版本。取而代之的是使用“api.compatibleWith(),这相当于轻声地说“对不起,如果您想使用我的应用扩展,则需要安装此版本的Quasar”。

手动测试

我们需要创建一个Quasar项目文件夹,以便在开发扩展程序时能够对其进行测试:

$ quasar create test-app

安装和提示脚本

TIP

详细了解如何使用提示API安装API.

在测试的Quasar项目文件夹中,我们手动添加了应用扩展。 请注意,由于我们要测试未发布的工作,因此我们并未指定npm软件包名称(尚未发布!),而是指定了用于开发的应用扩展文件夹的路径:

$ yarn add --dev file://path/to/our/app/ext/root
# or
$ yarn add --dev link://path/to/our/app/ext/root

您将需要确定哪个命令最适合您的环境。

WARNING

通过file:link:进行链接出现问题的报告很多。 这超出了Quasar的能力,但可能与您的开发环境有关,也就是说,您使用Windows的版本会有所不同。

然后我们调用它。 调用过程假定已经安装了应用扩展的软件包(我们之前已经完成了),并且跳过了这一步:

# 我们说我们的<ext-id>将是“my-ext”,因此:
$ quasar ext invoke my-ext

这将触发我们新的应用扩展安装。 每次进行更改并要测试它们时,都需要重做这两个步骤。

此外,如果您希望在开发应用扩展时在测试应用程序中具有HMR(热模块重载)功能,则您的quasar.conf.js > devServer > watchOptions将如下所示:

// quasar.conf.js
devServer: {
  watchOptions: {
    ignored: [
      'node_modules',

      // 确保将下面的<myextid>
      // 更改为您的应用扩展的名称:
      '!node_modules/quasar-app-extension-<myextid>'
    ]
  }
}

卸载脚本

TIP

详细了解如何使用卸载API.

假设您已按照上述部分安装了应用扩展,我们现在可以测试卸载脚本(如果有):

$ quasar ext uninvoke my-ext

上面的命令同样不会修改package.json和node_modules中的npm软件包。 它只是调用卸载脚本,并将其从测试Quasar应用程序项目文件夹中已注册/安装的应用扩展列表中删除。 但是您的最终用户将调用$ quasar ext remove my-ext来卸载它,这也会卸载npm软件包。

每次对卸载脚本进行更改并要对其进行测试时,都需要重做这些安装步骤并发出uninvoke命令。

索引脚本

在以上各节中,我们描述了如何测试提示、安装和卸载脚本。 现在是时候编写索引脚本了,这是您的App Extension的核心。

在这里,您可以篡改所有quasar.config.js选项、扩展Webpack配置、注册Quasar CLI命令、启动开发应用程序所需的外部服务等等。

结果是,每次执行$ quasar dev$ quasar build都会运行索引脚本。

为了测试索引脚本,您每次在应用扩展脚本代码中进行更改时,都可以重复上述卸载和安装过程。 但这变得非常乏味。 如果您在Unix OS(MacOS,Linux)上进行开发,则可以利用yarn link命令来创建符号链接将测试应用程序的node_modules文件夹链接到扩展程序的文件夹中:

$ cd /path/to/app/extension/folder

# 我们通过yarn注册扩展
$ yarn link

$ cd /path/to/quasar/testing/app/folder

$ yarn link quasar-app-extension-<ext-id>
# 在我们的演示案例中,是这样的:
# $ yarn link quasar-app-extension-my-ext

请记住,如果您需要yarn/npm install任何依赖项到您的应用扩展中,那么您还必须卸载您的应用扩展并将其重新安装在测试应用程序中:

$ cd /path/to/app/extension/folder

# 运行 yarn/npm command (install/uninstall, etc)

# 然后

$ cd /path/to/quasar/testing/app/folder

# 卸载应用扩展
$ quasar ext uninvoke my-ext

# 重新安装应用扩展
$ quasar ext invoke my-ext

您实际上只需要quasar ext invoke my-ext(安装)应用程序扩展来重新安装它。 以上信息仅供参考。

WARNING

在Windows上,有许多关于“ yarn link”问题的报告。 这超出了Quasar的能力,但可能与您的开发环境有关,也就是说,您使用Windows的版本会有所不同。

TIP

详细了解如何使用索引API.

发布

在完成您的App Extension并准备部署它之后,您所需要做的就是将其发布到npm存储库中。

在您的App Extension文件夹中,运行yarn publishnpm publish。 两者都做同样的事情。

WARNING

重要的是要记住不要从扩展程序的package.jsonname属性中删除quasar-app-extension-前缀,否则Quasar CLI将无法识别它。