MapLibre 粒子 React Native 使用说明 v3

本文对应 @navsea/maplibre-particle-rn@13.4.1-particle.2。v2 保留为 .1 历史接口说明；不要将其中的旧接口用于本版本。

安装与版本

Consumer 直接安装 @navsea/maplibre-particle-rn@13.4.1-particle.2 和 @maplibre/maplibre-react-native@11.3.6。RN 包 .2 继续使用 Android Native artifact cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1；本版本没有新的 AAR。

import { Camera, Map } from "@maplibre/maplibre-react-native";
import { FieldRuntime } from "@navsea/maplibre-particle-rn";

Map 与 Camera 必须来自官方 MLRN。NavSea 包仅为 peer dependency 对接 MLRN，不转导出地图组件。

Style 合入

宿主保有自己的底图、source 和 layer。将纯 renderer fragment 合入既有 style：

import { createParticleFieldStyleFragment } from "@navsea/maplibre-particle-rn";

const fragment = createParticleFieldStyleFragment();
const style = {
  version: 8,
  sources: { ...hostSources, ...fragment.sources },
  layers: [...hostLayers, ...fragment.layers],
};

fragment 只有 field source、field layer 和 particle layer；不含 GSI 或任何业务底图。使用 particleFieldIds 引用 renderer ID，不要自行硬编码其历史内部字符串。

Canonical Field 提交

React/宿主选择业务数据、下载/解码、校验、缓存和本地文件写入；SDK 不理解 provider、network、WeatherV2 或数据集。宿主将既有 Native 数据契约的 metadataJson 与本地 file:// payload 提交一次：

await FieldRuntime.attach(reactTag);
await FieldRuntime.clearFields(reactTag);
await FieldRuntime.submitField(reactTag, metadataJson, localFileUri);

契约保持 maplibre-particle-field/v1、float32-le、interleaved-uv。同一 canonical Field 同时供 field renderer 和 particle renderer 使用，不需要重复提交。

FieldRuntime 方法

所有方法均以 reactTag: number 为首参，异步返回现有 bridge 的结果；无 Native bridge 时调用会明确失败，import 本身不会失败。

方法	其余参数	返回值
`attach`	无	`Promise<RuntimeSnapshot>`
`detach`	无	`Promise<void>`
`getState`	无	`Promise<RuntimeSnapshot>`
`clearFields`	无	`Promise<CommandResult>`
`submitField`	`metadataJson: string`, `payloadFileUri: string`	`Promise<FieldSubmitResult>`
`setEnabled`	`enabled: boolean`	`Promise<CommandResult>`
`setFieldVisible`	`visible: boolean`	`Promise<CommandResult>`
`setParticleVisible`	`visible: boolean`	`Promise<CommandResult>`
`setTargetFps`	`target: "AUTO"	"FPS_30"
`setTargetTime`	`timestampMs: number`	`Promise<CommandResult>`
`setPlaybackState`	`state: "PLAY"	"PAUSE"`
`setPlaybackSpeed`	`speed: "HALF"	"NORMAL"
`setFieldColorStops`	`stops: readonly FieldColorStop[]`	`Promise<CommandResult>`
`setParticleColor` / `setTrailColor`	`red, green, blue, alpha: number`	`Promise<CommandResult>`
`setParticleCount`	`count: number`	`Promise<CommandResult>`
`setParticleLineWidth` / `setParticleLength`	`value: number`	`Promise<CommandResult>`
`setParticleOpacity` / `setTrailOpacity` / `setTrailFade` / `setFieldOpacity`	`value: number`	`Promise<CommandResult>`

FieldColorStop 为 { value, red, green, blue, alpha }。RuntimeSnapshot 包含 state、playbackState、targetFps、disposed；CommandResult 为 "ACCEPTED" | "REJECTED"。

setFieldColorStops() 继续遵循既有 Native 色阶约束：至少 2 个 stop，value 必须为 finite 且严格递增，RGBA 分量位于 [0,1]。

独立显示

setFieldVisible() 与 setParticleVisible() 可独立切换同一 Field 的两种 renderer。setEnabled() 控制 runtime 总开关。SDK 不根据业务类型自动选择显示组合；显示策略由宿主决定。

边界

本包不提供业务数据类型、HTTP、provider、重试、缓存、路线或 ETA 策略。Native/Core、JNI、shader 和 Android AAR 均保持 .1 已验证实现不变。Android 实机验证应在 Consumer 安装 .2 tarball 后单独执行。

4.2 KiB Raw Blame History Unescape Escape