@codewithdan/observable-store

可观察存储器 - 前端应用程序(Angular、React、Vue.js等)的国家管理

可观察存储器(Observative Store)是一个前端状态管理库,在前端应用程序中提供了简单而强大的状态管理方法. 前端国家管理变得如此复杂,以至于我们许多人花费更多的时间来制定国家管理规范,而不是其他应用. 可观察商店有一个总体目标——"保持简单".

可观测商店的目标是提供一个小型、简单和一致的方法,在任何前端应用程序(Angular、React、Vue.js等)中管理状态,同时实现许多 关键目标 由更为复杂的国家管理解决方案提供。 虽然许多前端框架/图书馆提供状态管理功能,但许多可能过于复杂,只能与目标框架/图书馆相通. 可观察存储器很简单,可以和任何前端JavaScript代码库一起使用.

• 关于可观察存储的博客帖

• 在可观察存储器上说话

可观察存储的关键目标 :

1. 简单点!
2. 国家唯一的真相来源
3. 存储状态不可改变
4. 向任何订阅者提供状态更改通知
5. 音轨状态变化历史
6. 以启动所需的最低数量代码容易理解
7. 用 JavaScript 或 TypeScript (Angular, React, Vue 等) 构建的任何前端工程的工程
8. 与 Redux DevTools 集成( 目前支持的 Angular 和 React)

兼容性

• 角 17 + 变相 — 使用可观察存储器 页:1 (单位:千美元)npm install @codewithdan/observable-store(中文(简体) )
• 角数 14-16 — 使用可观察存储器 v2.2.15 (中文(简体) ) (单位:千美元)npm install @codewithdan/[email protected](中文(简体) )
• 反应,Vue,和香草JS ——v3与任何现代设置合作

开发设置

在本地运行此 repo 的样本 :

1. 首先构建核心模块:

   npm run build
   

2. 然后进入任何样本并安装+开始:

   cd samples/angular-store
   npm install
   npm start
   

使用可观察存储的步骤

以下是一个简单的开始使用可观察商店的例子. 请注意,如果您正在使用TypeScript,您可以通过使用接口或类来提供存储状态的额外细节(下面可以找到其他实例).

1. 安装可观察存储软件包 :

   npm install @codewithdan/observable-store

2. 安装 RxJS - 如果您的工程还没有引用它, 需要对等依赖 :

   npm install rxjs

3. 创建扩展的类 ObservableStore设置 super() 在您的班级的构造器中( e)查看可观察存储设置) (中文(简体) ). 虽然这显示了纯粹的JavaScript方法,可观察Store也接受代表存储类型的通用. 详见下文"角"的例子.

   export class CustomersStore extends ObservableStore {
   
       constructor() {
           super({ /* add settings here */ });
       }
   
   }
   

4. 使用 setState(state, action)。 。 。 .

   addCustomerToStore(newCustomer) {
       this.setState({ customer: newCustomer }, 'add_customer');
   }
   

5. 使用 getState()。 。 。 .

   getCustomerFromStore() {
       this.getState().customer;
   }
   

6. 使用商店的 stateChanged 可见.

   // Create CustomersStore object or have it injected if platform supports that
   
   init() {
       this.storeSub = this.customersStore.stateChanged.subscribe(state => {
           if (state) {
               this.customer = state.customer;
           }
       });
   }
   
   // Note: Would need to unsubscribe by calling this.storeSub.unsubscribe()
   // as the target object is destroyed
   

7. 访问存储状态历史 CustomersStore 通过呼叫 stateHistory 财产(此处假定: trackStateHistory 设置设定为 true(中文(简体) )

   console.log(this.stateHistory);
   

API 和设置

可观察存储 API

可观察存储设置

可观察存储全局设置

可观察存储扩展

运行样本

打开 samples 在 Github Repo 上可用的文件夹,并遵循所提供样本项目在readme 文件中提供的指令.

样本应用程序

• 使用带有角的可观察存储器
• 使用可观察存储和反应
• 使用带有 JavaScript 的可观察存储器

使用带有角的可观察存储器

见 samples github repo 中的文件夹,用于使用 Angular 的可观察存储器.

1. 使用 Angular CLI 或其他选项创建角应用程序.

2. 安装 @codewithdan/observable-store数字 :

   npm install @codewithdan/observable-store

3. 添加一个界面或模型对象,代表您要添加到您的存储中的数据的形状. 以下是存储客户状态的接口示例:

   export interface StoreState {
       customers: Customer[];
       customer: Customer;
   }
   

4. 添加一个服务(如果您愿意,您可以选择称之为商店),扩展可观测站. 将显示您存储数据形状的接口或模型类传递给 T , 如下所示:

   @Injectable({ providedIn: 'root' })
   export class CustomersService extends ObservableStore<StoreState> {
   
   }
   

5. 在构造器中添加一个调用到 super()。商店允许您打开或关闭存储状态变化的跟踪 trackStateHistory 属性。 见列表 可观察存储设置。 。 。 .

   constructor() { 
       super({ trackStateHistory: true });
   }
   

6. 将函数添加到您的服务/ 仓库中, 以获取、 存储、 排序、 过滤或执行您想要的任何动作 。 更新商店电话 setState() 然后通过正在发生的动作 以及商店状态。 让州里的人离开店里 getState()。请注意,存储数据是不可改变的 getState() 总是返回存储数据的克隆。 这里有一个简单的例子:

   @Injectable({ providedIn: 'root' })
   export class CustomersService extends ObservableStore<StoreState> {
       sorterService: SorterService;
   
       constructor(sorterService: SorterService) { 
           const initialState = {
               customers: [],
               customer: null
           }
           super({ trackStateHistory: true });
           this.setState(initialState, 'INIT_STATE');
           this.sorterService = sorterService;
       }
   
       get() {
           const { customers } = this.getState();
           if (customers) {
               return of(customers);
           }
           // call server and get data
           // assume async call here that returns observable
           return asyncData;
       }
   
       add(customer: Customer) {
           let state = this.getState();
           state.customers.push(customer);
           this.setState({ customers: state.customers }, 'ADD_CUSTOMER');
       }
   
       remove() {
           let state = this.getState();
           state.customers.splice(state.customers.length - 1, 1);
           this.setState({ customers: state.customers }, 'REMOVE_CUSTOMER');
       }
       
       sort(property: string = 'id') {
           let state = this.getState();
           const sortedState = this.sorterService.sort(state.customers, property);
           this.setState({ customers: sortedState }, 'SORT_CUSTOMERS');
       }
   
   }
   

   虽然字符串用于前几个示例中的动作,但是如果想要有一组动作列表从中选择,也可以使用字符串enums(TypeScript特性):

       export enum CustomersStoreActions {
           AddCustomer = 'ADD_CUSTOMER',
           RemoveCustomer = 'REMOVE_CUSTOMER',
           GetCustomers = 'GET_CUSTOMERS',
           SortCustomers = 'SORT_CUSTOMERS'
       }
   
       // Example of using the enum in a store
       add(customer: Customer) {
           let state = this.getState();
           state.customers.push(customer);
           this.setState({ customers: state.customers }, CustomersStoreActions.AddCustomer);
       }
   

7. 如果您想要查看商店的所有更改, 您可以访问 stateHistory 属性 :

   console.log(this.stateHistory);
   

8. 州历史产出的一个例子如下:

   // example stateHistory output
   [
       {
           "action": "INIT_STATE",
           "beginState": null,
           "endState": {
               "customers": [
                   {
                       "id": 1545847909628,
                       "name": "Jane Doe",
                       "address": {
                           "street": "1234 Main St.",
                           "city": "Phoenix",
                           "state": "AZ",
                           "zip": "85258"
                       }
                   }
               ],
               "customer": null
           }
       },
       {
           "action": "ADD_CUSTOMER",
           "beginState": {
               "customers": [
                   {
                       "id": 1545847909628,
                       "name": "Jane Doe",
                       "address": {
                           "street": "1234 Main St.",
                           "city": "Phoenix",
                           "state": "AZ",
                           "zip": "85258"
                       }
                   }
               ],
               "customer": null
           },
           "endState": {
               "customers": [
                   {
                       "id": 1545847909628,
                       "name": "Jane Doe",
                       "address": {
                           "street": "1234 Main St.",
                           "city": "Phoenix",
                           "state": "AZ",
                           "zip": "85258"
                       }
                   },
                   {
                       "id": 1545847921260,
                       "name": "Fred",
                       "address": {
                           "street": "1545847921260 Main St.",
                           "city": "Phoenix",
                           "state": "AZ",
                           "zip": "85258"
                       }
                   }
               ],
           "customer": null
           }
       }
   ]
   

9. 任何组件都可以通过注入存储器并订阅存储器来通知存储状态的变化 stateChanged 可观测 :

   customers: Customer[];
   storeSub: Subscription;
   
   constructor(private customersService: CustomersService) { }
   
   ngOnInit() {
       // If using async pipe (recommend renaming customers to customers$)
       // this.customers$ = this.customersService.stateChanged;
   
       // Can subscribe to stateChanged observable of the store
       this.storeSub = this.customersService.stateChanged.subscribe(state => {
           if (state) {
               this.customers = state.customers;
           }
       });
   
       // Can call service/store to get data directly 
       // It won't fire when the store state changes though in this case
       //this.storeSub = this.customersService.get().subscribe(custs => this.customers = custs);
   }
   

Unsubscribe when the component is destroyed to avoid memory leaks:

``` typescript
ngOnDestroy() {
    if (this.storeSub) {
        this.storeSub.unsubscribe();
    }        
}
```

使用可观察存储和反应

见 samples/react-store github repo 中的完整示例文件夹.

1. 使用 维特 或另一个工具 :

   npm create vite@latest my-app -- --template react
   

2. 安装 @codewithdan/observable-store 和 RxJS 数据 :

   npm install @codewithdan/observable-store rxjs
   

3. 创建扩展的存储类 ObservableStore数字 :

   import { ObservableStore } from '@codewithdan/observable-store';
   
   class CustomersStore extends ObservableStore {
   
       constructor() {
           super({ trackStateHistory: true });
       }
   
       fetchCustomers() {
           return fetch('/customers.json')
               .then(response => response.json())
               .then(customers => {
                   this.setState({ customers }, 'GET_CUSTOMERS');
                   return customers;
               });
       }
   
       getCustomers() {
           const state = this.getState();
           if (state && state.customers) {
               return Promise.resolve(state.customers);
           }
           return this.fetchCustomers();
       }
   }
   
   export default new CustomersStore();
   

4. 使用带有钩子的组件中的商店. 订阅 stateChanged 在一个 useEffect 并在卸载上清理:

   import { useState, useEffect } from 'react';
   import CustomersStore from '../stores/CustomersStore';
   
   function CustomersList() {
       const [customers, setCustomers] = useState([]);
   
       useEffect(() => {
           // Subscribe to store state changes
           const sub = CustomersStore.stateChanged.subscribe(state => {
               if (state && state.customers) {
                   setCustomers(state.customers);
               }
           });
   
           // Trigger the initial data fetch
           CustomersStore.getCustomers();
   
           // Cleanup subscription on unmount
           return () => sub.unsubscribe();
       }, []);
   
       return (
           <ul>
               {customers.map(cust => (
                   <li key={cust.id}>{cust.name}</li>
               ))}
           </ul>
       );
   }
   
   export default CustomersList;
   

使用带有 JavaScript 的可观察存储器

见 samples/javascript-demo github repo 中的完整示例文件夹。 可观察 Store 与 plain JavaScript 工作——不需要框架.

1. 创建工程 维特 或任何捆绑器,然后安装可观察存储 :

   npm install @codewithdan/observable-store rxjs
   

2. 创建存储类并直接使用 :

   import { ObservableStore } from '@codewithdan/observable-store';
   
   class CustomersStore extends ObservableStore {
       constructor() {
           super({ trackStateHistory: true, logStateChanges: true });
       }
   
       addCustomer(customer) {
           const state = this.getState();
           const customers = state?.customers ? [...state.customers, customer] : [customer];
           this.setState({ customers }, 'ADD_CUSTOMER');
       }
   }
   
   const store = new CustomersStore();
   
   // Subscribe to state changes
   store.stateChanged.subscribe(state => {
       if (state) {
           console.log('Customers:', state.customers);
       }
   });
   
   // Update state
   store.addCustomer({ id: 1, name: 'Jane Doe' });
   

存储 API

Observable Store提供了一个简单的API,可用于获取/设置状态,订阅以存储状态变化,以及访问状态历史. 如果您是新到 TypeScript 通用软件,则 T 下面的 API 显示为您的商店状态 .

注意TypeScript类型用于描述以上参数和返回类型. TypeScript 虽然不需要使用可观察存储 .

传递函数到设置状态( C)

以下是将一个函数传递给 setState()。这允许在设置新状态时直接访问以前的状态.

this.setState(prevState => { 
    return { customers: this.sorterService.sort(prevState.customers, property) };
}, 'SORT_CUSTOMERS');

存储设置( 每个服务)

可观察存储器设置可以在存储器初始化(当一个服务中调用超级())时被通过. 这使得您可以控制您在扩展商店的应用程序中的每项服务的运作方式.

通过设置到商店的例子 :

export class CustomersStore extends ObservableStore {

    constructor() {
        super({ /* add settings here */ });
    }

}

使用状态SliceSelector () 函数

这个 stateSliceSelector() 函数可以用来返回由服务处管理的存储状态的“切片”。 例如,如果客户服务公司管理一个 customers 收集资料和a selectedCustomer 只返回对象 selectedCustomer 对象到订阅者(而不是 customers 财务报告和审定财务报表 selectedCustomer(通过创建 stateSliceSelector() 函数.

定义为您在通过时初始化服务 settings 对象 super() 在服务建筑师.

export class CustomersService extends ObservableStore<StoreState> {
  constructor() { 
    super({ stateSliceSelector: state => { 
        return {
          customer: state.selectedCustomer
          // return other parts of the store here too if desired
        };
      } 
    });
 }
}

全局存储设置

如果需要,您可以为整个应用程序在全球设置以下可观察存储设置 。 详情请查看 可观察存储设置 节。 这使得您可以一次性定义设置, 所有扩展可观察存储的服务都会自动取取这些设置 。 您可以在服务级别上覆盖这些属性, 当您希望某个特定服务拥有更多的记录( 例如) 而其它服务则没有时, 这样做也很好 .

• trackStateHistory
• logStateChanges

全局存储设置在应用程序时定义 ONCE 第一个初始化 在使用该商店之前:

ObservableStore.globalSettings = {  /* pass settings here */ };

扩展

可观察 Store 现在支持扩展 。 这些可以在应用程序首次通过调用加载时添加 ObservableStore.addExtension()。 。 。 .

Redux DevTools 扩展

第一个内置扩展增加 Redux 开发工具 集成到使用可观察存储的应用程序中。 扩展名可见于 @codewithdan/observable-store-extensions 软件包.

说明 __devTools 存储属性 :

启用 Redux DevTools 扩展后, 将使用名为属性的路径信息添加到您的仓库 __devTools。此属性用于启用 Redux DevTools 时间旅行特性,并可用于将不同的动作状态与给定的路由连接起来,同时手动查看使用 DevTools 的存储数据。 如果 Redux DevTools 扩展未启用(例如生产情景),则 __devTools 属性不会被添加到您的商店中 .

将 Angular 与 Redux DevTools 整合

参见 samples/angular-store 文件夹.

安装扩展包 :

npm install @codewithdan/observable-store-extensions

将以下内容添加到 main.ts 和确保你设置 trackStateHistory 改为 true数字 :

import { ObservableStore } from '@codewithdan/observable-store';
import { ReduxDevToolsExtension } from '@codewithdan/observable-store-extensions';

...

ObservableStore.globalSettings = {  
    trackStateHistory: true
};
ObservableStore.addExtension(new ReduxDevToolsExtension());

安装 Redux DevTools 扩展 在浏览器中运行您的 Angular 应用程序,并打开 Redux DevTools 扩展名.

与 Redux DevTools 集成反应

参见 samples/react-store 文件夹.

安装扩展包 :

npm install @codewithdan/observable-store-extensions

在您的应用程序的切入点中添加以下内容( 例如 ), main.jsx),并确保设置 trackStateHistory 改为 true数字 :

import { ObservableStore } from '@codewithdan/observable-store';
import { ReduxDevToolsExtension } from '@codewithdan/observable-store-extensions';

ObservableStore.globalSettings = {  
    trackStateHistory: true
};
ObservableStore.addExtension(new ReduxDevToolsExtension());

安装 Redux DevTools 扩展 在浏览器中,运行您的 React 应用程序,并打开 Redux DevTools 扩展名.

Redux 开发工具与生产

当你可以在生产中启用Redux DevTools扩展时,通常建议您去除. 可以通过自定义构建进程或通过检查您代码运行的环境来实现 .

角实例

import { isDevMode } from '@angular/core';

if (isDevMode()) {
    ObservableStore.addExtension(new ReduxDevToolsExtension());
}

反应示例

if (import.meta.env.DEV) {
    ObservableStore.addExtension(new ReduxDevToolsExtension());
}

变动

见 变动情况 为完整版本的历史.

项目建设

# Build both modules (observable-store + extensions)
npm run build

# Run tests
npm test