Nexus State 快速开始
使用 Nexus 创建可跨上下文同步的远程状态存储。
开始前
先配置两个相互通信的 Nexus 上下文,方法见快速开始。一个持有权威存储,另一个读取本地镜像并调用远程动作。
要安装什么
不依赖 UI 的 API 从 @nexus-js/core/state 导入;只有需要 React 集成时才额外安装 @nexus-js/react。@nexus-js/core/state 是导入路径,不是独立的包。
1. 定义存储契约
import { createStoreToken } from "@nexus-js/core/state";
export interface CounterStore {
count: number;
increment(by?: number): number;
reset(): void;
}
export const counterStore = createStoreToken<CounterStore>(
"example:counter-store",
);2. 创建宿主存储
像注册普通 Nexus 服务一样注册 State 存储。
import { nexus } from "@nexus-js/core";
import { createNexusStore } from "@nexus-js/core/state";
import { counterStore } from "./counter-store";
const { provider, store } = createNexusStore(
counterStore,
(set, get) => ({
count: 0,
increment(by = 1) {
const count = get().count + by;
set({ count });
return count;
},
reset() {
set({ count: 0 });
},
}),
{
snapshot: (local) => ({ count: local.count }),
expose: ["increment", "reset"],
},
);
nexus.configure({
providers: [provider],
});
console.log(store.getState().count);provider 用于注册远程服务,store 是原始的本地 Zustand 存储。已有 Zustand 存储时,使用 bindNexusStore(...)。
原生存储生命周期、ConnectOptions 和返回 Result 的安全接口,见Core API。
3. 从另一个上下文连接
import { nexus } from "@nexus-js/core";
import { connectNexusStore } from "@nexus-js/core/state";
import { counterStore } from "./counter-store";
const remoteCounter = await connectNexusStore(nexus, counterStore, {
target: { context: "background" },
});返回的 RemoteStore 持有本地镜像。会话替换后,需要用 connectNexusStore(...) 创建新句柄。
4. 读取、订阅和调用动作
console.log(remoteCounter.getState().count);
const stop = remoteCounter.subscribe((state) => {
console.log("count changed", state.count);
});
await remoteCounter.actions.increment(2);
stop();
remoteCounter.destroy();非 React 环境中的生命周期与清理
在不使用 React 的服务、Worker 或脚本中,可以采用以下模式:
const remote = await connectNexusStore(nexus, counterStore, options);
const unsubscribe = remote.subscribe((state) => {
// 处理远程更新。
console.log(state);
});
try {
await remote.actions.increment(1);
const snapshot = remote.getState();
console.log(snapshot.count);
} finally {
// 始终取消监听并销毁句柄。
unsubscribe();
remote.destroy();
}RemoteStore 句柄进入终态后,需要创建新句柄,不能继续复用旧句柄。断开后不要自动重试动作,因为它可能已在宿主端完成。
完整规则见生命周期和错误。
5. React 用法
在 React 中,用 NexusProvider 包裹组件树,并通过作用域共享远程句柄:
import { createRemoteStoreScope, NexusProvider } from "@nexus-js/react";
const CounterScope = createRemoteStoreScope(counterStore);
function App({ sessionEpoch }: { sessionEpoch: number }) {
return (
<NexusProvider nexus={nexus}>
<CounterScope.Provider
options={{
target: { context: "background" },
reconnectKey: sessionEpoch,
}}
>
<CounterView />
</CounterScope.Provider>
</NexusProvider>
);
}
function CounterView() {
const { pending, reconnect } = CounterScope.useRemoteStore();
const count = CounterScope.useSelector((state) => state.count, {
fallback: 0,
});
const actions = CounterScope.useActions();
const phase = CounterScope.useStatus((status) => status.type);
if (pending) return <span>Connecting</span>;
if (!actions || phase !== "ready") {
return <button onClick={reconnect}>Reconnect</button>;
}
return <button onClick={() => actions.increment(1)}>{count}</button>;
}作用域 Provider 为子树管理一个共享的 RemoteStore 句柄。叶组件使用该作用域的 useSelector、useActions 和 useStatus,无需各自调用 useRemoteStore(...)。
如果组件直接管理远程句柄,应在 remote.store 存在后再渲染子组件,并在子组件中使用 Zustand 的 useStore(remote.store, selector) 读取状态。
reconnectKey、reconnect()、句柄替换和选择器回退值的行为,见Nexus State React。