本文档的这一部分介绍如何创建你自己的应用扩展。

¥This section of the docs deals with creating your own App Extensions.

假设你已经安装了官方应用扩展之一。当你开始构建自己的应用扩展时，拥有这些经验将非常宝贵。如果你遇到问题，请访问我们的 Discord 服务器的 #app-extensions 通道。

¥It is assumed you have already installed one of the official App Extensions. Having this experience at your disposal is going to be very valuable when you start building your own App Extensions. If you run into problems, please visit our Discord server’s channel #app-extensions.

获取已启动(Getting started)

¥Getting started

应用扩展是一个 npm 包。有两个用于创建应用扩展的官方工具包：

¥An App Extension is an npm package. There are two official kits for creating App Extensions:

1. 应用扩展 (AE) 套件

   ¥App Extension (AE) kit

2. UI 工具包

   ¥UI kit

应用扩展 (AE) 套件(App Extension (AE) kit)

¥App Extension (AE) kit

如果你的应用扩展程序不涉及 UI（即没有组件或指令），请使用 AE 套件。一个例子是仅创建启动文件的扩展。

¥If your app extension does not involve UI (i.e. does not have components or directives) then use the AE kit. An example of this would be an extension that creates a boot file only.

UI 工具包(UI kit)

¥UI kit

如果你的应用扩展程序确实涉及 UI（即包含组件或指令），请使用 UI 套件。一个例子是提供 UI 元素供你在应用中使用的扩展。这包含一个 ui 文件夹用于创建组件/指令，一个 ui/dev Quasar 应用用于单独测试组件/指令，以及一个 app-extension 文件夹用于创建应用扩展，该扩展将用于通过 Quasar CLI 将组件/指令注入 Quasar 应用。UI 工具包还可以用于将你的组件/指令与 Quasar Vite 插件或 UMD 一起使用。

¥If your app extension does involve UI (i.e. does have components or directives) then use the UI kit. An example of this would be an extension that provides a UI element for use in your app. This has a ui folder for creating your component/directive, a ui/dev Quasar application for testing your component/directive in isolation, and an app-extension folder for creating the App Extension that will be used for injecting your component/directive via the Quasar CLI into a Quasar app. The UI kit can also be used such that your component/directive can also be used with the Quasar Vite plugin or UMD.

第三方集成(3rd party integration)

¥3rd party integration

如果你的目标是将第三方库安装到 Vue 中，那么这取决于该库……

¥If your objective is to install a 3rd-party library into Vue, then it depends upon the library…

• 如果你还打算提供一些使用该 Vue 插件的 UI 组件或类似组件，则应该使用 UI Kit。这对于包含日历扩展之类的功能来说是一个不错的选择。

  ¥If you also aim to provide some UI components or such that uses that Vue plugin, you should use the UI Kit. This would be a good choice for including something like a Calendar extension.

• 如果唯一目标是通过启动文件中的简单 app.use(SomeVuePlugin) 加载它，并且可能进行一些配置更新等，那么 AE 套件可能是更好的选择。例如，对于包含 Axios 之类的功能，这是一个不错的选择。

  ¥If the only objective is to load it through a simple app.use(SomeVuePlugin) in a boot file, and maybe some config updates and such, the AE Kit may be a better choice. This is a good choice for example for something like including Axios.

创建应用扩展(Creating the App Extension)

¥Creating the App Extension

$ yarn create quasar
# then pick the AppExtension option

它会提示你具体需求。你需要安装脚本、卸载脚本吗？你会向用户询问一些问题吗？仅选择你将要使用的选项。如果你另有决定，你可以稍后手动添加它们。

¥It will prompt you about your specific needs. Do you need an install script, an uninstall script, will you be prompting the user with some questions? Pick only what you will be using. You can manually add these later if you decide otherwise.

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

¥For the sake of this documentation page, let’s assume we answered with my-ext to the App Extension ext-id question (regarding the prompts above). Remember that the folder name for the App Extension source folder can be different from the actual ext-id. At the end, we will publish our new npm package (quasar-app-extension-my-ext).

根据你的回复，Quasar CLI 将为你的应用扩展程序的源代码创建一个文件夹，该文件夹的结构如下：

¥Based on your response, Quasar CLI will create a folder for your App Extension’s source code that will have the following structure:

应用扩展工具包：

¥The app-extension kit:

UI 工具包：

¥The ui kit:

除了 src/index.js（来自 app-extension 套件）或 app-extension/src/index.js（来自 ui 套件）之外，所有其他文件都是可选的。你可以随时手动添加或删除它们。

¥Except for src/index.js (from the app-extension kit) or app-extension/src/index.js (from the ui kit) , all the other files are optional. You can manually add or remove them at any point in time.

使用 UI 套件时，你将拥有两个 npm 包；一个用于应用扩展，一个用于 UI 模块。要使用 dev 应用进行测试，请从 ui 文件夹中输入 yarn dev。在 dev 文件夹中创建用于测试的页面，它们将自动注入到测试应用中。另外，请查看 package.json 中的 scripts 部分，了解你可用的内容。使用 yarn build 时，会创建一个 dist 文件夹，其中包含各种类型的包（common、esm 和 umd）。

¥When using the UI kit, you will have two npm packages; one for the App Extension and one for the UI module. For testing with the dev app, from the ui folder type yarn dev. Create pages in the dev folder for testing and they will automatically be injected into the test app. Also, check out the scripts section in the package.json to see what you have available. When you yarn build, a dist folder will be created and populated with various types of packages (common, esm, and umd).

应用扩展脚本说明(App Extension Scripts description)

¥App Extension Scripts description

处理包依赖(Handling package dependencies)

¥Handling package dependencies

如果你的应用扩展程序为了能够运行而依赖某些软件包（Quasar CLI 提供的软件包除外，例如 “quasar”、“@quasar/extras”、“@quasar/app” - 你应该在 /install.js 和 /index.js 脚本中使用 “api.compatibleWith()” - 检查 安装 API 和 索引 API），那么使用 yarn/npm 将它们安装到你的应用扩展程序文件夹中，即可将它们提供给托管应用。

¥If your App Extension has its own dependencies over some packages in order for it to be able to run (except for packages supplied by Quasar CLI, like “quasar”, “@quasar/extras”, “@quasar/app” – you should use “api.compatibleWith()” for those in your /install.js and /index.js scripts – check Install API and Index API), then yarn/npm installing them into your App Extension folder will supply them into the hosting app.

示例：你正在创建一个依赖于 “my-table” npm 包（名字是假的，只是为了强调这一点）的 UI 组件，那么你应该在你的 App Extension 文件夹中使用 yarn/npm install “my-table” 。

¥Example: You are creating a UI component that depends on “my-table” npm package (name is bogus, just for making a point here), then you should yarn/npm install “my-table” in your App Extension folder.

手动测试(Manually testing)

¥Manually testing

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

¥We need to create a Quasar project folder to be able to test it while we develop the extension:

$ yarn create quasar
# or
$ npm init quasar@latest

# pick "App with Quasar CLI"

安装并提示脚本(Install and prompts scripts)

¥Install and prompts scripts

在测试 Quasar 项目文件夹中，我们手动添加了我们的 App Extension。请注意，我们没有指定 npm 包名称（它尚未发布！），而是指定了我们开发它的 App Extension 文件夹的路径，因为我们想要测试未发布的作品：

¥Inside the testing Quasar project folder, we manually add our App Extension. Notice that we are not specifying the npm package name (it’s not published yet!) but a path to our App Extension folder where we develop it, since we want to test unpublished work:

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

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

¥You will need to figure out which command works best for your environment.

然后我们调用它。调用过程假定应用扩展的软件包已安装 yarn/npm（我们之前已安装），并跳过该步骤：

¥We then invoke it. The invoking procedure assumes that the App Extension’s package is already yarn/npm installed (which we did earlier) and skips that step:

# we said our <ext-id> will be "my-ext", so:
$ quasar ext invoke my-ext

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

¥This will trigger the installation of our new App Extension. You need to redo these two steps each time you make changes and you want to test them.

此外，如果你希望在开发应用扩展程序时在测试应用中启用 HMR（热模块重新加载）功能，那么你的 quasar.config file > devServer > watchFiles 将如下所示：

¥Additionally, if you would like to have HMR (hot module reload) capabilities in your test app while developing your App Extension, then your quasar.config file > devServer > watchFiles would look like this:

// quasar.config file for
// Quasar CLI with Webpack (@quasar/app-webpack)

devServer: {
  // be sure to change <myextid> below to
  // your App Extension name:
  watchFiles: [
    '/node_modules/quasar-app-extension-<myextid>/*'
  ]
}

@quasar/app-webpack(@quasar/app-webpack)

你可能想要扩展 Webpack 配置。假设你使用的是 chainWebpack 方法，你的 quasar.config file > build > chainWebpack 应如下所示：

¥You might want to extend the Webpack config. Assuming you are using the chainWebpack method, your quasar.config file > build > chainWebpack should look like this:

chainWebpack (chain) {
  chain.merge({
    snapshot: {
      managedPaths: []
    }
  })
},

@quasar/app-vite(@quasar/app-vite)

你可能想要扩展 Vite 配置。假设你使用的是 extendViteConf 方法，你的 quasar.config file > build > extendViteConf 应如下所示：

¥You might want to extend the Vite config. Assuming you are using the extendViteConf method, your quasar.config file > build > extendViteConf should look like this:

extendViteConf (viteConf, { isClient, isServer }) {
  // do stuff in-place with viteConf
},

卸载脚本(Uninstall script)

¥Uninstall script

假设你已按照上述部​​分安装了应用扩展，我们现在可以测试卸载脚本（如果有）：

¥Assuming you’ve installed your App Extension following the section above, we can now test the uninstall script (if you have any):

$ quasar ext uninvoke my-ext

类似地，上述命令不会从 package.json 和 node_modules 中修改或删除 npm 包。它只是调用卸载脚本，并将其从测试 Quasar 应用项目文件夹中已注册/已安装的应用扩展列表中删除。但是，你的终端用户将调用 $ quasar ext remove my-ext 来卸载它，这也会卸载 npm 包。

¥The command above similarly does not modify or remove the npm package from package.json and node_modules. It simply calls the uninstall script and removes it from the registered/installed App Extensions list in your testing Quasar app project folder. Your end-user will however call $ quasar ext remove my-ext to uninstall it, which also uninstalls the npm package.

每次更改卸载脚本并想要测试它们时，都需要重新执行这些安装步骤并发出 uninvoke 命令。

¥You need to redo these install steps and issue the uninvoke command each time you make changes to the uninstall script and you want to test them.

索引脚本(Index script)

¥Index script

在上面的部分中，我们描述了如何测试提示、安装和卸载脚本。现在是时候运行 index 脚本了，它是应用扩展的核心。

¥In the sections above we described how to test the prompts, install and uninstall scripts. Now it’s time for the index script, which is the heart of your App Extension.

在这里你可以修改所有 quasar.config 文件选项、扩展 Webpack 配置、注册 Quasar CLI 命令、启动开发应用所需的外部服务等等。

¥This is where you can tamper with all quasar.config file options, extend the Webpack configuration, register Quasar CLI commands, start up external services required for developing your app and many more.

因此，每次执行 $ quasar dev 和 $ quasar build 时，索引脚本都会运行。

¥As a result, the index script is run each time $ quasar dev and $ quasar build are executed.

为了测试索引脚本，你可以在每次更改某些内容时重复上述卸载和安装步骤在应用扩展脚本代码中。但这会变得非常繁琐。如果你在 Unix 操作系统（MacOS、Linux）上进行开发，你可以利用 yarn link 命令，该命令会从 Quasar 测试应用的 node_modules 文件夹创建一个 符号链接 文件，并将其复制到你的扩展程序文件夹中：

¥In order to test the index script, you can repeat the uninstall and install procedures described above each time you change something in the App Extension script code. But it becomes very tedious. If you are developing on a Unix OS (MacOS, Linux), you can take advantage of the yarn link command which creates a symbolic link from the Quasar testing app’s node_modules folder to the folder of your extension:

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

# we register the extension through yarn
$ yarn link

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

$ yarn link quasar-app-extension-<ext-id>
# in our demo case, it's this:
# $ yarn link quasar-app-extension-my-ext

请记住，如果你需要将任何依赖 yarn/npm install 到你的应用扩展中，那么你还必须卸载你的应用扩展，然后在测试应用中重新安装它：

¥Remember that if you need to yarn/npm install any dependencies into your App Extension, then you must also uninstall your App Extension and re-install it in your test app:

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

# run yarn/npm command (install/uninstall, etc)

# then

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

# Uninstall the app ext
$ quasar ext uninvoke my-ext

# Re-install the app ext
$ quasar ext invoke my-ext

你实际上只需要 quasar ext invoke my-ext（安装）应用扩展程序即可重新安装它。以上信息仅供参考。

¥You really only need to quasar ext invoke my-ext (install) the App Extension to re-install it. The above information is for completeness.

发布(Publishing)

¥Publishing

当你完成应用扩展并准备部署时，你只需将其发布到 npm 仓库即可。

¥When you finalized your App Extension and you’re ready to deploy it, all you need to do is to publish it to the npm repository.

在你的 App Extension 文件夹中，运行 yarn 发布 或 npm 发布。两者功能相同。

¥Inside of your App Extension folder, run yarn publish or npm publish. Both do the same thing.