Главная страница

Логотип Redux Saga

redux-saga

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

Переводы

• Chinese
• Traditional Chinese
• Japanese
• Korean
• Portuguese
• Russian

Использование UMD-сборки в браузере

Также существует сборка umd redux-saga, доступная в каталоге dist/. При использовании umd-сборки, redux-saga доступна как ReduxSaga в объекте window.

версия umd полезна, если вы не используете Webpack или Browserify. Вы можете получить доступ к ней, непосредственно из unpkg.

Доступны следующие сборки:

• https://unpkg.com/redux-saga/dist/redux-saga.js
• https://unpkg.com/redux-saga/dist/redux-saga.min.js

Важно! Если ваш целевой браузер не поддерживает генераторы 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

пример с async

$ npm run async

# тестовый образец для генераторов
$ npm run test-async

реальный пример (с горячей перезагрузкой webpack)

$ npm run real-world

# извините, тестов пока нет

TypeScript

Redux-Saga с TypeScript требует DOM.Iterable или ES2015.Iterable. Если ваш target это ES6, у вас, скорее всего, уже всё настроено, однако для ES5 вам потребуется самостоятельно добавить его. Посмотрите файл tsconfig.json и официальную документацию с опциями компилятора.

Логотип

Вы можете найти официальный логотип Redux-Saga с различными вариантами в каталоге logo.

Меценат

Поддержите нас ежемесячными пожертвованиями и помогите нам продолжать нашу деятельность. [Стать меценатом]

Спонсоры

Стань спонсором и получи свой логотип в нашем README на GitHub с ссылкой на ваш сайт. [Стать спонсором]