nativescript.mdc

---
description: NativeScript 移动应用的最佳实践和模式
globs: **/*.tsx, **/*.ts, **/*.vue, **/*.svelte, src/**/*.ts, app/**/*.ts, src/**/*.tsx, app/**/*.tsx, src/**/*.vue, app/**/*.vue, src/**/*.svelte
---

# NativeScript 最佳实践

## 代码风格与结构
- 使用模块化组件和服务来组织代码，以提高可维护性。
- 当平台特定代码超过 20 行时，使用平台特定文件（`.ios.ts`, `.android.ts`）。
- 创建自定义原生代码时，使用类似 `custom-native/index.ios.ts`, `custom-native/index.android.ts`, `custom-native/common.ts`, `custom-native/index.d.ts` 的文件夹结构，以保持平台特定代码的组织性，并便于在其他地方通过单次导入使用，将 `custom-native` 替换为自定义代码的名称。
  
## 命名约定
- 为平台特定的变量添加 `ios` 或 `android` 前缀（例如 `iosButtonStyle`）。
- 使用描述性的名称为自定义组件和样式命名（`primaryButtonStyle`, `userProfileView`）。
 
## 用法
- 在需要时，使用 `@NativeClass()` 扩展原生类。
- 对于 iOS，在扩展原生类时，如果需要或使用委托，请始终使用 `static ObjCProtocols = [AnyUIKitDelegate];` 来声明自定义委托。
- 对于 iOS，始终保留自定义委托实例以防止垃圾回收。例如，`let delegate = MyCustomDelegate.new() as MyCustomDelegate`，并确保它在类作用域内被保留。
- 优先使用 `__ANDROID__` 和 `__APPLE__` 进行带摇树优化（tree-shaking）的条件平台代码。
- 跟踪并清理所有计时器（`setTimeout`, `setInterval`）以避免内存泄漏。

## UI 和样式
- 始终使用 TailwindCSS 作为 CSS 框架，使用 `"@nativescript/tailwind": "^2.1.0"` 与 `"tailwindcss": "~3.4.0"` 配对以实现一致的样式。
- 为平台特定样式添加 `ios:` 和 `android:` 样式变体，`addVariant('android', '.ns-android &')`, `addVariant('ios', '.ns-ios &')`。
- `darkMode: ['class', '.ns-dark']`
- 利用 `GridLayout` 或 `StackLayout` 实现灵活、响应式的布局。对于复杂布局，更强调正确使用 `GridLayout`，但对于更简单的线性排列，则使用 `StackLayout`。
- 对隐藏时不应影响布局的元素使用 `visibility: 'hidden'`。
 
## 性能优化
- 尽量避免深度嵌套布局容器，而是明智地使用 `GridLayout` 来设置复杂布局。
- 避免在运行时直接操作可视化树，以最小化渲染开销。
- 使用 TinyPNG 等压缩工具优化图像，以减少内存和应用大小。
- 在修改 `App_Resources` 或 `package.json` 中的文件后，清理项目（`ns clean`）。
 
## 关键约定
- 重用组件和样式以避免重复。
- 在 `ListView` 和 `RadListView` 中使用模板选择器（`itemTemplateSelector`）实现条件布局。
- 最小化 UI 绑定或方法中的繁重计算。
- 仅当使用纯 XML 绑定时，才使用 `Observable` 或 `ObservableArray` 属性来高效地反映状态变化。
- 使用 Angular、React、Solid、Svelte 或 Vue 时，始终利用它们各自的状态管理、生命周期钩子、渲染优化和响应式绑定，以获得最佳性能。