API参考

构造函数

VuexSugar

函数签名: constructor(options:Object):VuexSugar

用法:

const VuexSugar = VuexSugar({ baseURL: '' });

// 等效
const VuexSugar = new VuexSugar({ baseURL: '' });

VuexSugar方法内部会隐式的使用new创建一个对象。可以传入一个实例选项对象。

VuexSugar 实例选项

实例选项对象在初始化VuexSugar实例时传入。

axios

类型: axios (instance)
默认值: axios (instance)

用法:

import Axios from 'axios'
import VuexSugar from 'vuex-sugar';

const service = Axios.create({
    withCredentials: true,
    headers: { 'X-Requested-With': 'XMLHttpRequest' }
});

VuexSugar({
    axios: service
})

axios可以是任何有效的axios实例。可以自定义axios实例，或者其他能够返回 Promise 的 Http 请求工具。默认使用axios。

baseUrl

类型: string
用法:
```
VuexSugar({
    baseURL: '/v1/client'
})
```
baseURL将传入axios实例。除了实例选项可以设置baseURL，action 选项的requestConfig参数也可以指定请求的baseURL。

如果这两个地方都没有设置，将使用axios默认的baseURL。优先权：request config base URL > baseURL > axios instance base URL

namespaced

类型: boolean
默认值: false
用法:
```
VuexSugar({
    namespaced: true
})
```
指定该实例下的store是否具有命名空间，与 Vuex namespaced意义相同。

validateResponse

类型: function
函数签名: validateResponse(res: Response): boolean

默认值:

function validateResponse(res) {
    if (!res) return false;
    const { status, data } = res;
    const isServerOk = !data || (data.code ? parseInt(data.code, 10) === 200 : true);
    return status === 200 && isServerOk;
}

详细: vuex-sugar假定服务端 REST API 返回的结果形式如下：
```
{
    code: number,
    data: any,
    msg: string
}
```
其中code与 HTTP status意义相同，data为实际返回的结果，msg为额外的信息。REST 采用此设计，主要在于服务端能够返回更多信息给前端，方便前端灵活处理。如果你的项目中，采用其他的结构，可以重写validateResponse以便决定请求成功或者失败。

用法:

function validateResponse(res) {
    if (!res) return false;
    const { status } = res;
    return status >= 200 && status < 300 ;
}

VuexSugar({
    validateResponse
})

vuex-sugar将使用新的方法来判断请求结果。

resolved

类型: String|Object|Function|Array

用法:

const posts = VuexSugar({
    baseURL: '/v1/client',
    state: { posts: [] },
    // 该实例每个action均会在请求成功时执行全局的message action。root参数表示该action为全局action。
    resolved: { action: 'message', root: true }
});

设置实例的resolved，用于设置请求成功的回调，被该实例的所有action共享，最终会被合并到action中。

String 类型：表示回调执行一个action。该action只能是本实例store的action。如果需要向全局提交action，或者为action传递参数，则使用对象形式。
Object 类型：用于回调执行action。格式同action 提交参数:

{
    // 只有action属性是必须的
    action: String, // action name
    [root]: boolean, // global dispatch
    // 可以添加其他任何action提交参数
    [data]: Object, // http data
    [params]: Object,// http params
    [... other action dispatch options]
    // 也可以添加除action提交参数以外的数据
    [.. other payload]
}

Function 类型：回调执行函数。函数参数为(Response, rest)。response为请求返回结果，rest为action提交时除提交参数以外的数据。

this.updatePost({
    data : {
        ...
    },
    data1, // data1不属于action提交参数，将会被原样传送给回调函数
    data2,
    ...,
    resolved: (res, { data1, data2, ... }) => {} // 剩余数据将会被传递给回调函数
})

Array 类型：可包含以上任一类型，甚至嵌套的数组。

rejected

类型: String|Object|Function|Array
用法:

与resolved相同，用于设置请求失败的回调。

state

类型: Object|Function
默认值: {}
用法:
```
const posts = VuexSugar({
    baseURL: '/v1/client',
    state: { posts: [] }
});
```
设置 store 的默认state，state应该与action中的property对应。如果没有指定默认的state，则默认为null。

如果state为函数形式，则在实例初始化时被执行。函数应该返回一个纯对象。
```
const posts = VuexSugar({
    baseURL: '/v1/client',
    state: () => {
        return { posts: [] };
    } // 返回纯对象
});
```
注意：该函数并不是最终生成的state，如果需要最终生成的state为函数，请在store选项中指定。

当请求成功时，将自动更新property对应的state。

VuexSugar 实例方法

调用实例方法添加action，并生成store。

add

函数签名: (options: Object): VuexSugar
用法:
```
add({
    action: 'listPosts',
    property: 'posts',
    path: '/posts',
    method: 'get'
});
```
在VuexSugar实例上添加一个action，返回该实例。添加action并不是真正的Vuex action，这里只是添加了Vuex action的定义。可以通过选项对象设置action。

选项对象中action为必须字段。更多选项，请参考action 选项。

get

函数签名: (options: Object): VuexSugar

用法:

get({
    action: 'listPosts',
    property: 'posts',
    path: '/posts'
});
// 等同于
add({
    action: 'listPosts',
    property: 'posts',
    path: '/posts',
    method: 'get'
});

add方法的别名，get请求的快捷方法。

delete

函数签名: (options: Object): VuexSugar
用法:

add方法的别名，delete请求的快捷方法。

head

函数签名: (options: Object): VuexSugar
用法:

add方法的别名，head请求的快捷方法。

options

函数签名: (options: Object): VuexSugar
用法:

add方法的别名，options请求的快捷方法。

post

函数签名: (options: Object): VuexSugar
用法:

add方法的别名，post请求的快捷方法。

put

函数签名: (options: Object): VuexSugar
用法:

add方法的别名，put请求的快捷方法。

patch

函数签名: (options: Object): VuexSugar
用法:

add方法的别名，patch请求的快捷方法。

getStore

函数签名: (options: Object): Store

用法:

VuexSugar().getStore({
    courseState: true, // 自动生成pending与error数据
    createStateFn: true // 返回的state为函数形式
});

可以传入store选项参数，用于生成 Vuex store 对象。

 {
     namespaced: false,
     state: {
         pending: {
             posts: false,
             post: false
         },
         error: {
             posts: null,
             post: null
         },
         posts: [],
         post: null
     },
     mutations: {
         LIST_POSTS: Function,
         LIST_POSTS_SUCCEEDED: Function,
         LIST_POSTS_FAILED: Function,
         GET_POST: Function,
         GET_POST_SUCCEEDED: Function,
         GET_POST_FAILED: Function,
         UPDATE_POST: Function,
         UPDATE_POST_SUCCEEDED: Function,
         UPDATE_POST_FAILED: Function
     },

     actions: {
         listPosts: Function,
         getPost: Function,
         updatePost: Function
     }
 }

action 选项

定义action属性。

action

类型: String

用法:

get({
    action: 'listPosts',
    property: 'posts',
    path: '/posts'
});

指定action的 name，可通过 Vuex store 的dispatch进行提交。

// direct via store
this.$store.dispatch('listPosts', { params: {}, data: {} });

// or with mapActions
this.listPosts({ params: {}, data: {} });

property

类型: String

用法:

get({
    action: 'listPosts',
    property: 'posts',
    path: '/posts'
});

指定action对应的state字段。如果没有指定该字段，则不会自动更改state，即使指定了默认的state。

const posts = VuexSugar({
    baseURL: '/v1/client',
    state: { posts: [] }
})
    .get({
        action: 'getPost', // action name
        property: 'post', // state property name
        path: ({ id }) => `/posts/${id}`
    })
    .get({
        action: 'listPosts',
        // property: 'posts', // 没有指定property
        path: '/posts'
    })
    .post({
        action: 'updatePost',
        property: 'post',
        path: ({ id }) => `/posts/${id}`
    })
    .getStore(); // create store object

// post默认值为null，会自动设置post。
// posts虽然设置了默认值，但是没有对应的property，因此不会自动改变。

当不需要state存储数据，例如某些全局提交，或者普通的action，则可省略property，这很有必要。

path

类型: String|Function
用法:

Api 请求的路径，如果path为相对路径，则会自动使用baseURL作为前缀。

如果path为函数，则可使用meta元数据，path在发起请求前会自动执行。path应该返回字符串路径。

详细使用方法参考在 headers 和 path 中使用参数。

headers

类型: Object|Function
用法:

Api 请求头部，该选项的值将与requestConfig属性中的headers合并。
```
get({
    action: 'getPost', // action name
    property: 'post', // state property name
    headers: { userName: 'test' }
});
```
如果headers为函数，则可使用meta元数据，headers在发起请求前会自动执行。headers应该返回对象数据。

详细使用方法参考在 headers 和 path 中使用参数

method

类型: String
用法:

Http 请求的method字段。允许的值为：['get', 'delete', 'head', 'options', 'post', 'put', 'patch']。

当使用HTTP快捷方法时，不需要指定该字段。

requestConfig

类型: Object
用法:

Axios的请求选项参数。该选项中指定的属性具有最高优先权（params、data除外）。

resolved

类型: String|Object|Funtion|Array
用法:

设置当前action的resolved，用于设置请求成功的回调。将与action 选项的resolved、action 提交参数中的resolved进行合并。

rejected

类型: String|Object|Funtion|Array
用法:

与resolved相同，用于设置请求失败的回调。

successHandler

类型: Function
参数: (state, { data, other })
用法:

用于设置请求成功时，覆盖默认的改变state的行为。见自定义请求处理方法。

第二个参数包含了接口的返回结果。如果在action提交参数中，添加了其他额外数据，也会被合并传入进来。

errorHandler

类型: Function
参数: (state, payload)
用法:

第二个参数为错误信息。

before

类型: Function
参数: (error, data: any, context: { dispatch, commit, state, rootState }) 第三个参数为Vuex action参数

用法:

在 action 执行（发起请求）之前执行钩子函数。注意：普通 action 也会执行 before 钩子函数。

get({
    action: 'getPost', // action name
    property: 'post', // state property name
    headers: { userName: 'test' },
    before: (undefined, undefined, { dispatch }) => dispatch('action name', {})
)

在action执行之前还没有任何数据参数，因此第二个参数始终为空，与node接口保持一致。

after

类型: Function
参数: (error, data: any, context: { dispatch, commit, state, rootState }) 第三个参数为Vuex action的第一个参数

在 action 执行（发起请求）之后执行钩子函数。用法同before一致。

第一个参数为错误对象，第二个参数为请求结果。普通 action 的前两个参数都为空。

store 选项

控制生成的store的结构。

createStateFn

类型: boolean
默认值: false

用法:

设置返回的state是否为函数形式。

VuexSugar().getStore({
    courseState: true, // 自动生成pending与error数据
    createStateFn: true // 返回的state为函数形式
});

返回的 store 为:

{
    namespaced: false,
    state: function(){
        return {
            pending: {
                posts: false,
                post: false
            },
            error: {
                posts: null,
                post: null
            },
            posts: [],
            post: null
        };
    }
    ...
}

默认返回的state不被函数包裹。

courseState

类型: boolean
默认值: true

用法:

设置是否默认生成pending与error等数据。

VuexSugar().getStore({
    courseState: false, // 不自动生成pending与error数据
    createStateFn: true // 返回的state为函数形式
});

返回的 store 为:

{
    namespaced: false,
    state: function(){
        return {
            posts: [],
            post: null
        };
    }
    ...
}

successSuffix

类型: String
默认值: SUCCEEDED
用法:
```
VuexSugar().getStore({
    successSuffix: 'REQUEST_OK'
});
```
设置mutations type的后缀。请求成功时，将与action name一起作为mutation的 type。这在手动触发mutation时，很有用。

errorSuffix

类型: String
默认值: FAILED
用法:

设置mutations type的后缀。请求失败时，将与action name一起作为mutation的 type。同successSuffix。

action 提交参数

dispatch action时可以附带一些提交参数。

类型: { [params: Object], [data: Object], [meta: OBject], [after: Funtion], [before: Funciton], [resolved:String|Object|Function|Array], [rejected:String|Object|Function|Array], [...any] }

用法

this.updatePost({
    resolved: () => (this.btnEnable = true), // 执行成功按钮恢复可点击
    rejected: () => (this.btnEnable = false), // 执行过程中按钮不可点击
    meta: { id: 123 }
});

提交action时，可以指定请求参数，或者传入来自页面的元数据，或者页面组件的回调等内容。

这里可以传入after、before钩子函数，分别在请求发起之前与请求发起之后调用。函数签名为(error, data: any, context: { dispatch, commit, state, rootState })。

其中第一个参数为error对象，第二个在after中是请求的返回结果。注意：这里请求成功或者失败都会被调用，同action选项before与after。

注意after区别于resolved与rejected，虽然他们都能完成绝大部分相同的工作。但是after不管成功或失败都会调用，resolved与rejected只有在确定成功或失败才会分别调用。

添加after、before钩子函数的好处在于，可以在请求开始前后做一些额外的操作，比如：更改页面的状态。

{
    params, // 请求参数对象，将被传入axios
    data, // 提交的数据队形，将被传入axios
    meta, // 提交的元数据，会被action的header或者path函数使用
    after, // action的前置钩子函数
    before, // action的后置钩子函数，注意：普通action也会执行before与after
    resolved, // 请求成功的回调，详细使用方式将`Vuex实例选项`
    rejected, // 请求失败的回调，实际上：普通action也会执行resolved与rejected
    ...other // 提交action时，传递的额外数据。这些数据会传入successHandler，或者传入resolved（rejected）中规定的下一个action
}

全局属性

Vuex-Sugar拥有一些全局属性，他们会被每个Vuex-Sugar实例使用。

全局属性对象VuexSugar.defaults：

{
    baseURL,
    axios,
    namespaced,
    validateResponse,
    meta, // 全局元数据，将与action定义、action提交参数进行合并。{ ...GlobalDefaults.meta, ...ActionOptions.meta, ...ActionPayload.meta }
    resolved, // 全局回调，将与action定义、action提交参数进行合并。[ ...GlobalDefaults.resolved, ...ActionOptions.resolved, ...ActionPayload.resolved ]
    rejected; // 全局回调，将与action定义、action提交参数进行合并。[ ...GlobalDefaults.rejected, ...ActionOptions.rejected, ...ActionPayload.rejected ]
}

可以使用全局方法setGlobal设置全局属性，默认全局属性为空。

全局方法

Vuex-Sugar导出了一些辅助方法，便于使用Store。

creatStore

函数签名: (VuexSugar, options: Object): store

用法

import VuexSugar, { createStore } from 'vuex-sugar';

const store = VuexSugar();
createStore(store, { createStateFn: true });

VuexSugar实例的getStore调用了该方法，根据VuexSugar实例创建一个 Store对象。

mergeStore

函数签名: (store, [store]): store

用法

import VuexSugar, { mergeStore } from 'vuex-sugar';

const store = VuexSugar().getStore();
mergeStore(store, { state: {}, mutations: {}, getters: {}, actions: {} });

允许混入其他自定义的 store。

setGlobal

函数签名: (defaultOptions): VuexSugar

用法

import VuexSugar, { mergeStore, setGlobal } from 'vuex-sugar';

// 设置全局属性
setGlobal({ baseURL, axios });
// or 也可以这样设置
VuexSugar.setGlobal({ baseURL, axios });

允许设置全局属性，每个VuexSugar实例都会拥有这些属性。这里设置的属性会根据其属性类型，与action选项或者action提交参数进行合并，或被覆盖。

# API参考

# 构造函数

# VuexSugar

# VuexSugar 实例选项

# axios

# baseUrl

# namespaced

# validateResponse

# meta

# resolved

# rejected

# state

# VuexSugar 实例方法

# add

# get

# delete

# head

# options

# post

# put

# patch

# getStore

# action 选项

# action

# property

# path

# headers

# method

# requestConfig

# meta

# resolved

# rejected

# successHandler

# errorHandler

# before

# after

# store 选项

# createStateFn

# courseState

# successSuffix

# errorSuffix

# action 提交参数

# 全局属性

# 全局方法

# creatStore

# mergeStore

# setGlobal

API参考

构造函数

VuexSugar

VuexSugar 实例选项

axios

baseUrl

namespaced

validateResponse

meta

resolved

rejected

state

VuexSugar 实例方法

add

get

delete

head

options

post

put

patch

getStore

action 选项

action

property

path

headers

method

requestConfig

meta

resolved

rejected

successHandler

errorHandler

before

after

store 选项

createStateFn

courseState

successSuffix

errorSuffix

action 提交参数

全局属性

全局方法

creatStore

mergeStore

setGlobal