redux-saga
— это библиотека, которая призвана упростить и улучшить побочные эффекты (т.е. такие действия, как асинхронные операции, например, загрузки данных, и "грязные" действия, такие, как доступ к браузерному кешу), сделать лёгкими в тестировании и лучше справляться с ошибками.
Можно представить это так, что saga — это как отдельный поток в вашем приложении, который отвечает за побочные эффекты. redux-saga
— это мидлвар redux, что означает, что этот поток может запускаться, останавливаться и отменяться из основного приложения с помощью обычных действий redux, оно имеет доступ к полному состоянию redux приложения и также может диспатчить действия redux.
Библиотека использует концепцию ES6, под названием генераторы, для того, чтобы сделать эти асинхронные потоки легкими для чтения, написания и тестирования. (если вы не знакомы с этим, здесь есть некоторые ссылки для ознакомления) Тем самым, эти асинхронные потоки выглядят, как ваш стандартный синхронный JavaScript-код. (наподобие async
/await
, но генераторы имеют несколько отличных возможностей, необходимых нам)
Возможно, вы уже использовали redux-thunk
, перед тем как обрабатывать ваши выборки данных. В отличие от redux thunk, вы не оказываетесь в аду колбэков, вы можете легко тестировать ваши асинхронные потоки и ваши действия остаются чистыми.
$ npm install --save redux-saga
или
$ yarn add redux-saga
Альтернативно, вы можете использовать предоставленные UMD сборки напрямую в <script>
на HTML странице. Смотрите эту секцию.
Предположим, что у нас есть интерфейс для извлечения некоторых пользовательских данных с удалённого сервера при нажатии кнопки. (Для краткости, мы просто покажем код запуска экшена.)
class UserComponent extends React.Component {
...
onSomeButtonClicked() {
const { userId, dispatch } = this.props
dispatch({type: 'USER_FETCH_REQUESTED', payload: {userId}})
}
...
}
Компонент диспатчит действие в виде простого объекта в хранилище. Мы создадим saga, которая слушает все действия USER_FETCH_REQUESTED
и генерирует вызовы API для извлечения пользовательских данных.
sagas.js
import { call, put, takeEvery, takeLatest } from 'redux-saga/effects'
import Api from '...'
// воркер Saga: будет запускаться на действия типа `USER_FETCH_REQUESTED`
function* fetchUser(action) {
try {
const user = yield call(Api.fetchUser, action.payload.userId);
yield put({type: "USER_FETCH_SUCCEEDED", user: user});
} catch (e) {
yield put({type: "USER_FETCH_FAILED", message: e.message});
}
}
/*
Запускаем `fetchUser` на каждое задиспатченное действие `USER_FETCH_REQUESTED`.
Позволяет одновременно получать данные пользователей.
*/
function* mySaga() {
yield takeEvery("USER_FETCH_REQUESTED", fetchUser);
}
/*
В качестве альтернативы вы можете использовать `takeLatest`.
Не допускает одновременное получение данных пользователей. Если `USER_FETCH_REQUESTED`
диспатчится в то время когда предыдущий запрос все еще находится в ожидании ответа,
то этот ожидающий ответа запрос отменяется и срабатывает только последний.
*/
function* mySaga() {
yield takeLatest("USER_FETCH_REQUESTED", fetchUser);
}
export default mySaga;
Для запуска Saga, мы подключим ее к Redux Store, используя мидлвар redux-saga
.
main.js
import { createStore, applyMiddleware } from 'redux'
import createSagaMiddleware from 'redux-saga'
import reducer from './reducers'
import mySaga from './sagas'
// создаем мидлвар saga
const sagaMiddleware = createSagaMiddleware()
// монтируем его в хранилище
const store = createStore(
reducer,
applyMiddleware(sagaMiddleware)
)
// затем запускаем saga
sagaMiddleware.run(mySaga)
// отрисовываем приложение
- Введение
- Базовые концепции
- Продвинутое использование
- Рецепты
- Сторонние ресурсы
- Устранение проблем
- Глоссарий
- Справочник по API
Также существует сборка umd redux-saga
, доступная в каталоге dist/
. При использовании umd-сборки, redux-saga
доступна как ReduxSaga
в объекте window
.
версия umd полезна, если вы не используете Webpack или Browserify. Вы можете получить доступ к ней, непосредственно из unpkg.
Доступны следующие сборки:
Важно! Если ваш целевой браузер не поддерживает генераторы ES2015, вам нужно транспилировать код (например, через babel plugin) и предоставить корректный runtime, такой, например, как этот. Runtime нужно импортировать до redux-saga:
import 'regenerator-runtime/runtime'
// затем
import sagaMiddleware from 'redux-saga'
$ git clone https://github.com/redux-saga/redux-saga.git
$ cd redux-saga
$ npm install
$ npm test
Ниже приведены примеры, портированные (пока) из репозиториев Redux.
Есть три примера счётчика.
counter-vanilla
Демо, использующее обычный JavaScript и UMD-сборки. Все исходники находятся в index.html
.
Для запуска примера, просто откройте index.html
в браузере.
Важно: ваш браузер должен поддерживать генераторы. Подойдут последние версии Chrome/Firefox/Edge.
counter
Демо, использующее webpack
и высокоуровневое API takeEvery
.
$ npm run counter
# тестовый образец для генератора
$ npm run test-counter
cancellable-counter
Демо, использующее низкоуровневое API для демонстрации отмены задачи.
$ npm run cancellable-counter
$ npm run shop
# тестовый образец для генератора
$ npm run test-shop
$ npm run async
# тестовый образец для генераторов
$ npm run test-async
$ npm run real-world
# извините, тестов пока нет
Redux-Saga с TypeScript требует DOM.Iterable
или ES2015.Iterable
. Если ваш target
это ES6
, у вас, скорее всего, уже всё настроено, однако для ES5
вам потребуется самостоятельно добавить его. Посмотрите файл tsconfig.json
и официальную документацию с опциями компилятора.
Вы можете найти официальный логотип Redux-Saga с различными вариантами в каталоге logo.
Поддержите нас ежемесячными пожертвованиями и помогите нам продолжать нашу деятельность. [Стать меценатом]
Стань спонсором и получи свой логотип в нашем README на GitHub с ссылкой на ваш сайт. [Стать спонсором]