# npm
npm install valtio
 
# yarn
yarn add valtio
 
# pnpm
pnpm add valtio
 
# bun
bun add valtio

import { proxy, useSnapshot } from 'valtio'
 
// 1. 创建 proxy 状态（像普通对象一样）
const state = proxy({
  count: 0,
  name: 'Valtio',
})
 
// 2. 在组件中使用 useSnapshot 读取（自动追踪依赖）
function Counter() {
  const snap = useSnapshot(state)
  return (
    <div>
      <p>Count: {snap.count}</p>
      <button onClick={() => state.count++}>+1</button>
    </div>
  )
}

import { proxy, useSnapshot, subscribe } from 'valtio'
 
// 1. 创建 proxy 状态
const state = proxy({
  todos: [],
  filter: 'all',
})
 
// 2. 直接修改（可变更新，无需 set/immutable）
function addTodo(text) {
  state.todos.push({ id: Date.now(), text, done: false })
}
 
function toggleTodo(id) {
  const todo = state.todos.find((t) => t.id === id)
  if (todo) todo.done = !todo.done  // 直接修改嵌套属性
}
 
// 3. 组件中自动响应（只重渲染依赖了变化属性的组件）
function TodoList() {
  const snap = useSnapshot(state)
  const filtered = snap.todos.filter((t) => {
    if (snap.filter === 'active') return !t.done
    if (snap.filter === 'done') return t.done
    return true
  })
 
  return (
    <div>
      <input
        placeholder="New todo"
        onKeyDown={(e) => {
          if (e.key === 'Enter') {
            addTodo(e.currentTarget.value)
            e.currentTarget.value = ''
          }
        }}
      />
      <select value={snap.filter} onChange={(e) => (state.filter = e.target.value)}>
        <option value="all">All</option>
        <option value="active">Active</option>
        <option value="done">Done</option>
      </select>
      <ul>
        {filtered.map((todo) => (
          <li key={todo.id} onClick={() => toggleTodo(todo.id)}>
            {todo.text} {todo.done ? '✅' : ''}
          </li>
        ))}
      </ul>
    </div>
  )
}
 
// 4. 组件外部也能订阅变化
subscribe(state, () => {
  console.log('State changed:', state)
})

const state = proxy({ count: 0, name: 'Valtio' })
 
function Counter() {
  const snap = useSnapshot(state)
  return <p>{snap.count}</p>  // 只有 count 变化时重渲染
}
 
function Name() {
  const snap = useSnapshot(state)
  return <p>{snap.name}</p>  // 只有 name 变化时重渲染
}

state.count++
state.user.name = 'Alice'  // 深层嵌套也能追踪
state.items.push({ id: 1 })

import { proxy, subscribe } from 'valtio/vanilla'
 
const state = proxy({ count: 0 })
subscribe(state, () => {
  document.getElementById('count').textContent = state.count
})

import { use } from 'react'
import { proxy, useSnapshot } from 'valtio'
 
const state = proxy({
  dataPromise: fetch('/api/data').then((r) => r.json()),
})
 
function DataDisplay() {
  const snap = useSnapshot(state)
  const data = use(snap.dataPromise) // React 19 use() Hook
  return <p>{data.message}</p>
}

import { proxy, useSnapshot } from 'valtio'
import { derive } from 'valtio/utils'
 
const state = proxy({
  items: [1, 2, 3, 4, 5],
  filter: 'all',
})
 
const derived = derive({
  activeItems: (get) => {
    const items = get(state).items
    const filter = get(state).filter
    return items.filter((i) => i > 2)
  },
  totalCount: (get) => get(state).items.length,
})

class CounterModel {
  count = 0
  increment() {
    this.count++
  }
}
 
const state = proxy(new CounterModel())

// Valtio：直接修改
state.users[0].profile.name = 'Alice'
 
// Zustand：需要展开
set((s) => ({
  users: s.users.map((u, i) =>
    i === 0 ? { ...u, profile: { ...u.profile, name: 'Alice' } } : u
  ),
}))
// 或借助 Immer 中间件

import { proxy, useSnapshot } from 'valtio'
 
// 类型推断：proxy() 自动推断类型
interface AppState {
  count: number
  user: {
    name: string
    age: number
  }
  todos: Array<{ id: number; text: string; done: boolean }>
}
 
const state = proxy<AppState>({
  count: 0,
  user: { name: '', age: 0 },
  todos: [],
})
 
// useSnapshot 返回只读的 snapshot 类型
function App() {
  const snap = useSnapshot(state)
  // snap.count 是 number (只读)
  // snap.user.name 是 string (只读)
  return <div>{snap.count}</div>
}

import { proxy, useSnapshot } from 'valtio'
import { derive } from 'valtio/utils'
 
const state = proxy({
  items: [
    { id: 1, text: 'Learn Valtio', done: true },
    { id: 2, text: 'Build app', done: false },
  ],
  filter: 'all' as 'all' | 'active' | 'done',
})
 
// derive 创建计算属性
const derived = derive({
  filteredItems: (get) => {
    const { items, filter } = get(state)
    switch (filter) {
      case 'active': return items.filter((i) => !i.done)
      case 'done': return items.filter((i) => i.done)
      default: return items
    }
  },
  activeCount: (get) => get(state).items.filter((i) => !i.done).length,
})
 
function TodoList() {
  const { filteredItems, activeCount } = useSnapshot(derived)
  return (
    <div>
      <p>{activeCount} items left</p>
      <ul>
        {filteredItems.map((item) => (
          <li key={item.id}>{item.text}</li>
        ))}
      </ul>
    </div>
  )
}

import { proxy, useSnapshot, subscribe } from 'valtio'
 
const state = proxy({ count: 0 })
 
// 从 localStorage 恢复
const saved = localStorage.getItem('count')
if (saved) state.count = JSON.parse(saved)
 
// 监听变化并持久化
subscribe(state, () => {
  localStorage.setItem('count', JSON.stringify(state.count))
})

import { proxy, snapshot, subscribe } from 'valtio'
 
test('proxy state updates', () => {
  const state = proxy({ count: 0 })
 
  state.count++
  expect(state.count).toBe(1)
 
  // snapshot 返回不可变副本
  const snap = snapshot(state)
  expect(snap.count).toBe(1)
})
 
test('subscribe fires on changes', () => {
  const state = proxy({ count: 0 })
  const callback = vi.fn()
 
  subscribe(state, callback)
  state.count++
 
  // 同一事件 tick 内的多次修改批次化为一次通知
  expect(callback).toHaveBeenCalledTimes(1)
})

// ✅ 直接修改属性（Proxy 自动追踪）
state.count++
state.user.name = 'Alice'
 
// ❌ 重新赋值根变量（破坏追踪）
let state = proxy({ count: 0 })
state = proxy({ count: 1 })  // 错误！根变量重新赋值会丢失追踪
 
// ✅ 正确做法：修改属性
const state = proxy({ count: 0 })
state.count = 1  // 正确

// ✅ 正确：通过 useSnapshot 读取
const snap = useSnapshot(state)
return <p>{snap.count}</p>
 
// ❌ 错误：直接读取 proxy 对象
return <p>{state.count}</p>  // 不会触发重渲染！

// ✅ 写入：通过 proxy 对象
const onClick = () => { state.count++ }
 
// ✅ 读取：通过 snapshot
const snap = useSnapshot(state)
return <p>{snap.count}</p>
 
// ❌ 不要在 snapshot 上写入
// snap.count++  // 报错：snapshot 是只读的

const state = proxy({ count: 0 })
 
// ❌ 错误：根变量重新赋值
state = proxy({ count: 1 })  // 丢失追踪
 
// ✅ 正确：修改属性
state.count = 1
 
// ✅ 正确：使用 Object.assign
Object.assign(state, { count: 1, name: 'new' })

import { derive } from 'valtio/utils'
 
// ✅ 使用 derive 替代手动维护派生值
const state = proxy({ items: [], tax: 0.1 })
const derived = derive({
  total: (get) => get(state).items.reduce((sum, i) => sum + i.price, 0),
  totalWithTax: (get) => get(derived).total * (1 + get(state).tax),
})

// 在组件外部监听状态变化（日志、持久化、同步）
const unsub = subscribe(state, () => {
  localStorage.setItem('app-state', JSON.stringify(snapshot(state)))
})
 
// 清理订阅
unsub()

import { proxy, ref } from 'valtio'
 
const state = proxy({
  count: 0,
  // ref() 包裹的对象不会被 Proxy 追踪
  // 适合存储 DOM 引用、第三方库实例等
  editor: ref(null),
  canvas: ref(null),
})

let state = proxy({ count: 0 })
state = proxy({ count: 1 })  // ❌ 新 proxy 与旧追踪断开