插件

插件是一个函数，它返回一个对象——更具体地说，该对象可以包含增强和修改 Swagger UI 功能的函数和组件。

注意：语义版本控制

Swagger UI 的内部 API 不属于我们的公共契约，这意味着它们可以在不更改主要版本的情况下进行更改。

如果您的自定义插件包装、扩展、覆盖或使用任何内部核心 API，我们建议在您的应用程序中指定 Swagger UI 的特定次要版本，因为它们在补丁版本之间不会改变。

例如，如果您通过 NPM 安装 Swagger UI，您可以使用波浪号来做到这一点

{
  "dependencies": {
    "swagger-ui": "~3.11.0"
  }
}

格式

插件返回值可以包含以下任何键，其中 stateKey 是状态片段的名称

{
  statePlugins: {
    [stateKey]: {
      actions,
      reducers,
      selectors,
      wrapActions,
      wrapSelectors
    }
  },
  components: {},
  wrapComponents: {},
  rootInjects: {},
  afterLoad: (system) => {},
  fn: {},
}

系统提供给插件

假设我们有一个插件 NormalPlugin，它在 normal 状态命名空间下暴露了一个 doStuff 动作。

const ExtendingPlugin = function(system) {
  return {
    statePlugins: {
      extending: {
        actions: {
          doExtendedThings: function(...args) {
            // you can do other things in here if you want
            return system.normalActions.doStuff(...args)
          }
        }
      }
    }
  }
}

正如您所看到的，每个插件都传递了对正在构建的 system 的引用。只要 NormalPlugin 在 ExtendingPlugin 之前编译，这将没有任何问题地工作。

插件系统中没有内置的依赖管理，因此如果您创建了一个依赖于另一个插件的插件，您有责任确保依赖插件在被依赖插件之后加载。

接口

动作

const MyActionPlugin = () => {
  return {
    statePlugins: {
      example: {
        actions: {
          updateFavoriteColor: (str) => {
            return {
              type: "EXAMPLE_SET_FAV_COLOR",
              payload: str
            }
          }
        }
      }
    }
  }
}

一旦定义了动作，您就可以在任何可以获取系统引用的地方使用它

// elsewhere
system.exampleActions.updateFavoriteColor("blue")

Action 接口允许在 Swagger UI 系统中某个状态片段内创建新的 Redux action creators。

此 action creator 函数将作为 exampleActions.updateFavoriteColor 暴露给容器组件。当此 action creator 被调用时，返回值（应为 Flux Standard Action）将传递给 example reducer，我们将在下一节中定义它。

有关 Redux 中动作概念的更多信息，请参阅 Redux 动作文档。

Reducers

Reducers 接收一个状态（这是一个 Immutable.js map）和一个动作，然后返回一个新状态。

Reducers 必须以它们处理的动作类型的名称提供给系统，在本例中是 EXAMPLE_SET_FAV_COLOR。

const MyReducerPlugin = function(system) {
  return {
    statePlugins: {
      example: {
        reducers: {
          "EXAMPLE_SET_FAV_COLOR": (state, action) => {
            // you're only working with the state under the namespace, in this case "example".
            // So you can do what you want, without worrying about /other/ namespaces
            return state.set("favColor", action.payload)
          }
        }
      }
    }
  }
}

选择器

选择器进入其命名空间的状态，从状态中检索或派生数据。

它们是保持逻辑在一个地方的简单方法，并且比直接将状态数据传递给组件更受青睐。

const MySelectorPlugin = function(system) {
  return {
    statePlugins: {
      example: {
        selectors: {
          myFavoriteColor: (state) => state.get("favColor")
        }
      }
    }
  }
}

您还可以使用 Reselect 库来记忆（memoize）您的选择器，这对于任何将大量使用的选择器都推荐这样做，因为 Reselect 会自动为您记忆选择器调用

import { createSelector } from "reselect"

const MySelectorPlugin = function(system) {
  return {
    statePlugins: {
      example: {
        selectors: {
          // this selector will be memoized after it is run once for a
          // value of `state`
          myFavoriteColor: createSelector((state) => state.get("favColor"))
        }
      }
    }
  }
}

一旦定义了选择器，您就可以在任何可以获取系统引用的地方使用它

system.exampleSelectors.myFavoriteColor() // gets `favColor` in state for you

组件

您可以提供一个组件映射以集成到系统中。

请注意您提供的组件的键名，因为您需要在其他地方使用这些名称来引用组件。

class HelloWorldClass extends React.Component {
  render() {
    return <h1>Hello World!</h1>
  }
}

const MyComponentPlugin = function(system) {
  return {
    components: {
      HelloWorldClass: HelloWorldClass
      // components can just be functions, these are called "stateless components"
      HelloWorldStateless: () => <h1>Hello World!</h1>,
    }
  }
}

// elsewhere
const HelloWorldStateless = system.getComponent("HelloWorldStateless")
const HelloWorldClass = system.getComponent("HelloWorldClass")

您还可以通过创建一个始终返回 null 的无状态组件来“抵消”任何您不想要的组件

const NeverShowInfoPlugin = function(system) {
  return {
    components: {
      info: () => null
    }
  }
}

如果当系统中不存在组件时您不希望出现警告，可以使用 config.failSilently。

请注意 getComponent 参数的顺序。在下面的示例中，布尔值 false 指的是是否存在容器，第三个参数是用于抑制缺少组件警告的配置对象。

const thisVariableWillBeNull = getComponent("not_real", false, { failSilently: true })

Wrap-Actions

Wrap Actions 允许您覆盖系统中某个动作的行为。

它们是具有签名 (oriAction, system) => (...args) => result 的函数工厂。

Wrap Action 的第一个参数是 oriAction，它正在被包装的动作。您有责任调用 oriAction - 如果不调用，原始动作将不会触发！

此机制对于有条件地覆盖内置行为或监听动作非常有用。

// FYI: in an actual Swagger UI, `updateSpec` is already defined in the core code
// it's just here for clarity on what's behind the scenes
const MySpecPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        actions: {
          updateSpec: (str) => {
            return {
              type: "SPEC_UPDATE_SPEC",
              payload: str
            }
          }
        }
      }
    }
  }
}

// this plugin allows you to watch changes to the spec that is in memory
const MyWrapActionPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        wrapActions: {
          updateSpec: (oriAction, system) => (str) => {
            // here, you can hand the value to some function that exists outside of Swagger UI
            console.log("Here is my API definition", str)
            return oriAction(str) // don't forget! otherwise, Swagger UI won't update
          }
        }
      }
    }
  }
}

Wrap-Selectors

Wrap Selectors 允许您覆盖系统中某个选择器的行为。

它们是具有签名 (oriSelector, system) => (state, ...args) => result 的函数工厂。

此接口对于控制流入组件的数据非常有用。我们在核心代码中使用它来根据 API 定义的版本禁用选择器。

import { createSelector } from 'reselect'

// FYI: in an actual Swagger UI, the `url` spec selector is already defined
// it's just here for clarity on what's behind the scenes
const MySpecPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        selectors: {
          url: createSelector(
            state => state.get("url")
          )
        }
      }
    }
  }
}

const MyWrapSelectorsPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        wrapSelectors: {
          url: (oriSelector, system) => (state, ...args) => {
            console.log('someone asked for the spec url!!! it is', state.get('url'))
            // you can return other values here...
            // but let's just enable the default behavior
            return oriSelector(state, ...args)
          }
        }
      }
    }
  }
}

Wrap-Components

Wrap Components 允许您覆盖系统中注册的组件。

Wrap Components 是具有签名 (OriginalComponent, system) => props => ReactElement 的函数工厂。如果您更愿意提供一个 React 组件类，(OriginalComponent, system) => ReactClass 也同样有效。

const MyWrapBuiltinComponentPlugin = function(system) {
  return {
    wrapComponents: {
      info: (Original, system) => (props) => {
        return <div>
          <h3>Hello world! I am above the Info component.</h3>
          <Original {...props} />
        </div>
      }
    }
  }
}

这是另一个示例，其中包含将被包装的组件的代码示例

/////  Overriding a component from a plugin

// Here's our normal, unmodified component.
const MyNumberDisplayPlugin = function(system) {
  return {
    components: {
      NumberDisplay: ({ number }) => <span>{number}</span>
    }
  }
}

// Here's a component wrapper defined as a function.
const MyWrapComponentPlugin = function(system) {
  return {
    wrapComponents: {
      NumberDisplay: (Original, system) => (props) => {
        if(props.number > 10) {
          return <div>
            <h3>Warning! Big number ahead.</h3>
            <Original {...props} />
          </div>
        } else {
          return <Original {...props} />
        }
      }
    }
  }
}

// Alternatively, here's the same component wrapper defined as a class.
const MyWrapComponentPlugin = function(system) {
  return {
    wrapComponents: {
      NumberDisplay: (Original, system) => class WrappedNumberDisplay extends React.component {
        render() {
          if(props.number > 10) {
            return <div>
              <h3>Warning! Big number ahead.</h3>
              <Original {...props} />
            </div>
          } else {
            return <Original {...props} />
          }
        }
      }
    }
  }
}

rootInjects

rootInjects 接口允许您在系统的顶层注入值。

此接口接受一个对象，该对象将在运行时与顶层系统对象合并。

const MyRootInjectsPlugin = function(system) {
  return {
    rootInjects: {
      myConstant: 123,
      myMethod: (...params) => console.log(...params)
    }
  }
}

afterLoad

afterLoad 插件方法允许您在插件注册后获取系统引用。

此接口在核心代码中用于附加由绑定选择器或动作驱动的方法。您还可以使用它来执行需要您的插件已经准备就绪的逻辑，例如从远程端点获取初始数据并将其传递给您的插件创建的动作。

插件上下文，它绑定到 this，是未文档化的，但下面是一个如何将绑定动作作为顶级方法附加的示例

const MyMethodProvidingPlugin = function() {
  return {
    afterLoad(system) {
      // at this point in time, your actions have been bound into the system
      // so you can do things with them
      this.rootInjects = this.rootInjects || {}
      this.rootInjects.myMethod = system.exampleActions.updateFavoriteColor
    },
    statePlugins: {
      example: {
        actions: {
          updateFavoriteColor: (str) => {
            return {
              type: "EXAMPLE_SET_FAV_COLOR",
              payload: str
            }
          }
        }
      }
    }
  }
}

fn

fn 接口允许您向系统添加辅助函数，以便在其他地方使用。

import leftPad from "left-pad"

const MyFnPlugin = function(system) {
  return {
    fn: {
      leftPad: leftPad
    }
  }
}