Question

使用React Higher-Order Component记录JSDoc的正确方法是什么？当然，还没有内置任何特定于React的标签 - 那么什么是正确的方法呢？

Answer 1

要使用JSDoc记录高阶组件，您将遵循下面列出的标准。为了明确起见，通常会在定义高阶组件的地方找到文档，而不一定在使用它的地方找到。如果要记录使用位置，可以将其作为@description，@see，@link或其他相关标记记录在该组件的JSDocs中。

  import React, { useState } from 'react';
  import Async from 'react-async';
  import { withTheme } from 'design'; // Contains the JSDoc for this HOC.
  import { getName } from 'api';

  /**
    * Component to render a greeting to someone!
    * 
    * @component
    * @param {string} userId The ID of the user to greet
    */
  export function Hello({ theme, userId }) {
    return (
      <Async promiseFn={getName} userId={userId}>
        <Async.Fulfilled>
          {(data) => <p>Hello {data.name}!</p>}
        </Async.Fulfilled>
      </Async>
    );
  };

  export default withTheme(Hello);

带有React的文档以及通常的代码总是很有趣。有几种方法，以及每种方法的优点和缺点。问自己，它将用于什么用途？创建文档网站，在队友之间，仅在开发人员之间共享？话虽这么说，纯文档最常见的方式是JSDoc和Markdown。

降价（例如Material UI）
MarkdownX（MDX

还有其他可视化具有内置文档功能的组件的方法，这些功能通常也基于Markdown或JSDoc。在团队内部工作或发布软件包时，这将变得非常有用。

位（Bit Documentation）
故事书（Storybook for MD）
React StyleGuidist（StyleGuidist Docs）

Answer 2

在React中构建UI时，HOC模式是一个非常重要的代码重用工具。道具类型有助于在bug产生之前捕获它们。

但是，编写能够正确处理所包装组件的prop类型的HOC十分困难，并且需要大量样板代码。理想情况下，工程师不应回避将逻辑转移到HOC，因为编写它太冗长了。

为解决此问题，react-create-hoc提供了一个实现大部分样板函数的函数。它只允许使用简单的函数创建HOC，该函数将一个组件包装到一个新组件中。

用法

import React from 'react';
import PropTypes from 'prop-types';
import createHOC from 'react-create-hoc';

function WelcomeMessage({ name }) {
  return <div>{greeting}, {name}!</div>;
}

WelcomeMessage.propTypes = {
  greeting: PropTypes.string.isRequired,
  name: PropTypes.string.isRequired,
};

const withModifiedName = createHOC(
  'withModifiedName',
  (ComponentToWrap, nameModifier) => {
    function WithModifiedName({ nameProvider, ...rest }) {
      return (
        <ComponentToWrap
          name={nameModifier(nameProvider())}
          {...rest}
        />
      );
    }

    WithModifiedName.propTypes = {
      nameProvider: PropTypes.func.isRequired,
    };

    return WithModifiedName;
  },
  {
    factory: true,
    passedProps: ['name'],
  },
);

// WrappedWelcomeMessage has the following prop types:
// {
//   greeting: PropTypes.string.isRequired,
//   nameProvider: PropTypes.func.isRequired,
// }
const WrappedWelcomeMessage = withModifiedName(
  // nameModifier param
  name => name.toUpperCase(),
)(WelcomeMessage);

// Renders a div containing, "Rise and shine, MR. FREEMAN!"
ReactDOM.render(
  <WrappedWelcomeMessage
    greeting="Rise and shine"
    nameProvider={() => 'Mr. Freeman'}
  />,
  document.getElementById('root'),
);

反应HOC的JSDoc标记支持（高阶组件）

2 个答案: