# @navsea/maplibre-particle-rn

当前版本：`13.6.1-particle.22`。Android Native 必须配套 `cc.navsea.maplibre:android-sdk-particle-opengl:13.6.1-particle.22`。本包是 React Native 的薄控制面，不负责 Map 组件、provider、HTTP、manifest、下载、缓存或 NavSea 业务策略。

## 当前推荐主链：QBIN V4

宿主负责取得并缓存 QBIN 文件，然后只把本地绝对路径或 `file://` URI 交给 RN/Native：

```ts
await FieldRuntime.attach(reactTag);
await FieldRuntime.submitEncodedField(reactTag, fieldKey, metadata, profileContract, qbinFileUri);
await FieldRuntime.setEncodedColorBinding(reactTag, colorBinding);
await FieldRuntime.setEncodedParticleBinding(reactTag, particleBinding);
await FieldRuntime.setEncodedForecastTime(reactTag, timestampMs);
```

Android 链路为：`FieldRuntime.submitEncodedField` → `WeatherRuntimeBridgeModule` → `WeatherRuntime.submitEncodedField` → JNI → `RasterArraySource::submitEncodedField` → `EncodedFieldIngress`。Native 依据 magic/version 显式分流：历史 QBV2 继续走 `QbinV2Decoder`，新的 QBV3 压缩格式走 `QbinV3Decoder`。iOS 使用同一 `WeatherRuntimeBridge` TurboModule，按每次调用的 Fabric `reactTag` 即时解析当前 MLRN `MapView`，再调用 public `MLNParticleFieldRuntime`。两端的 QBIN 解码都发生在 MapLibre Native，不在 JS/TS。

V4 主要公共方法：`submitEncodedField`、`setEncodedColorBinding`、`setEncodedParticleBinding`、`setEncodedForecastTime`、`setEncodedForecastPlaybackState`、`setEncodedForecastPlaybackSpeed`、`clearEncodedField`。ColorBinding 支持 `SCALAR`、`VELOCITY_COMPONENT`、`DIRECTION_ANGLE`；ParticleBinding 支持 U/V vector components 或 direction angle。

## V3 canonical 兼容

`submitField(metadataJson, FieldPayloadRefs)`、`clearFields`、旧 renderer 参数接口仍保留，用于历史 Consumer/Test Host 对照。新 NavSea 接入不要以 V3 `submitField` 作为新主链。

## Map / Camera

Map 与 Camera 直接从 `@maplibre/maplibre-react-native@11.5.0` 使用。本包把 MLRN 作为 peer dependency，不转导出 MapLibre React Native。

## iOS 集成

autolinking 使用 `MapLibreParticleRN.podspec` 和 RN codegen 的 `WeatherRuntimeBridge` provider。pod 只依赖 `MapLibreReactNative`，不声明、链接或嵌入第二份 `MapLibre.framework`。Consumer 必须以 MLRN 11.5.0 的 `$MLRN_SPM_SPEC` 配置同一个 custom `MapLibre` product；Particle pod 不接受独立 MapLibre binary。

Podfile 的 `post_install do |installer|` 必须同时调用 `$MLRN.post_install(installer)` 与 `$MLRN_PARTICLE.post_install(installer)`。两者复用同一个 `$MLRN_SPM_SPEC`：前者接入 MLRN/App，后者将同一 package reference/product 加到 `MapLibreParticleRN` pod target。Expo plugin 会幂等注入后一个调用；它不设置 `$MLRN_SPM_SPEC`，该值仍由 MLRN 官方 plugin 或宿主 Podfile 提供。

## Android 发布

RN tgz：

```text
https://pbf.jpcn.ccwu.cc/npm/navsea-maplibre-particle-rn-13.6.1-particle.22.tgz
```

Native Maven repository：

```text
https://pbf.jpcn.ccwu.cc/maven
```

Native coordinate：

```text
cc.navsea.maplibre:android-sdk-particle-opengl:13.6.1-particle.22
```

Expo plugin 与 `android/build.gradle` 必须指向同一 `.22`。正常 Consumer 不复制 AAR、不依赖 MapLibreParticleLab 源码路径，也不以 Maven Local 作为公网验证主路径。完整 Linux 发布与 Win11 验证流程见 `docs/50_Step记录/STEP-080_Android_AAR与RNTestHost标准构建流水线_v2.md`。