nexus
Nexus State

Nexus State React 指南

在 React 中使用 Nexus State 远程存储并管理其生命周期。

本页介绍 @nexus-js/react 中的 Nexus State 集成。Nexus Provider 和带类型约束的 React 作用域见 React。

公共 API

import {
  createRemoteStoreScope,
  NexusProvider,
  useRemoteStore,
  useStoreStatus,
} from "@nexus-js/react";
import type { RemoteStore } from "@nexus-js/core/state";
import { useStore } from "zustand";

示例复用共享契约代码中的 counterStore 和 CounterStore,以及已配置的 nexus 实例。

在组件子树中共享句柄

多个组件使用同一存储时,使用 createRemoteStoreScope()。Provider 为子树统一管理一个 RemoteStore 句柄及其远程订阅。子组件通过作用域 Hook 访问,不再各自创建句柄和订阅。

const CounterScope = createRemoteStoreScope(counterStore);

function CounterPanel() {
  return (
    <NexusProvider nexus={nexus}>
      <CounterScope.Provider options={{ target: chromeTarget.background() }}>
        <CounterButton />
        <CounterStatus />
      </CounterScope.Provider>
    </NexusProvider>
  );
}

function CounterButton() {
  const count = CounterScope.useSelector((state) => state.count, {
    fallback: 0,
  });
  const actions = CounterScope.useActions();
  return (
    <button disabled={!actions} onClick={() => actions?.increment(1)}>
      {count}
    </button>
  );
}

function CounterStatus() {
  const { pending, error } = CounterScope.useRemoteStore();
  const phase = CounterScope.useStatus((status) => status.type);
  return <span>{pending ? "connecting" : (error?.message ?? phase)}</span>;
}

作用域中的 RemoteStore 句柄为 null 时,useSelector(selector, { fallback }) 始终返回显式指定的回退值,包括获取前、替换中和获取失败后。它不会保留从旧句柄中选出的值。 useRemoteStore、useActions 和 useError 读取 Provider 的获取结果。 useStatus(selector?) 单独监听当前句柄的生命周期;没有句柄或服务端渲染期间返回 null。

远程快照和生命周期通知不会改变 Provider 的上下文值。只有选中数据或状态确实发生变化的组件,才会重新渲染。 只关心生命周期阶段时,选择 status.type;订阅完整状态对象,还会收到快照版本推进引起的更新。

不同存储需要各自的 RemoteStore 句柄。使用同一存储的组件应共享作用域,而不是分别调用 useRemoteStore()。

直接读取句柄中的状态

useRemoteStore(token, options) 负责异步获取、替换和清理 IPC 句柄;并发尝试以最新一次为准。它返回 { store, pending, error, reconnect },不订阅数据或生命周期更新。 获取期间,pending 为 true,store 和 error 为 null。一次尝试最终得到存储或获取错误;后续连接断开不会改写这个获取结果。

读取具体的本地或远程存储时,直接使用 Zustand 的 useStore(store, selector?)。Nexus 不提供自己的 useStore 或选择器缓存;使用该接口时,将 zustand 加入应用依赖。

直接读取和作用域的 useSelector 都遵循 Zustand 5 的快照稳定性规则。优先选择已有状态引用或基本类型值;如果选择器构造新对象或数组,并希望浅比较相等时保持结果稳定,使用 zustand/react/shallow 的 useShallow。 存储应在两次更新之间返回相同的状态引用,而不是每次读取都复制状态。

当前 React 集成要求 Core ~1.2.0 和基于回调的 State 契约。请一起升级这两个包和所有 State 端点。 获取的 RemoteStore 句柄包含 getInitialState、getStatus 和 subscribeStatus。应通过 useStoreStatus(store, selector?) 订阅生命周期,而不是轮询状态。 宿主存储是通过 createNexusStore(...) 或 bindNexusStore(...) 绑定的普通 Zustand 存储,不需要也不提供 withNexusState 中间件。

取得具体的 RemoteStore 句柄后再渲染子组件,让每个组件内部的 Hook 都能无条件调用。

function CounterRemote() {
  const remote = useRemoteStore(counterStore, {
    target: chromeTarget.background(),
  });

  if (!remote.store) {
    return <span>{remote.pending ? "connecting" : remote.error.message}</span>;
  }

  return <CounterValue store={remote.store} />;
}

function CounterValue({ store }: { store: RemoteStore<CounterStore> }) {
  const count = useStore(store, (state) => state.count);
  const phase = useStoreStatus(store, (status) => status.type);
  if (phase !== "ready") return <span>{phase}</span>;
  return <button onClick={() => store.actions.increment(1)}>{count}</button>;
}

useStoreStatus 只负责监听,不获取或销毁句柄。没有句柄或服务端渲染期间返回 null,之后在客户端读取当前状态。其选择器同样需要保持输出稳定。

生命周期控制

应用得知同一目标已有新会话时,可以改变 reconnectKey;也可以在事件处理器、回调或定时器中调用 remote.reconnect() 请求替换。 两种方式都会使用最新输入创建新句柄,不恢复终态句柄、不重放动作,也不保证新获取一定成功。重叠尝试以最新一次为准。

目标值、Token、Nexus 实例或超时变化时,也会重新获取。仅内联 where 函数的引用变化不会触发重连;下一次尝试会使用当前筛选函数。共享 Token 应在组件渲染函数之外定义。

替换开始时,会立即隐藏旧句柄并让选择器返回回退值。Effect 清理会销毁旧句柄,不等待新获取完成。过时请求或组件卸载后才返回的句柄也会被销毁。 React 不会在等待替换期间将旧句柄保留为 stale。

function ReconnectButton() {
  const { reconnect } = CounterScope.useRemoteStore();
  return <button onClick={reconnect}>Reconnect</button>;
}

RemoteStore 句柄绑定到会话。通过 useStoreStatus 或作用域的 useStatus 监听 disconnected、stale 和 destroyed,再通过管理句柄的 Hook 或作用域 Provider 请求替换。 remote.error 和 Scope.useError() 只报告获取失败,不报告后续传输断开或动作失败。 对端身份不再匹配时,Core 仍可将句柄标记为 stale;React 属性变化则会直接销毁旧句柄。

在 GitHub 上编辑此页