san-store

San 框架的官方应用状态管理套件，其理念是类似 flux 的单向流。

虽然应用状态管理已经是流行的理念，我们依然推荐您在开始之前，先看看 为什么要进行应用状态管理，可能会有些思考和启发。

提示：使用 san-store 需要同时使用 san-update 2.x 创建状态变更器，san-store 将使用此变更器更新 store 中的应用状态。

• 下载
• 使用
• 单Store与多Store
• Action
• 组件的connect
• API

下载

NPM:

$ npm i --save san-store san-update

使用

import {store, connect} from 'san-store';
import {builder} from 'san-update';


store.addAction('changeUserName', function (name) {
    return builder().set('user.name', name);
});


let UserNameEditor = connect({
    name: 'user.name'
})(san.defineComponent({
    submit() {
        store.dispatch('changeUserName', this.data.get('name'));
    }
}));

从例子开始和模仿比死啃枯燥的文档要更人性化。 Todos项目 和 RealWorld App 展示了如何在项目里使用 san-store 进行状态管理。 多store的Todos项目 展示了如何再项目中使用 多 store connect 及 composition api 的用法。

本文档描述了 san-store 的基本使用场景。想了解 san-store 都提供了什么，可以参阅 API文档

单Store与多Store

一个应用具有唯一的应用状态源，在一个地方管理整个应用的所有状态，是一个比较共识的方式。所以 san-store 提供了默认的 Store 实例。绝大多数时候，应用开发者不需要手工创建自己的 Store 实例，只需要 import 默认的 store。

import {store} from 'san-store';

// 通过 getState 方法，获取 store 中的状态数据。
console.log(store.getState('user.name'));

store 并没有提供修改状态数据的方法，修改状态数据只能通过 dispatch action 来做到，具体细节请参考 Action 章节。通过 addAction 方法可以添加 action。

store.addAction('changeUserName', name => builder().set('user.name', name));

当同一系统中有不同团队开发自己的业务模块，各团队之间没有状态共享，可以考虑分别建立 Store 实例进行开发。通过 new Store 创建自己的 Store 实例。创建时可以传入初始化数据和声明 actions。

import {Store} from 'san-store';
import {builder} from 'san-update';


let myStore = new Store({
    initData: {
        user: {
            name: 'your name'
        }
    },

    actions: {
        changeUserName(name) {
            return builder().set('user.name', name);
        }
    }
});

本节最后，还是要强调下，应用开发应当遵循 一个应用具有唯一的应用状态源。说白了就是 要按常理出牌。

Action

通过 addAction 方法可以为 Store 添加 Action。 Action 是 san-store 最重要的组成部分之一，它：

1. 是一个函数
2. 在一个 store 内每个 action 具有唯一名称，通过名称 dispatch
3. 是 store 更新状态的唯一入口
4. 状态更新是同步的，这使得状态更新可依赖当前状态环境，可被记录、被追溯和重放

如果你使用了 san-store，Action 应该是你业务组件的唯一出口：用户操作事件等需要改变应用状态时，都应该 dispatch Action。

变更应用状态

Action 接收一个 payload，返回一个 san-update 的 builder 对象。store 使用 builder 对象生成状态变更函数，并执行它，使 store 内部的状态得到更新。当然，如果当前 action 不期望对 store 的状态进行更新，可以不返回 builder 对象。

import {builder} from 'san-update';

store.addAction('changeUserName', function (name) {
    return builder().set('user.name', name);
});

// 通过名称 dispatch
store.dispatch('changeUserName', 'erik');

san-update 是一个 Immutable 的更新对象库，其提供了一些更新函数（如set、push等），通过 newObj = set(oldObj, 'x', 1) 的使用形式让对象更新 Immutable。builder 是 san-update 提供的一个很好用的功能，通过 builder 你可以预定义一系列的数据更新操作，然后通过 builder.build 方法可以获得一个更新函数。san-store 就是利用这个功能，使用 action 返回的 builder 生成对象更新函数，再调用它进行 store 内部状态更新。

san-update 的 builder 支持预定义所有 san-update 支持的数据操作，通过 san-update文档：可用指令 可以查看所有操作类型。常用的有：

• apply: 对现有数据项应用更新
• set: 设置数据项
• remove: 数组移除项
• push: 数组push操作
• pop: 数组pop操作
• unshift: 数组unshift操作
• shift: 数组shift操作
• splice: 数组splice操作

使用前请阅读 san-update文档：使用builder构建更新函数 进行详细了解。

获取当前应用状态

Action 的第二个参数是一个对象，其中的 getState 方法可以用于获得当前 store 中的应用状态。这个方法是 this 无关的。

import {builder} from 'san-update';

store.addAction('initCount', function (count, {getState}) {
    if (getState('count') == null) {
        return builder().set('count', count);
    }
});

store.dispatch('initCount', 10);

如果我们的更新操作仅依赖于当前数据状态项的值，也可以使用 san-update 提供的 apply 方法。

import {builder} from 'san-update';

store.addAction('initCount', function (count) {
    // apply 意思是：在原有的值上应用新的值
    return builder().apply('count', oldValue => {
        return oldValue == null ? count : oldValue;
    });
});

store.dispatch('initCount', 10);

异步过程

同步的 Action 返回一个 builder，并立即更新数据状态，但我们经常会遇到异步的场景，常见的比如请求数据、返回并更新应用状态。Action 在设计上作为 业务组件的唯一出口， 对异步支持的方式如下：

1. 返回一个 Promise 时，当前 Action 为异步
2. 返回一个 builder 或什么都不返回时，当前 Action 为同步

下面是一个简单的例子： 一个列表请求的行为，此时要显示 loading，在请求返回时更新应用状态中的列表项，同时隐藏 loading。

import {builder} from 'san-update';

store.addAction('fetchList', function (page, {getState, dispatch}) {
    dispatch('showLoading');
    dispatch('updateCurrentPage', page);

    return requestList(page).then(list => {
        if (getState('currentPage') === page) {
            dispatch('updateList', list);
            dispatch('hideLoading');
        }
    });
});

store.addAction('showLoading', function () {
    return builder().set('loading', true);
});

store.addAction('hideLoading', function () {
    return builder().set('loading', false);
});

store.addAction('updateCurrentPage', function (page) {
    return builder().set('currentPage', page);
});

store.addAction('updateList', function (list) {
    return builder().set('list', list);
});


// 这里模拟一下，意思意思
function requestList(page) {
    return new Promise(resolve => {
        setTimeout(() => {
            let pageList = [1, 2, 3];
            resolve(pageList);
        }, 500);
    });
}

例子中有下面几个要点：

1. 异步 Action 可以多次 dispatch 其他的 Action，通过第二个参数对象中的 dispatch 方法。这个方法和 getState 一样，也是 this 无关的。
2. fetchList 中马上 updateCurrentPage，在请求返回时使用 getState 方法对 currentPage 判断，能够避免用户快速多次点击页码时发起多个 list 请求，请求返回的顺序不同可能导致问题。
3. 异步 Action 没有更新应用状态的能力，想要更新应用状态必须 dispatch 同步 Action。下面的代码说明了为什么，感兴趣可以看看。

store.addAction('fetchList', function (page, {getState, dispatch}) {
    dispatch('showLoading');
    dispatch('updateCurrentPage', page);

    return requestList(page).then(list => {
        if (getState('currentPage') === page) {
            dispatch('hideLoading');
            
            // 如果异步 Action 支持在 promise 中返回 builder 并更新状态
            // 这里的代码就可能导致问题。因为 promise.then 不是马上运行的
            // 这里的 currentPage 不代表 builder 运行时的 currentPage
            // currentPage 可能被另外一个 dispatch fetchList 改掉
            // 所以这里应该 dispatch 一个同步的 Action 让应用状态即时完成变更
            dispatch('updateList', list);  // good
            // return builder().set('list', list); // warning
        }
    });
});

异步 Action 在 dispatch 时将返回 Promise 对象，以便于 Action 完成后的逻辑控制。

store.addAction('addArticle', function (article) {
    return axios.post(url, article);
});


store.dispatch('addArticle', {}).then(() => {
    // redirect to view page
});

组件的connect

connect到默认store

connect 方法支持对 默认store实例 和 San 组件进行连接，步骤和 redux 类似：

1. 通过 connect 方法创建一个 connect 组件的函数
2. 调用这个函数对组件进行 connect

import {store, connect} from 'san-store';

const connector = connect(
    {name: 'user.name'},
    {change: 'changeUserName'}
);
const UserNameEditor = san.defineComponent({/*...*/});
const NewUserNameEditor = connector(UserNameEditor);

通常，我们只需要对当前声明的组件进行 connect。此时可以合并成一句

const UserNameEditor = san.defineComponent({/*...*/});
const NewUserNameEditor = connect(
    {name: 'user.name'},
    {change: 'changeUserName'}
)(UserNameEditor);

connect到自己创建的store

当实际业务中需要多个 Store 实例时，可以自行创建 Store 实例。connect 方法支持连接到指定的 Store 实例。

import {Store, connect} from 'san-store';

// 自行创建 store 实例
const myStore = new Store({
    initData: {
        name:'erik'
    },
    actions:{
        changeUserName(name) {
            return builder().set('user.name', name);
        }
    }
});

const UserNameEditor = san.defineComponent({/*...*/});

// connect 时提供自创建的 storeA 
const NewUserNameEditor = connect(
    myStore,
    {name: 'user.name'},
    {change: 'changeUserName'}
)(UserNameEditor);

映射store状态与组件data

mapStates 参数指定了要把哪些状态注入到组件，key 是要注入到组件的数据项名称，value 是 store 中状态项的名称。

import {store, connect} from 'san-store';

const NewUserNameEditor = connect(
    {name: 'user.name'}
)(san.defineComponent({
    // connect 后，name 数据项由 store 提供
    template: '<div title="{{name}}">......</div>'
}));

组件上可直接调用的 dispatch action 方法

使用 store 时，我们可以通过调用 store.dispatch(actionName, payload) 方法更新应用状态。但如果在组件中也这么做，就会有些问题：

• 由于 actionName 的应用全局唯一性，名字需要比较完整，对于组件来说这么长的名称会显得比较冗余
• 组件实现时，得关心对具体 store 的依赖

通过指定 mapActions 可以在组件的 actions 成员上生成 dispatch action 的快捷方法，让组件可以更便捷的 dispatch action。mapActions 的 key 是要映射到组件 actions 成员上的方法名，value 是 action 的名称。

import {store, connect} from 'san-store';

const UserNameEditor = connect(
    {name: 'user.name'},
    {change: 'changeUserName'}
)(san.defineComponent({
    submit() {
        // 通过 mapActions，可以把 dispatch action 简化成组件自身的方法调用
        // store.dispatch('changeUserName', this.data.get('name'));
        this.actions.change(this.data.get('name'));
    }
}));

connect 多个 store

当实际业务中真的需要多个 Store 实例时，可以通过 connect 自行创建 connector，连接 Store 实例和 San 组件。步骤如下：

1. 创建 Store 实例
2. 通过 connect().connect() 方式，即 connect 的链式调用实现 连接多个 store

import {Store, connect} from 'san-store';

// 创建模块A中的store实例
const storeA = new Store({
    initData: {
        name:'erik'
    },
    actions:{
        changeUserName(name) {
            return builder().set('user.name', name);
        }
    }
});

const storeB = new Store({
    initData: {
        todos: []
    },
    actions:{
        changeTodos(payload) {
            return builder().set('todos', payload);
        }
    }
});

const Container = san.defineComponent({/*...*/});

// 调用手动创建的connectA方法进行storeA和组件连接
const NewContainer = connect(
    storeA,
    {name: 'user.name'},
    {change: 'changeUserName'}
).connect(
    storeB,
    {todos: 'todos'},
    ['changeTodos']
)(Container);

componsition api

use api 提供了对 san-composition 形式组件的 store 支持：

1. 使用 useState 定义数据。
2. 使用 useAction 定义方法。

import san from 'san';
import {defineComponent, template, method} from 'san-composition';
import {useState} from 'san-store/use';
import {Store} from 'san-store';

// 创建模块A中的store实例
const myStore = new Store({
    initData: {
        name:'erik'
    },
    actions:{
        changeUserName(name) {
            return builder().set('user.name', name);
        }
    }
});

export default defineComponent(context => {
    template(`
        <div>{{name}}
            <input value="{=newName=}"><button on-click="change">change</button>
        </div>
    `);

    const name = useState(myStore, 'user.name', 'name');
    const newName = data('newName', '');
    let changeUserName = useAction(myStore, 'changeUserName');

    method({
        change: () => {
            changeUserName(newName.get());
        }
    });

}, san);