ReactJS 编写无状态函数注释

IT技术 javascript reactjs code-documentation
2021-05-25 22:37:16

为 ReactJS 无状态函数编写注释的推荐方式是什么？

假设我有以下代码：

export const LoginForm = ({ submitting, handleSubmit }) => (
  <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
));

文档注释应该是什么样的？

我的第一个想法是：

/**
 * Form for user login
 * @param {bool} submitting Shows if form submitting is in progress
 * @param {function} handleSubmit Form submit callback function
 */

但是，这并不为正确submitting而handleSubmit不是真正的PARAMSLoginForm功能。它们只是props参数的键。另一方面，props作为参数的文档LoginForm似乎毫无意义，因为每个react组件都有props一个参数，而 props 键是函数中最重要的部分。

有没有官方的指导方针？（我没有找到）

编辑

我还PropTypes定义了：

LoginForm.propTypes = {
  submitting: PropTypes.bool,
  handleSubmit: PropTypes.func.isRequired,
};

也许这是props相关文档的地方？如果是这样，它应该是什么样子？有什么标准吗？

4个回答

您可以props在属性名称之前指定对象：

/**
 * Form for user login
 * @param {object} props Component props
 * @param {bool} props.submitting Shows if form submitting is in progress
 * @param {function} props.handleSubmit Form submit callback function
 */
export const LoginForm = ({ submitting, handleSubmit }) => (
  <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
));

有关更多信息，请参阅部分中的@param wiki 页面Parameters With Properties。

我知道我参加这个聚会几乎晚了 3 年。仅供参考。可以这样做：

/**
 * @typedef {Object<string, any>} Props
 * @property {boolean} submitting Shows if form submitting is in progress
 * @property {function} handleSubmit Form submit callback function
 */

/** 
 * Form for user login
 *
 * @type {import('react').FunctionComponentElement<Props>}
 */
export const LoginForm = ({ submitting, handleSubmit }) => (
    <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
);

为简洁起见，您还可以这样做：

/**
 * Form for user login
 *
 * @type {import('react').FunctionComponentElement<{
       submitting: boolean,
       handleSubmit: function
    }>}
 */
export const LoginForm = ({ submitting, handleSubmit }) => (
    <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
);

如果在您的 IDE 中启用了 Typescript，您可以避免在此设置中完全声明 prop-types。

另一种选择是jsdoc-react-proptypes，像这样使用：

SomeComponent.propTypes = {
  /** Function to run after animation completes. */
  onStop: PropTypes.func
};

这会为该类创建一个“属性”文档部分，其中包含您所期望的内容，大致如下：

Name    Type Attributes  Description
onStop       <optional>  Function to run after animation completes.

我不知道为什么Type没有出现；这是一个非常简陋的图书馆，但我有同样的问题，发现了这个，并且必须努力清理它。

我认为你可以使用这个：

 * @property {function(argType1, argType2, argTypeN): void} handleSubmit - The handleSubmit Form submit callback function

并且返回类型中的 void 可以替换为任何数据类型，例如数字或字符串。

其它你可能感兴趣的问题
上一篇为什么 reactjs 中的功能组件没有实例？ 下一篇德国RepRep Neo无法加热挤出机