基础用法

计数器

tsx

import { Button } from "shineout";
import { create } from "@lite-code/reactive";

const store = create({ count: 0 });

export default function Basic() {
  const { count } = store.useSnapshot();
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <Button onClick={() => store.count--}>-</Button>
      <span style={{ minWidth: 32, textAlign: "center", fontSize: 16 }}>
        {count}
      </span>
      <Button type="primary" onClick={() => store.count++}>
        +
      </Button>
    </div>
  );
}

跨组件共享

多组件共享

tsx

import { Button } from "shineout";
import { create } from "@lite-code/reactive";

/**
 * 多组件共享同一个 store 实例，任意一处修改，所有订阅组件同步更新。
 */
const store = create({ count: 0 });

function Display() {
  const { count } = store.useSnapshot();
  return (
    <div style={{ padding: "8px 16px", background: "var(--vp-c-bg-soft)", borderRadius: 6 }}>
      当前值：<strong>{count}</strong>
    </div>
  );
}

function Controls() {
  return (
    <div style={{ display: "flex", gap: 8 }}>
      <Button onClick={() => store.count--}>-1</Button>
      <Button type="primary" onClick={() => store.count++}>+1</Button>
      <Button type="primary" mode="outline" onClick={() => (store.count = 0)}>重置</Button>
    </div>
  );
}

export default function SharedStore() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <Display />
      <Display />
      <Controls />
    </div>
  );
}

自动依赖追踪

只有依赖字段变化时才重渲染

tsx

import { Button } from "shineout";
import { create } from "@lite-code/reactive";

/**
 * 自动依赖追踪演示：
 * - CountPanel 只解构了 count，name 变化时不重渲染
 * - NamePanel 只解构了 name，count 变化时不重渲染
 * - 每个面板右上角的时间戳会在重渲染时更新，可直观看出哪个面板被触发
 */
const store = create({ count: 0, name: "Alice" });

function CountPanel() {
  const { count } = store.useSnapshot();
  return (
    <div style={{ padding: 12, border: "1px solid var(--vp-c-divider)", borderRadius: 6 }}>
      <div style={{ fontSize: 12, marginBottom: 4 }}>
        CountPanel 渲染时间：{new Date().toLocaleTimeString()}
      </div>
      <div>count = <strong>{count}</strong></div>
    </div>
  );
}

function NamePanel() {
  const { name } = store.useSnapshot();
  return (
    <div style={{ padding: 12, border: "1px solid var(--vp-c-divider)", borderRadius: 6 }}>
      <div style={{ fontSize: 12, marginBottom: 4 }}>
        NamePanel 渲染时间：{new Date().toLocaleTimeString()}
      </div>
      <div>name = <strong>{name}</strong></div>
    </div>
  );
}

const names = ["Alice", "Bob", "Carol", "Dave"];
let nameIdx = 0;

export default function TrackingDemo() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <CountPanel />
      <NamePanel />
      <div style={{ display: "flex", gap: 8 }}>
        <Button type="primary" onClick={() => store.count++}>
          改 count（只触发 CountPanel）
        </Button>
        <Button
          mode="outline"
          onClick={() => {
            nameIdx = (nameIdx + 1) % names.length;
            store.name = names[nameIdx];
          }}
        >
          改 name（只触发 NamePanel）
        </Button>
      </div>
    </div>
  );
}

注意：若直接使用整个快照对象（const snap = store.useSnapshot()）而不解构，等价于订阅所有字段，任意字段变化都会触发重渲染。

嵌套对象深层响应

深层嵌套属性修改

tsx

import { Button } from "shineout";
import { create } from "@lite-code/reactive";

/**
 * 嵌套对象深层响应：直接修改嵌套属性，无需手动 dispatch。
 */
const store = create({
  user: {
    name: "Alice",
    address: {
      city: "上海",
    },
  },
});

export default function NestedObject() {
  const { user } = store.useSnapshot();
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <div style={{ padding: 12, background: "var(--vp-c-bg-soft)", borderRadius: 6 }}>
        <div>姓名：{user.name}</div>
        <div>城市：{user.address.city}</div>
      </div>
      <div style={{ display: "flex", gap: 8 }}>
        <Button
          type="primary"
          onClick={() => {
            store.user.name = store.user.name === "Alice" ? "Bob" : "Alice";
          }}
        >
          切换姓名
        </Button>
        <Button
          mode="outline"
          onClick={() => {
            const cities = ["上海", "北京", "广州", "深圳"];
            const idx = cities.indexOf(store.user.address.city);
            store.user.address.city = cities[(idx + 1) % cities.length];
          }}
        >
          切换城市（深层嵌套）
        </Button>
      </div>
    </div>
  );
}

const store = reactive({
  user: {
    name: "Alice",
    address: { city: "上海" },
  },
});

// ✅ 任意层级直接赋值，自动触发更新
store.user.name = "Bob";
store.user.address.city = "北京";

限制：深层响应仅对普通对象生效，Array、Map、Set 等容器类型的方法（如 push、set）不会自动触发更新，需替换整个引用：

// ❌ push 不触发更新
store.list.push(1);

// ✅ 替换引用触发更新
store.list = [...store.list, 1];

重置初始状态

调用 store.restore() 将 store 的所有字段重置为初始值并触发视图更新。当所有订阅该 store 的组件全部卸载时，store 也会自动还原到初始状态，下次挂载时始终是干净的初始数据。

手动重置 store

tsx

import { Button } from "shineout";
import { create } from "@lite-code/reactive";

/**
 * restore 演示：将 store 重置回初始状态。
 */
const store = create({
  count: 0,
  name: "Alice",
});

export default function RestoreDemo() {
  const { count, name } = store.useSnapshot();
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
      <div style={{ padding: 12, background: "var(--vp-c-bg-soft)", borderRadius: 6 }}>
        <div>count = {count}</div>
        <div>name = {name}</div>
      </div>
      <div style={{ display: "flex", gap: 8 }}>
        <Button type="primary" onClick={() => store.count++}>count +1</Button>
        <Button
          mode="outline"
          onClick={() => {
            store.name = store.name === "Alice" ? "Bob" : "Alice";
          }}
        >
          切换 name
        </Button>
        <Button onClick={() => store.restore()}>
          ↺ 重置初始状态
        </Button>
      </div>
    </div>
  );
}

// 手动重置
store.restore();

最佳实践

Store 定义建议放在模块顶层

// store.ts
import reactive from "@lite-code/reactive";

export const userStore = reactive({
  name: "",
  age: 0,
  role: "viewer" as "viewer" | "editor" | "admin",
});

按功能拆分多个 store

// 避免一个巨大的全局 store，按功能域拆分
export const authStore = reactive({ token: "", userId: "" });
export const themeStore = reactive({ mode: "light", accent: "#6366f1" });
export const cartStore = reactive({ items: [] as CartItem[], total: 0 });

在事件处理函数中批量修改

// 多次赋值会触发多次 dispatch，如需批量更新，建议直接替换对象
store.user = { ...store.user, name: "Bob", age: 25 };

API

reactive(initialState)

创建并返回一个响应式 store。

参数	类型	说明
initialState	T	store 的初始状态对象

返回值 T & { useSnapshot, restore }

---

store.useSnapshot()

React Hook，在组件中订阅 store，返回当前快照（浅冻结）。

• 自动追踪本次渲染中访问过的 key，仅当这些 key 对应的值变化时才触发重渲染
• 返回值顶层属性被 Object.freeze 保护，严格模式下直接修改会抛出运行时异常
• 必须在 React 函数组件或自定义 Hook 内调用（遵循 React Hooks 规则）

const { count, name } = store.useSnapshot();

---

store.restore()

将 store 重置为 reactive() 调用时传入的初始状态，并触发视图更新。

store.restore();

---

内部保留属性

以下属性名为 store 内部保留，不可作为 state 的 key 使用：

属性名	说明
state	原始 state 对象
originStore	初始状态快照（供 restore 用）
listeners	订阅者集合
subscribe	订阅方法
getSnapshot	快照读取方法
dispatch	内部触发更新方法
useSnapshot	React Hook
restore	重置方法

TypeScript 会在编译期对使用保留名的 state key 进行报错提示。