NgRx Signals 信号存储高级特性开发指南

信号存储模型的扩展需求

在NgRx Signals项目中，开发者经常需要创建自定义的信号存储特性来满足特定业务需求。近期社区提出了一个重要需求：需要将更多内部模型暴露给公共API，以便开发者能够构建更复杂的自定义特性。

核心问题分析

当前信号存储系统存在一个关键限制：一些关键类型如SignalStoreFeatureResult、StateSignals和Prettify等未被暴露在公共API中。这使得开发者在创建自定义特性时不得不依赖内部实现细节，这种做法存在以下问题：

1. 代码脆弱性：依赖内部实现容易在版本更新时出现兼容性问题
2. 重复代码：开发者需要自行重新实现基础功能
3. 类型安全性降低：缺乏官方类型支持导致类型推断不够精确

最佳实践解决方案

官方推荐的正确做法是使用现有的基础特性来构建自定义功能，而不是重新实现核心逻辑。以下是一个实现标签页可见性特性的示例：

type TabVisibilityMethod<Input extends SignalStoreFeatureResult> = (
  store: Prettify<
    StateSignals<Input['state']> &
      Input['computed']> &
      Input['methods']> &
      StateSource<Input['state']>
  >
) => void;

export function withTabVisibility<
  Input extends SignalStoreFeatureResult
>(methods: {
  onTabVisible?: TabVisibilityMethod<Input>;
  onTabHidden?: TabVisibilityMethod<Input>;
}): SignalStoreFeature<Input, { state: {}; computed: {}; methods: {} }> {
  return signalStoreFeature(
    type<Input>(),
    withHooks((store) => {
      const visibilityChangeFn = () => {
        document.hidden
          ? methods.onTabHidden?.(store)
          : methods.onTabVisible?.(store);
      };

      return {
        onInit() {
          document.addEventListener('visibilitychange', visibilityChangeFn);
        },
        onDestroy() {
          document.removeEventListener('visibilitychange', visibilityChangeFn);
        },
      };
    })
  );
}

即将公开的关键类型

为了支持这类高级用例，NgRx团队计划将以下关键类型加入公共API：

1. SignalStoreFeatureResult：表示信号存储特性的结果类型
2. StateSignals：处理状态信号的工具类型
3. Prettify：用于优化类型显示的工具类型
4. StateSource(原StateSignal)：表示状态源的接口

这些类型的分离设计提供了更好的灵活性，允许开发者根据需要组合不同的访问权限。例如，可以创建仅访问状态和计算信号的自定义方法：

type CustomFeatureMethod<Input extends SignalStoreFeatureResult> = (
  store: Prettify<StateSignals<Input['state']> & Input['computed']>
) => void;

版本兼容性说明

需要注意的是，在即将发布的v18版本中，StateSignal将被重命名为StateSource。开发者应关注这一变化以确保代码的向前兼容性。

总结

通过暴露这些关键类型，NgRx Signals将大大增强其扩展能力，使开发者能够构建更强大、类型安全的自定义特性，同时保持代码的稳定性和可维护性。建议开发者在创建自定义特性时遵循官方推荐模式，充分利用即将公开的公共API类型。