状态管理 | LWC State Managers | Salesforce CRM 中文站

跨 LWC 组件管理状态（State Managers）

随着应用复杂度增长，管理数据流、确保组件响应变更、保持代码整洁面临挑战。LWC 状态管理通过 State Manager 提供原生解决方案——一个封装相关数据集（状态）+ 操作这些数据的函数（动作）的专用 JavaScript 模块。暂不支持 Experience Cloud。

State Manager 由三要素组成：提供给 defineState() 的实现函数、一组命名属性（简单值或派生/computed 值）、一组命名动作（修改状态的函数）。State Manager 与 LWC 响应式系统集成——状态变更自动触发组件更新和重渲染。

状态管理 —— 概念与优势

传统方案适用简单场景：父传子属性（向下）、子传父事件（向上）。但当组件层次超过十几层时变得繁琐。State Manager 像"黑盒"——持有相关数据值并一致管理：

六大优势：

减少 Prop Drilling：深层嵌套子组件无需通过每个中间组件显式传递属性即可访问状态
分离数据与展示：将数据检索、转换和业务逻辑与 UI 组件的展示逻辑解耦——代码更易测试维护
集中状态逻辑：状态定义和更新逻辑放在一起——更容易理解数据如何随时间变化
改善性能与数据编排：数据加载与组件渲染解耦——可预取数据、在渲染前加载
管理复杂状态交互：提供惯用、健壮的方式处理状态依赖和频繁更新
可重用性：状态逻辑封装后可在整个应用甚至不同应用中重用

两种共享方式：组件子树中的组件通过层次访问（fromContext）；从共享模块导出单例——所有导入的组件获得同一实例。

defineState —— 语法与结构

defineState 接受一个回调函数作为参数——这个函数就是你的 State Manager。函数接收两个参数：一个包含原语（{ atom, computed, setAtom }）的对象，以及任意数量的初始化参数（可设默认值）。

import { defineState } from "@lwc/state";

const counterManager = defineState(
  ({ atom, computed, setAtom }, initialValue = 0) => {
    const count = atom(initialValue);                          // 创建响应式状态
    const increment = () => { setAtom(count, count.value + 1); };  // 定义动作
    return { count, increment };                               // 返回公共 API
  }
);

// 使用——调用 state manager 函数创建实例（每个实例独立状态）
counter = counterManager(100);                // 初始值 100
// 模板中：{counter.value.count}             // 读取状态
// JS 中：this.counter.value.increment();    // 调用动作

每个 State Manager 实例有自己独立的值集。.value 是访问状态和动作的入口——模板中用 {counter.value.count}，JS 中用 this.counter.value.increment()。

状态管理原语 —— atom 与 computed

atom(value) —— 响应式数据单元

代表单个响应式数据片段。变更时自动触发使用该 atom 的组件更新和依赖派生值的重新计算。只能用 setAtom 修改。可包装任何 JS 值，但推荐使用JSON 可序列化值或 undefined。不公开的内部 atom 可省略在 return 中。

computed([deps], fn) —— 派生值

从其他 atom 或 computed 值派生的数据。依赖变化时自动重新计算。第一个参数是依赖数组，第二个是计算函数——接收与依赖数组等量的参数（每个依赖的当前值）。

const count = atom(0);
const doubleCount = computed([count], (countValue) => countValue * 2);  // 依赖 count
// count 变化 → doubleCount 自动重新计算

// 多依赖示例：
const total = computed([price, quantity], (p, q) => p * q);

与 atom 一样，仅内部使用的 computed 可省略在 return 中。

动作、公共 API 与计数器完整示例

动作（Actions）：用 setAtom 修改状态的函数——唯一的修改方式。可同步/异步、可接受参数、可返回值或不返回。用 const 保存，在 return 中公开。

// 完整 State Manager——atom + computed + 两个动作
const counterManager = defineState(({ atom, computed, setAtom }, initialValue = 0) => {
  const count = atom(initialValue);
  const doubleCount = computed([count], (cv) => cv * 2);
  const increment = () => setAtom(count, count.value + 1);
  const setCount = (newValue) => setAtom(count, Number(newValue));
  return { count, doubleCount, increment, setCount };
});

// 组件中使用
counter = counterManager(100);
handleIncrement() { this.counter.value.increment(); }
handleSetCount() { this.counter.value.setCount(Number(this.refs.newValue.value)); }
get stateDump() { return JSON.stringify(this.counter.value, null, 2); }

反模式：不要根据初始化参数有条件地返回不同形状的 API（如只有偶数时包含某个动作）——消费者无法依赖 API 的一致性。

跨组件共享 State Manager —— fromContext 模式

共享 State Manager 需将定义放在独立的 API 模块组件中（最佳实践——无 .html 文件）。父组件（Provider）创建实例，子组件（Consumer）通过 fromContext 获取引用：

// c/smCounter.js —— API 模块组件（State Manager 定义）
import { defineState } from '@lwc/state';
const counterManager = defineState(({ atom, computed, setAtom }, initialValue = 0) => {
  const count = atom(initialValue);
  const increment = () => setAtom(count, count.value + 1);
  return { count, increment };
});
export default counterManager;

// c/multiCounter.js —— Provider 父组件（创建实例）
import counterManager from 'c/smCounter';
export default class MultiCounter extends LightningElement {
  counter = counterManager(100);  // 创建共享实例
}

// c/counterDisplay.js —— Consumer 子组件（获取引用）
import { fromContext } from '@lwc/state';
import counterManager from 'c/smCounter';
export default class CounterDisplay extends LightningElement {
  counter = fromContext(counterManager);  // 从组件上下文获取
  // 模板中：{counter.value.count}——自动响应变更
}

解析时机：Provider 必须在连接到 DOM 时拥有 state manager 引用，connected 后不能更改该引用。Consumer 在connectedCallback 运行前收不到 state manager 引用——不能在 constructor 中访问。Consumer 从自身开始向上查找最近的匹配类型实例。

嵌套 State Manager —— 平台集成

State Manager 可以嵌套——一个 State Manager 内部使用另一个 State Manager。Salesforce 提供内置平台 State Manager（如 lightning/stateManagerRecord 和 lightning/stateManagerLayout），替代直接调用 UI API 或 @wire：

import smRecord from "lightning/stateManagerRecord";
import smLayout from "lightning/stateManagerLayout";

// 数据瀑布模式——三层依赖链：
// 1. recordId+objectApiName → minimalRecord（获取 recordTypeId）
// 2. objectApiName+recordTypeId → layout（获取布局字段列表）
// 3. recordId+fields → finalRecord（获取完整字段值）

const config = atom({ recordId, objectApiName });
const initialRecord = smRecord(computed([config], ({ recordId, objectApiName }) =>
  (!recordId || !objectApiName) ? {} : { recordId, fields: [`${objectApiName}.Id`] }
));
const layout = smLayout(computed([initialRecord], ({ data: recordData }) =>
  !recordData ? {} : { objectApiName: recordData.apiName, recordTypeId: recordData.recordTypeId, layoutType: "Compact", mode: "View" }
));
const finalRecord = smRecord(computed([initialRecord, layout], (...) => ...));

// 派生状态——status 根据所有子 State Manager 的状态计算
const status = computed([initialRecord, layout, finalRecord],
  (ir, l, fr) => /* 逻辑 */);
// unconfigured → loading → error / loaded

关键模式：返回空对象 {} 让嵌套 State Manager 等待——直到依赖数据就绪。computed 自动追踪依赖链——上游变化→下游自动重新配置。最终暴露 data、error、status 给消费者。

State Management 示例与参考

State Management 在 GitHub 有专门仓库：forcedotcom/state-management。包含两个示例：

platform-state-managers：最简实现——展示定义 State Manager、使用它获取 Salesforce 元数据和数据、在 UI 中显示。演示嵌套内置 state manager 替代 @wire。
simple-store：更复杂——购物车状态管理。不获取 Salesforce 数据，展示如何构建和操作本地数据（尚未发送服务器的数据），同时保证一致性逻辑。

lwc-recipes 中也有示例：opportunitiesStateManager 模块、opportunitiesList 组件、opportunitiesSummary 组件。

感谢阅读本指南。如需继续学习，请参阅下一章：调用 Apex 方法。

跨组件管理状态 — LWC State Managers 完全指南