开发 NativeScript 插件

这个仓库是基于 @NathanWalker 的 插件种子 构建的。感谢，Nathan！

• TL;DR
• 长描述
  • 什么是 NativeScript 插件种子？
  • 插件文件夹结构
  • 入门
    • 开发设置
  • 链接到 CocoaPod 或 Android Arsenal 插件
    • 为 iOS 生成类型定义
    • 为 Android 生成类型定义
  • 清理插件和演示文件
  • 单元测试
  • 发布到 NPM
  • TravisCI
  • 在插件中引用 tns-core-modules
• 贡献
• 获取帮助

TL;DR

NativeScript 插件种子是为了让 NativeScript 插件开发者作为起点使用的。要启动您的插件开发，请执行以下命令

1. git clone https://github.com/NativeScript/nativescript-plugin-seed nativescript-yourplugin 其中 nativescript-yourplugin 是您插件的名字。
2. cd nativescript-yourplugin/src
3. npm run postclone
4. npm run demo.ios 或 npm run demo.android 来运行演示。这将自动监视您的插件中的 TypeScript 变更并进行转译。

长描述

什么是 NativeScript 插件种子？

NativeScript 插件种子是为了让 NativeScript 插件开发者作为起点使用的。它扩展了这里展示的几个方面。种子提供了哪些功能？

• 具有易于开发和调试选项的插件结构（见下方的开发设置部分）
• 一个简单的可用插件
• 一个与插件一起工作的演示项目。在开发期间和通过 Travis CI 运行测试时非常有用
• 插件测试
• 如何结构化您将发布到 NPM 的插件 README 文件的指南
• 创建您的插件包的 shell 脚本
• 保持 GitHub 整洁的正确 .gitignore
• 确保您发布插件到 NPM 时每个人都满意的正确 .npmignore

插件文件夹结构

入门

1. 打开命令提示符/终端，并执行 git clone https://github.com/NativeScript/nativescript-plugin-seed nativescript-yourplugin，将插件种子仓库克隆到名为 nativescript-yourplugin 的文件夹中，其中 nativescript-yourplugin 是您插件的名字。
2. 打开命令提示符/终端，并使用 cd nativescript-yourplugin/src 命令导航到 nativescript-yourplugin/src 文件夹。
3. 执行 npm run postclone 以
   • 配置您的 GitHub 用户名 - 它将被自动更改到 package.json 中
   • 配置您的插件名称 - 种子中的所有文件和类都将为您重命名
   • 为您的插件 README.md 文件创建占位符
   • 为您的插件创建一个新的仓库
   • 使用 npm link 将您的插件链接到演示应用 - 这将安装插件依赖并将在演示项目中添加插件代码的符号链接，允许您在演示中进行更改并预览，而无需每次更改时添加/删除插件。 了解更多关于 npm link 的信息。如果您遇到“EACCES”权限拒绝错误，请修复您的全局 npm 权限，这已经在这里进行了详细解释。

现在，您可以继续使用下面的开发设置来开发您的插件。

注意：插件种子已更新为使用最新版本的 NativeScript。如果您还没有准备好升级，可以检出与您的 NativeScript 版本兼容的标记版本。

开发设置

为了更容易地进行开发和调试，请继续以下步骤

1. 打开命令提示符/终端，导航到 src 文件夹，并运行 npm run demo.ios 或 npm run demo.android 以运行演示。
2. 打开另一个命令提示符/终端，导航到 src 文件夹，并运行 npm run plugin.tscwatch 以监视插件中的文件更改。

现在，更改您的插件。更改将自动应用到演示项目中。

注意：在您的插件中使用的任何原生库或 src/platforms 目录中的任何其他文件（如 Info.plist 或 AndroidManifest.xml）的更改都无法直接反映在演示应用中。您需要使用 npm run demo.reset 并重新运行应用程序。

链接到 CocoaPod 或 Android Arsenal 插件

您需要在这些文件夹中创建文件，以便在 src 文件夹中使用原生 API

platforms --
  ios --
    Podfile
  android --
    include.gradle

这样做将使这些原生 API 对您的插件可用 :)

看看这些现有的插件，了解如何简单地完成这项操作

• nativescript-cardview
• nativescript-floatingactionbutton

强烈建议为您的插件中使用的原生库生成类型定义。通过生成类型定义，您将能够查看哪些 API 正确暴露给 JavaScript，并在插件代码中轻松使用它们。

为 iOS 生成类型定义

• 按照文档中的说明运行类型定义生成命令。
• 打开 demo/typings/x86_64，并将您计划在插件中使用的 d.ts 文件复制到 src/platforms/ios/typings
• 打开 src/references.d.ts，并为添加到 src/platforms/ios/typings 的每个文件添加引用。

注意：未导出到 Objective-C 的 Swift API 不受支持。这意味着您只能调用可见于 Objective-C 运行的 API。这包括所有 Objective-C API 和仅暴露给 Objective-C 的 Swift API 的子集。因此，要从 NativeScript 中使用 Swift API（类/函数/方法等），首先请确保它可以从 Objective-C 代码中使用。有关哪些 Swift API 可以暴露给 Objective-C 的更多信息，请参阅这里。

为 Android 生成类型定义

• 克隆Android DTS 生成器仓库
• 按照README中的步骤进行操作。
• 将生成的 d.ts 文件复制到 src/platforms/android/typings 目录下。可以根据需要重命名这些文件以提高可读性。
• 打开 src/references.d.ts 文件，并为添加到 src/platforms/android/typings 的每个文件添加引用。

清理插件和演示文件

有时您可能需要删除 src/node_modules、demo/node_modules 和 demo/platforms 目录，以便重新安装。

• 运行 npm run clean 清除这些目录，然后运行 npm i 安装新的依赖项。

有时只需删除 demo 的 platforms 目录即可。

• 运行 npm run demo.reset 删除 demo 的 platforms 目录。

有时您可能需要确保 demo 中的插件文件已更新。

• 运行 npm run plugin.prepare 重新构建插件，然后将其从 demo 中删除并重新添加，以确保其正确性。

单元测试

插件种子会自动为您的插件添加基于 Jasmine 的单元测试支持。打开 demo/app/tests/tests.js 并调整其内容，以便测试在您的插件及其功能的上下文中变得有意义。

您可以在这里了解更多相关信息。

一旦您准备好测试插件的 API，请进入 src 目录并执行以下命令之一。

npm run test.ios
npm run test.android

发布到 NPM

当您准备发布时

• 在 src/package.json 中增加版本号。
• 进入 publish 目录并执行 publish.sh 脚本（如果文件不可执行，请运行 chmod +x *.sh）。

如果您只想创建一个包，请进入 publish 目录并执行 pack.sh。包将创建在 publish/package 目录下。

注意：在 Windows 上运行 bash 脚本时，您可以安装GIT SCM并使用 Git Bash。

TravisCI

插件结构附带了一个完全功能的 .travis.yml 文件，该文件在 Android 模拟器和 iOS 模拟器上部署测试应用程序，并在单元测试部分中执行测试。在克隆存储库并实现您的插件和测试后，您只需在 https://travis-ci.org/ 上注册即可。然后，在 "https://travis-ci.org/profile/<你的 github 用户>" 上启用您的插件存储库，这样就可以了。下次有人提交 PR 或向分支提交更改时，TravisCI 将触发生成，测试代码。

为了正确显示当前构建状态，您将不得不编辑 README.md 文件开头的徽章，使其与您的存储库、用户和分支相匹配。

在插件中引用 tns-core-modules

由于 Angular CLI 中存在一个问题，我们建议使用完整的 tns-core-modules 导入。更多详细说明请参阅这个讨论。

最终，在 Angular CLI 的问题修复后，这不会成为限制，但在那时之前，建议的方法是从 tns-core-modules 使用完整路径导入。以下是一个示例

错误

tsconfig.json

...

"paths": {
  "*": [
    "./node_modules/*",
    "./node_modules/tns-core-modules/*"
  ]
}
...

yourplugin.common.ts

import * as app from 'application';

正确

yourplugin.common.ts

import * as app from 'tns-core-modules/application';

贡献

我们热爱 PRs！查看贡献指南。如果您想贡献，但不确定从哪里开始，请查找标记为 help wanted 的问题。

获取帮助

请，仅使用 github issues 报告错误或请求新功能。对于一般问题和支持，请查看Stack Overflow或向我们的专家在NativeScript 社区 Slack 频道提问。