插件工作区指南 | NativeScript 中文

我们的插件工作区种子（由Nx提供支持）使 NativeScript 插件开发更加高效。

工作区旨在管理一组绑定到 npm 范围的插件，例如 @org/plugin。

您可以在一个工作区中拥有一个、几十个甚至数百个插件，同时保持高效且易于维护。
简化设置、配置、更新和发布维护。
插件功能演示可以编写一次并在多个 NativeScript 应用版本中共享，以便轻松舒适地确认前端框架集成兼容性。
从管理角度和用户角度来看，插件所属的 npm 范围都很清晰。
结构组织整齐。
您可以以全面方式自动化构建/发布任务。

如果您管理多个 npm 范围，您可以为每个范围创建一个工作区以简化操作。

创建工作区

您可以直接从仓库中选择“使用此模板”将其复制到您选择的组织中，并为其提供您喜欢的名称。

现在我们的新工作区已在 GitHub 中，我们可以克隆它来开始开发插件。

cli

git clone https://github.com/nstudio/nativescript-ui-kit.git
Cloning into 'nativescript-ui-kit'...

cd nativescript-ui-kit

设置和配置工作区

第一步将确保所有依赖项都正确安装，并且在克隆工作区后只需要运行一次。您也可以在任何时候使用它来简单地清理/重置工作区依赖项。
cli
```
npm run setup
```

现在让我们对其进行配置以使用我们首选的设置，例如我们希望将这些插件与哪个组织关联。这还将使我们有机会配置我们希望每个包使用的默认 package.json 存储库 URL 和作者详细信息。

cli

npm run config

? What npm scope would you like to use for this workspace?
› nstudio

? What is the git repository address?
› https://github.com/nstudio/nativescript-ui-kit

? What is the author display name?
› nstudio

? What is the author email?
> [email protected]

您的工作区现已配置完成并可以使用！

添加包

让我们添加一个包来开发插件，例如：@nstudio/nativescript-label-marquee

cli

npm run add

? What should the new package be named?
› nativescript-label-marquee

? Should it use the npm scope of the workspace?
› true

"@nstudio/nativescript-label-marquee" created and added to all demo apps.
Ready to develop!

这将在 packages 中创建了一个包含插件框架的 packages/nativescript-label-marquee 文件夹，其中包含必要的样板代码，以便您立即开始开发，此外还包括

更新所有演示应用版本以支持演示新包
在 tools/demo 中添加了共享代码，您可以在其中**编写一次**演示代码并在所有演示版本中共享
更新构建工具以支持新包
更新 npm start 交互式显示
更新此处的自述文件以列出新包

专注于单个包以独立开发

cli

npm start

为要关注的包选择**focus**命令并按 Enter 键。（您可以键入 focus.{package-name} 以缩小列表范围）
所有演示应用都将更新以隔离该一个包，并且对于支持的 IDE（目前为 VS Code），源代码也将隔离在工作区中。

注意：在关注后，最好始终清理计划运行的演示。（您也可以从 npm start 中清理任何演示）

您可以随时使用 npm start > focus.reset ENTER 重置。

发布包

cli

npm run publish-packages

系统将提示您输入要发布的包名称。留空并按 Enter 键将发布所有包。
然后系统将提示您输入要使用的版本。留空将自动增加修订版本（它还处理 alpha、beta、rc 等预发布类型 - 它甚至会自动在 npm 上标记相应的预发布类型）。
然后，您将收到一个简短的健全性检查 🧠😊

向包中添加 Angular 兼容性

并非所有包都需要特定的 Angular 兼容性。仅当您希望提供 Angular 特定的行为（例如自定义指令、组件或其他扩展行为以扩展您的 NativeScript 插件）时，您才需要执行此操作。

您可以在此处查看插件中 Angular 特定行为的示例。

cli

npm run add-angular

在提示符处，输入要向其添加 angular 文件夹的包的名称，该文件夹包含必要的样板代码以向包提供 Angular 支持。

迁移插件工作区

使用我们的插件工作区的一个好处是，通过 Nx 工具可以轻松高效地更新它们。TSC 维护插件工作区迁移，因此每当有迁移可用时，您只需使用几个简单的命令即可更新您的插件工作区（这通常会提供支持包的依赖项版本升级到最新的 NativeScript 版本、配置改进以及其他欢迎的补充，以帮助您创建和维护 NativeScript 插件）

cli

yarn nx migrate @nativescript/plugin-tools

这将获取 plugin-tools 的 latest 版本，分析包以查看是否有任何迁移可用，然后在有迁移要运行时打印一条消息。

有时 @nativescript/plugin-tools 更新不需要任何迁移，因此您不会总是看到可用的迁移，但如果它声明迁移可用，您可以按照消息中的说明运行它们。

cli

// install latest updates
yarn

// now run the migrations
yarn nx migrate --run-migrations=migrations.json

现在，您的插件工作区在各种配置、设置和核心依赖项方面都将是最新的。根据您所做的其他自定义，您可能需要自行调整其他内容。

运行迁移后，您始终可以删除 migrations.json 文件，因为它将不再使用。如果迁移可用，则始终会生成 migrations.json 文件。应用后，您不再需要该文件。

迁移需要多长时间运行一次？

实际上并不经常。大多数插件工作区可以维护其依赖项集长达 1-2 年或更长时间，但如果可用的迁移提到了您想要/需要的内容，请随时运行迁移。

5.2.3 迁移（2024 年 4 月 6 日发布）

迁移到 Nx 18.2.3、NativeScript 8.6 和 TypeScript ~5.4.x。

运行 yarn nx migrate @nativescript/plugin-tools 然后运行 yarn nx migrate --run-migrations 并使用此迁移后，您可能会看到此消息

bash

[!] Some files can't be patched! You can run again with --verbose to get specific error detail. The following files are unable to be patched:
  - /path/to/workspace/node_modules/typescript/lib/tsc.js
  - /path/to/workspace/node_modules/typescript/lib/typescript.js

这是正常的，运行迁移后将消失。

运行 npm run add 以将另一个插件添加到工作区后，您可能会看到此消息

bash

NX   Please run "npm run config" to confirm your workspace settings before continuing.

继续执行此操作：npm run config，这将确保您的默认包设置对以后添加的所有新包都正确设置。

5.0.0 迁移（2022 年 12 月 26 日发布）

迁移到 Nx 15.4.1、NativeScript 8.4 和 TypeScript ~4.8.x。

使用 NativeScript 8.4，TypeScript 目标已升级到 es2020，同时还使用 esnext 库。这样做是为了将 WeakRef 使用标准化到现代用法。

迁移为您更新了此目标，但是如果您遇到如下问题

Compiling TypeScript files for project "nativescript-loading-indicator"...
packages/nativescript-loading-indicator/index.android.ts:122:19 - error TS2693: 'WeakRef' only refers to a type, but is being used as a value here.

122   const ref = new WeakRef(this);

这仅表示 tsconfig.base.json 仍需要以下调整

json

"target": "ES2020",
"module": "esnext",
"lib": ["ESNext", "dom"],

这也将瞬态依赖项更新到 Angular 15。将您的插件工作区迁移到 @nativescript/plugin-tools@5 时，预计任何 Angular 部分都将与 Angular 15 及更高版本兼容。

4.1.0 迁移（2022 年 9 月 17 日发布）

迁移到 Nx 14.7.5 和 NativeScript 8.3。

对于任何 Angular 特定行为，如果您正在扩展 ListViewComponent，则可能会遇到以下情况

bash

✖ Compiling with Angular sources in Ivy partial compilation mode.
Error: packages/picker/angular/picker.directive.ts:60:40 - error TS2345: Argument of type 'NgZone' is not assignable to parameter of type 'ChangeDetectorRef'.
  Type 'NgZone' is missing the following properties from type 'ChangeDetectorRef': markForCheck, detach, detectChanges, checkNoChanges, reattach

     super(_elementRef, _iterableDiffers, zone);

这与最新版本中修改的 ListViewComponent 签名有关：https://github.com/NativeScript/angular/blob/main/packages/angular/src/lib/cdk/list-view/list-view.component.ts#L133

可以通过将签名修改为以下内容来修复

export class PickerFieldComponent
  extends ListViewComponent
  implements AfterContentInit
{
  constructor(
    _elementRef: ElementRef,
    _iterableDiffers: IterableDiffers,
    _cdRef: ChangeDetectorRef
  ) {
    super(_elementRef, _iterableDiffers, _cdRef)
  }
  // ...
}

4.0.0 迁移（2022 年 7 月 3 日发布）

迁移到 Nx 14.4.0 和 Angular 14 兼容性。
允许自定义演示 modals 文件夹与focus工具一起使用

您现在可以在apps/demo/src/modals/anything-packagename.{xml,ts}中添加补充模态视图，以帮助测试包与各种模态处理的集成，其中在文件名中使用packagename将与工作区的focus工具配合使用。例如，请参阅此处。

迁移 3.0.0（发布日期：2022 年 3 月 8 日）

迁移后

如果使用 Angular 集成，您可能会遇到以下问题

bash

✖ Compiling with Angular sources in Ivy partial compilation mode.
Error: packages/picker/angular/picker.accessors.ts:30:14 - error NG3001: Unsupported private class PickerValueAccessor. This class is visible to consumers via NativeScriptPickerModule -> PickerValueAccessor, but is not exported from the top-level library entrypoint.

30 export class PickerValueAccessor extends BaseValueAccessor<PickerField> {
                ~~~~~~~~~~~~~~~~~~~~
packages/picker/angular/picker.directive.ts:58:14 - error NG3001: Unsupported private class PickerFieldComponent. This class is visible to consumers via NativeScriptPickerModule -> PickerFieldComponent, but is not exported from the top-level library entrypoint.

58 export class PickerFieldComponent extends ListViewComponent implements AfterContentInit {
                ~~~~~~~~~~~~~~~~~~~~~

    at compileSourceFiles (/NativeScript/plugins/node_modules/ng-packagr/lib/ngc/compile-source-files.js:141:15)
    at async /NativeScript/plugins/node_modules/ng-packagr/lib/ng-package/entry-point/compile-ngc.transform.js:59:13
    at async /NativeScript/plugins/node_modules/ng-packagr/lib/graph/transform.js:7:29
ERROR: Something went wrong in @nrwl/run-commands - Command failed: node tools/scripts/build-finish.ts picker

这与 ng-packgr 更新有关，您可以通过确保导出出现问题的符号（例如，从packages/picker/angular/index.ts导出）来解决。

packages/picker/angular/index/ts:

import { NgModule, NO_ERRORS_SCHEMA } from '@angular/core'
import { registerElement } from '@nativescript/angular'
import { PickerField } from '@nativescript/picker'
import { DIRECTIVES } from './picker.directive'

// Adding these exports fixes the error
export * from './picker.directive'
export * from './picker.accessors'

@NgModule({
  declarations: [DIRECTIVES],
  exports: [DIRECTIVES],
  schemas: [NO_ERRORS_SCHEMA],
})
export class NativeScriptPickerModule {}

// Uncomment this line if the package provides a custom view component
registerElement('PickerField', () => PickerField)

创建工作区 ​

设置和配置工作区 ​

添加包 ​

专注于单个包以独立开发 ​

发布包 ​

向包中添加 Angular 兼容性 ​

迁移插件工作区 ​

迁移需要多长时间运行一次？ ​

5.2.3 迁移（2024 年 4 月 6 日发布） ​

5.0.0 迁移（2022 年 12 月 26 日发布） ​

4.1.0 迁移（2022 年 9 月 17 日发布） ​

4.0.0 迁移（2022 年 7 月 3 日发布） ​

迁移 3.0.0（发布日期：2022 年 3 月 8 日） ​

贡献者

创建工作区

设置和配置工作区

添加包

专注于单个包以独立开发

发布包

向包中添加 Angular 兼容性

迁移插件工作区

迁移需要多长时间运行一次？

5.2.3 迁移（2024 年 4 月 6 日发布）

5.0.0 迁移（2022 年 12 月 26 日发布）

4.1.0 迁移（2022 年 9 月 17 日发布）

4.0.0 迁移（2022 年 7 月 3 日发布）

迁移 3.0.0（发布日期：2022 年 3 月 8 日）