【免费下载链接】NativeScript
⚡ Write Native with TypeScript ✨ Best of all worlds (TypeScript, Swift, Objective C, Kotlin, Java, Dart). Use what you love ❤️ Angular, React, Solid, Svelte, Vue with: iOS (UIKit, SwiftUI), Android (View, Jetpack Compose), Flutter and you name it compatible.
本指南以仓库内 DevelopmentWorkflow.md 为核心脉络，系统讲解 NativeScript 原生 UI 底座包ui-mobile-base（历史名tns-core-modules-widgets）的完整开发流程：包括环境准备、一键打包、Android/iOS 分平台构建，以及如何通过npm link将其集成到 NativeScript 应用中用于本地调试。阅读后你将掌握这套原生组件库的构建命令、产物路径与接入方法，并能结合源码结构理解构建脚本背后的工程组织。
一、先认识这个包：NativeScript 的原生 UI 底座
在进入构建流程之前，有必要先明确这个包在整个 NativeScript 生态中的位置。根据 README.md 的说明，ui-mobile-base是NativeScript core modules 所使用的原生代码（Java 与 Objective-C），它为上层 TypeScript 实现的 UI 控件提供真正的原生渲染能力。
从仓库源码结构可以清晰看到这一定位：
- Android 侧：android/widgets 下是一整套 Java 布局与控件实现，包括
AbsoluteLayout、DockLayout、FlexboxLayout、GridLayout、StackLayout、WrapLayout、TabLayout、TabViewPager、BorderDrawable、BoxShadowDrawable等，它们是 NativeScript 布局系统在 Android 上的落点； - iOS 侧：ios/TNSWidgets 是一个 Xcode 工程，包含
TNSLabel、UIView+PassThroughParent、UIView+PropertyBag、NSData+Async等 Objective-C 类别与工具类，用于补齐 UIKit 在 NativeScript 场景下的能力。
当前包的元数据见 package.json：包名为@nativescript/ui-mobile-base，版本7.0.0，描述为 "Native UI base components used with NativeScript"，声明支持ios: 6.0.0与android: 6.0.0平台基线，采用 Apache-2.0 许可证。
二、环境准备（Prerequisites）
开发这套原生组件库前，需要先安装好原生工具链与 NativeScript 本身：
- 安装 NativeScript 与原生工具链：按官方 quick-setup 文档完成配置（即 Node.js、NativeScript CLI 及 Android/iOS 环境要求）；
- Android 工程：需要安装Android Studio，用于打开位于
android/目录下的 Android 工程； - iOS 工程：需要安装Xcode，用于打开位于
ios/TNSWidgets目录下的 Xcode 工程。
这两类 IDE 不只是“查看源码”的工具，也是本地构建与调试的入口，与后文的构建流程直接相关。
三、一键构建整个包：./build.sh
在 macOS 上，只需在包根目录执行：
$ ./build.sh该脚本会同时构建 Android 与 iOS，并完成两件事：
- 将产物组装到
./dist/package目录（即 npm 包的内容布局）； - 将其打包为
./dist/tns-core-modules-widgets-*.tgz压缩包，供本地发布或安装使用。
值得注意的是，构建脚本虽未随仓库提交（当前包目录下只有文档、源码与工程配置），但它在仓库的 Nx 工程定义 project.json 中被直接引用：build目标依次执行./build.sh、cp -R dist/package/platforms/* ../../packages/core/platforms与node tools/native-state.mjs write。这意味着一次./build.sh不仅是产出 tgz，还会把原生平台资源同步进packages/core/platforms，保持 core 包与原生底座一致——这正是该工作流与 NativeScript 主仓库（monorepo）深度耦合的体现。
增量构建与一致性校验
project.json还定义了两个与构建配套的目标：
ensure-native：以SKIP_NATIVE_IF_UNCHANGED=1 ./build.sh方式执行，即在原生代码未变化时跳过重建，适合 CI 或日常开发中避免重复全量编译；verify-native：执行node tools/native-state.mjs check，通过 tools/native-state.mjs 校验原生产物的状态是否与记录一致，用于确认当前原生二进制与预期版本匹配。
这组目标揭示了该仓库的工程实践：原生构建并非一次性动作，而是与 core 包平台目录的同步、原生状态记录/校验绑定在一起的受控流程。
四、单独构建 Android：./build.android.sh
在 Unix 类系统（Linux、macOS）上，可跳过 iOS 只构建 Android：
$ ./build.android.sh该脚本只构建 Android 工程，同样会把 npm 包组装到./dist/package并打出./dist/tns-core-modules-widgets-*.tgz。此外，构建的核心产物——AAR 文件——输出在：
./android/widgets/build/outputs/aar/widgets-release.aarwidgets-release.aar是 Android 原生库的发布形态，NativeScript 运行时正是通过它把 Java 布局控件桥接给上层。
Android 工程结构速览
Android 目录是一个标准的多模块 Gradle 工程，settings.gradle 中声明了两个模块：
include ':widgets' include ':widgetdemo':widgets：核心原生库模块，即上面提到的全部 Java 控件源码与proguard-rules.pro（混淆规则，默认保留为空配置，说明该库按运行时反射调用设计，通常不应过度混淆）；:widgetdemo：一个 Kotlin 演示应用（含MainActivity.kt、ExampleInstrumentedTest.kt与ExampleUnitTest.kt），用于在设备上快速验证控件行为。
工程的 Gradle 全局配置见 gradle.properties：其中org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -Dfile.encoding=UTF-8（第 14 行）为 AGP 的 Kotlin 脚本 lint 分析预留了足够堆内存；android.useAndroidX=true与android.enableJetifier=true（第 24–25 行）开启 AndroidX 兼容，这是 NativeScript 6.x 之后的基础要求。
使用 Android Studio 构建（替代命令行）
android/README.md 提供了 IDE 内的构建路径：
- Android Studio 中File → Open，选择
android/目录； - 左侧 Project 面板选中
widgets模块； - 右侧 Gradle 面板进入
android/widgets/Tasks/build/，执行assembleRelease任务； - 输出位于
./android/widgets/build/outputs/。
assembleRelease正是build.android.sh背后调用的 Gradle 任务，两种方式产出一致。
Windows 用户的注意事项
原文档明确说明：在 Windows 上运行 bash 脚本需要先安装 GIT SCM，并改用 Git Bash 执行。即 Windows 开发者应使用 Git Bash 终端来运行build.android.sh（以及build.sh），而不是 CMD/PowerShell。
五、单独构建 iOS：./build.ios.sh
在 macOS 上可只构建 iOS：
$ ./build.ios.sh该脚本只构建 Xcode 工程，组装./dist/package并打出./dist/tns-core-modules-widgets-*.tgz。原生 iOS 框架产物位于：
./ios/TNSWidgets/build/TNSWidgets.frameworkTNSWidgets.framework以 framework 形态被 NativeScript 的 iOS 运行时链接，其中的 Objective-C 类别与工具类（如TNSLabel、UIView+PassThroughParent）用于支撑 Text、布局等控件的 UIKit 实现。
Xcode 工程结构速览
ios/TNSWidgets 目录包含：
TNSWidgets/：核心源码（.h/.m文件）与Info.plist；TNSWidgets.xcodeproj/：Xcode 工程文件（project.pbxproj与 workspace 配置）；TNSWidgetsTests/：单元测试工程，含TNSWidgetsTests.m；- 根目录还有
TNSProcess.h/.m与 normalize-xcframework-plist.mjs（用于规范化 xcframework 的 plist，适配多架构分发）。
ios/README.md 给出的 IDE 打开方式是：Xcode 中File → Open，选择ios/TNSWidgets/目录，在 Project navigator 中选择TNSWidgets工程。
六、在应用中使用：通过npm link集成调试
构建完成后，可以把打包好的插件链接到你的 NativeScript 应用中，实现“改原生代码 → 重建 → 立即在应用里验证”的本地迭代闭环。步骤分两步：
第 1 步：在包产物目录注册全局链接
在./dist/package目录下执行：
npm link这会把这个包注册为全局 npm 链接（link 的目标是dist/package下的组装产物，而不是源码目录本身）。
第 2 步：在应用项目里引用该链接
在你的 NativeScript 应用项目根目录执行：
npm link tns-core-modules-widgets之后应用便会解析到本地构建的原生组件包。每次修改原生代码后，都需要重新执行前文提到的构建命令（build.sh/build.android.sh/build.ios.sh）刷新dist/package产物，链接才会反映最新改动——这是该工作流中最重要的习惯。
需要说明的是，文档中的链接名tns-core-modules-widgets沿用了历史包名；当前仓库中该包的正式名称为@nativescript/ui-mobile-base（见 package.json）。实际链接时应以你所依赖的版本所声明的包名为准，历史文档中的名称用于理解此链接机制的历史形态。
七、工作流要点总结
综合原文档与仓库工程配置，这套原生组件库的开发工作流可以归纳为四条关键经验：
- 按需选择构建粒度：全量用
./build.sh（macOS）；只改 Android 用./build.android.sh（Unix/Windows+Git Bash）；只改 iOS 用./build.ios.sh（macOS），避免无谓的全平台编译耗时； - 认准产物路径：npm 包在
./dist/package、tgz 在./dist/tns-core-modules-widgets-*.tgz、Android AAR 在android/widgets/build/outputs/aar/widgets-release.aar、iOS framework 在ios/TNSWidgets/build/TNSWidgets.framework，排障与集成时先核对这些位置； - IDE 与命令行等价：Android Studio 的
assembleRelease、Xcode 的构建即命令行脚本对应的 GUI 形态，二者产出一致，可按习惯选择； - 与 monorepo 联动：在本仓库（Nx 工程）中，构建还会同步原生平台资源到
packages/core/platforms，并通过native-state.mjs记录/校验原生状态（ensure-native、verify-native目标），改原生代码时留意这些联动，避免 core 包与原生底座版本漂移。
对于希望深入这套构建与原生实现的读者，建议从 android/widgets/src/main/java/org/nativescript/widgets 的 Java 布局类与 ios/TNSWidgets 的 Objective-C 类别源码入手，配合本文的构建流程，即可完整掌握 NativeScript 原生 UI 底座的开发闭环。
【免费下载链接】NativeScript
⚡ Write Native with TypeScript ✨ Best of all worlds (TypeScript, Swift, Objective C, Kotlin, Java, Dart). Use what you love ❤️ Angular, React, Solid, Svelte, Vue with: iOS (UIKit, SwiftUI), Android (View, Jetpack Compose), Flutter and you name it compatible.
相关推荐
一文选对 YOLOv9 五个版本 T/S/M/C/E：按算力档位做模型选型的完整指南
一文选对 YOLOv9 五个版本 T/S/M/C/E：按算力档位做模型选型的完整指南 上周一个朋友问 YOLOv9 版本选型："五个版本我该选哪个？"我随口让他
NativeScript ui-mobile-base iOS 工程指南：TNSWidgets Xcode 项目解析与构建
NativeScript ui mobile base iOS 工程指南：TNSWidgets Xcode 项目解析与构建 NativeScript 框架的 i
2024年最完整的knowledge_graph入门指南：从安装到生成第一个知识图谱
2024年最完整的knowledge_graph入门指南：从安装到生成第一个知识图谱 knowledge_graph是一个强大的开源工具，能够将任何文本转换为知
知识图谱人工智能RAG本地部署数据可视化
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
