★ FEATURED ARTICLE 桌面应用【免费下载链接】VortexVortex Development项目地址https://gitcode.com/gh_mirrors/vor/Vortex点击查看免费下载本指南面向想在 Vortex Stardew Valley 扩展game-stardewvalley中新增或维护配置项的开发者以src/state/README.md为骨架结合仓库内真实源码与调用链系统讲解 Action、Reducer、Selector 三者分工、完整数据流与新增设置的标准化四步法。读完你将掌握在 state 目录 中安全读写settings.SDV状态、排查状态不更新问题的全部技巧。一分钟搞懂 Redux三个角色在 JavaScript/TypeScript 项目中Redux 是“整个应用共享的一份数据存储”。对于新手可以用最朴素的心智模型记住三个角色Action动作 “一句描述发生了什么的消息”例如“用户打开了合并配置开关”“用户关闭了推荐功能”。Action 本身不修改数据它只是把“发生了什么”和携带的参数payload发给 Reducer。Reducer归约器 “负责更新已保存数据的代码”它接收当前状态 action 载荷返回一份新的状态对象。它是唯一被允许“写”状态的地方。Selector选择器 “负责安全读取已保存数据的辅助函数”普通代码不直接伸手进状态对象深处取数而是通过 Selector 以类型安全、带默认值的方式读取。铁律UI 代码永远不直接修改 Redux 状态。正确姿势永远是“先 dispatch 一个 action再由 Reducer 去更新状态”随后 UI 通过订阅状态的变化自动重渲染。这个文件夹里有什么state目录下只有三个源文件职责划分清晰详见 state 目录文件结构文件职责对应源码actions.ts定义用于更新settings.SDV的 action creatoractions.tsreducers.ts处理这些 action并把结果写入settings.SDVreducers.tsselectors.ts从 Redux 状态树中安全读取嵌套值selectors.ts这个扩展的状态以settings.SDV为根挂载。在扩展入口 index.ts 中可以看到挂载代码// Register the game definition and SDV-specific reducer state. context.registerGame(new StardewValleyGame(context)); context.registerReducer([settings, SDV], sdvReducers);也就是说reducers.ts默认导出的 reducer spec 被注册到全局状态路径[settings, SDV]之后所有通过state.settings[SDV]读取的数据都归这个 reducer 管理。真实数据流以“管理 SDV 配置文件”开关为例README 用“用户开启 Manage SDV mod configuration files”这一真实功能演示完整闭环。结合源码我们可以把每一步落得更细UI dispatch用户在 Settings.tsx 中点击 Toggle回调setMergeConfigSetting会调用onMergeConfigToggle(profileId, enabled)该回调注册于 registerUi.ts最终执行context.api.store?.dispatch(setMergeConfigs(profileId, enabled))。Reducer 处理setMergeConfigs的 payload 是{ profileId, enabled }对应 handlerreducers.ts执行util.setSafe(state, [mergeConfigs, profileId], enabled)。状态写入结果被写入settings.SDV.mergeConfigs[profileId] true。其他代码读取例如同步引擎 sync.ts 调用selectMergeConfigsEnabled(state, profile.id)判断当前 profile 是否处于合并配置模式进而决定扫描config.json并归入合成配置 mod文件事件处理 ingest.ts 也依赖同一 selector 决定新文件的归属路径。新增一个设置项复制这个四步模式这是 README 的核心实战章节完整照搬并结合真实源码补齐说明。第一步在actions.ts中添加 actionexport const setExampleFlag createAction(SET_SDV_EXAMPLE_FLAG, (enabled: boolean) enabled);createAction来自redux-act见 actions.ts 顶部 import。第一个参数是全局唯一的 action 类型字符串命名习惯SET_SDV_*前缀与现有SET_SDV_RECOMMENDATIONS、SET_SDV_MERGE_CONFIGS保持一致第二个参数是 payload 构造器。若需要携带复合载荷可参考真实实现setMergeConfigs返回{ profileId, enabled }对象export const setMergeConfigs createAction( SET_SDV_MERGE_CONFIGS, (profileId: string, enabled: boolean) ({ profileId, enabled }), );第二步在reducers.ts中处理并补充默认值[actions.setExampleFlag as any]: (state, payload) { return util.setSafe(state, [exampleFlag], payload); },同时必须在defaults中加入默认值defaults: { useRecommendations: false, exampleFlag: false, }对照真实源码reducers.ts定义了状态形状接口IStateSDV与默认值export interface IStateSDV { useRecommendations: boolean; mergeConfigs?: { [profileId: string]: boolean }; } const sdvReducers: types.IReducerSpecIStateSDV { reducers: { /* ... */ }, defaults: { useRecommendations: false, }, };两点必须注意的实现细节handler 中使用的是util.setSafe来自nexusmods/vortex-api它会沿路径安全写入避免手动展开嵌套对象造成不可变更新的遗漏文件末尾将 reducer spec 断言为types.IReducerSpec导出因为扩展 API 期待通用 reducer spec 类型源码注释中明确说明 “Needed because the API expects the generic IReducerSpec”见 reducers.ts。第三步在selectors.ts中添加选择器export function selectExampleFlag(state: types.IState): boolean { return util.getSafe(state, [settings, SDV, exampleFlag], false); }注意这里把settings与SDV一并写进路径因为全局状态树的根在settings之下第三个参数是读取失败时的兜底默认值。对照仓库中真实 selector 的写法selectors.ts例如export function selectMergeConfigsEnabled(state: types.IState, profileId: string): boolean { return util.getSafe(state, [settings, SDV, mergeConfigs, profileId], false); }selectors.ts中并非所有选择器都挂在settings.SDV下它们同样负责读取游戏发现路径、mod 列表等selectSdvDiscoveryPath读取settings.gameMode.discovered.stardewvalley.path游戏安装路径供 index.ts 的getGameInstallPath使用selectSdvMods读取persistent.mods.stardewvalley被 ModManifestCache.ts、transitions.ts、smapi/selectors.ts 等模块复用selectConfigModAttributes读取合成配置 mod 的attributes.configMod追踪数组。第四步在 UI 或功能代码中使用派发更新store.dispatch(setExampleFlag(true));读取当前值const enabled selectExampleFlag(state);真实 UI 的写法Settings.tsx展示了标准范式用useSelector((state: any) state.settings[SDV])订阅状态用useStore().dispatch(...)派发 actionconst sdvSettings useSelector((state: any) state.settings[SDV]); const { useRecommendations, mergeConfigs } sdvSettings; const setUseRecommendations React.useCallback((enabled: boolean) { store.dispatch(setRecommendations(enabled)); }, []);至此一个完整的 Redux 循环就闭环了dispatch → reducer 更新 → selector 读取 → UI 重渲染。状态形状一览settings.SDV到底长什么样结合IStateSDV接口与各处读取点可以画出这个扩展管理的关键状态路径settings.SDV ├── useRecommendations: boolean // 安装时是否给出依赖推荐默认 false └── mergeConfigs?: { [profileId]: boolean } // 按 profile 记录是否合并 config.json settings.gameMode.discovered.stardewvalley.path // 游戏发现路径selectSdvDiscoveryPath persistent.mods.stardewvalley // 该游戏的 mod 列表selectSdvMods persistent.mods.stardewvalley.id.attributes.configMod // 合成配置 mod 追踪的 mod id 数组其中mergeConfigs是“按 profile 键控”的映射结构这解释了为什么相关 action 与 selector 都要求传入profileIdVortex 支持多 profile配置开关必须按 profile 隔离存储。从状态到行为这些设置项被谁消费仅“写进状态”没有意义状态的价值在于被其他模块读取并驱动行为。在本仓库中可以追踪到以下消费链useRecommendations历史上用于在安装 manifest 型 mod 时按依赖生成“推荐安装”规则见 stardewValleyInstaller.ts当前该逻辑已被注释UI 中的对应 Toggle 目前为disabled{true}状态见 Settings.tsx。mergeConfigs[profileId]是 config-mod 功能的总开关被 sync.ts、ingest.ts、lifecycle.ts 三处读取开启时把游戏运行生成的config.json归集到名为 “Stardew Valley Configuration ( )” 的合成 mod 中避免 mod 更新/卸载导致配置丢失关闭或显式 revert时 transitions.ts 的onRevertFilesImpl会把追踪的配置文件归还回原 mod 目录。这印证了 README 的核心主张UI 只负责 dispatchReducer 负责落盘Selector 负责供出业务模块负责消费。快速排障清单README 给出了三类最典型的问题这里结合源码补充判定要点设置项没有变化检查 action 名称与 reducer handler 的键是否一致。handler 的键是[actions.xxx as any]若键写错例如少写SET_SDV_前缀或拼写不一致reducer 将静默不匹配、状态保持原样。读到的值永远是undefined检查 selector 路径与 reducer 写入路径是否完全一致。写入走util.setSafe(state, [...])读取走util.getSafe(state, [...])两处的路径数组必须逐段相同例如写入[mergeConfigs, profileId]读取就必须是[settings, SDV, mergeConfigs, profileId]前两段由挂载位置决定。UI 没有更新确认 UI 组件读的是 Redux 状态useSelector订阅的变量而不是某个仅存在于组件内部的局部变量。Redux 只有在状态引用变化时才会通知订阅者直接缓存局部值会绕过整个响应式链路。小结Vortex 的 Stardew Valley 扩展把“设置项”的增删改查收敛成一个高度模板化的流程actions.ts声明动作、reducers.ts落盘并维护默认值、selectors.ts安全读取、UI 与业务模块只消费。对照本文的“四步法”与真实源码中的setRecommendations/setMergeConfigs实例任何人都能在几分钟内为扩展新增一个状态项并在settings.SDV中安全地读写它。继续深入可以参考扩展入口与 reducer 挂载、UI 设置面板、config-mod 功能的完整说明。赞分享桌面应用【免费下载链接】VortexVortex Development项目地址https://gitcode.com/gh_mirrors/vor/Vortex点击查看免费下载相关推荐Vortex 的 Stardew Valley 游戏扩展深度解析SMAPI 模组安装、部署与配置管理实战Vortex 的 Stardew Valley 游戏扩展深度解析SMAPI 模组安装、部署与配置管理实战 本文以 Vortex 仓库中 extensions/桌面应用wp-calypso ActivePromotions 状态管理模块详解Redux Action / Reducer / Selector 全流程实战wp calypso ActivePromotions 状态管理模块详解Redux Action / Reducer / Selector 全流程实战 导读前端CMSwp-calypso Keyring Services 状态模块深度解析从 Action 到 Selector 的完整数据流wp calypso Keyring Services 状态模块深度解析从 Action 到 Selector 的完整数据流 导读 本文围绕 wp calyp前端CMS上一篇从底层到实战Cangjie-TPC/CJQT框架QCore模块深度剖析与应用指南下一篇从0到1精通开源字节/source-vue权限管理系统设计原理与实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
