第1895期 React组件开发的十条最佳实践

Posted 2021-07-30 前端早读课

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了第1895期 React组件开发的十条最佳实践相关的知识，希望对你有一定的参考价值。

前言

今日早读文章由南京华为慧通@潘绳杰翻译投稿分享。

@潘绳杰，南京华为慧通，热爱前端和工程化

正文从这开始～～

创建被许多人使用的组件是困难的。尤其当组件的属性作为公开API的一部分，你不得不仔细考虑哪些属性应该接受。

这篇文章会快速介绍一些在API设计时的通用最佳实践，并且给出10条明确的最佳实践指导你创建让同事开发者喜欢使用的组件。

API是什么?

API或者应用程序接口(Application Programming Interface)，主要是指两部分代码相遇的地方。这是你的代码和其他世界接触的地方。我们称这个接触表面为接口。这些是可交互的动作集合或者数据点。

介于前端和后端之间的接口就是一个API。你可以通过这个API访问一系列特定的数据和功能。

介于一个类和调用代码之间接口也是一个API。你可以在类上调用方法，来获取数据或者触发封装在其中的功能。

沿着这个思路，你的组件接受的属性也是其API。这是你的用户和组件交互的方式，因此当你决定暴露哪些属性时有很多类似的规则和考虑可以应用。

API设计的部分最佳实践

那么在设计一个API时有哪些规则和考虑可以应用？在这方面我们做了一些调查，并找到了许多极好的资源。我们挑选了两篇文章，Josh Tauberer的“What Makes a Good API?”和Ron Kurir的同名文章，从中提取了4条最佳实践来遵循。

稳定的版本管理

当你在创建一个API时要考虑的最重要的一点是尽可能保持稳定。这意味着破坏性变更的次数很少。如果你有破坏性的变更，确保写一份详细的升级指南，并且如果可能，提供一个重构件(code-mod)来给用户自动化处理这些变更。

如果你发布了API，确保遵守语义化版本。这让用户更容易决定使用什么版本。

描述性的错误信息

任何调用API出错的时候，你都应该尽可能的解释什么地方出错，并告知如何修复。返回一个错误使用且没有任何其他提示的响应会让使用者感到羞愧，这不是一种好的用户体验。

相反，提供描述性的错误来帮助用户修复他们调用API的方式。

少让开发者感到惊讶

开发者是脆弱的人类，因此当他们使用API时不应该让他们感到惊讶。换句话说，尽可能让API更直观。这可以通过遵守最佳实践和命名规范来达到。

另外需要放在心上是保持你的代码一致性。如果你在一处地方给布尔型属性名称前面添加了is或has，而在另外一处忽略了，这会让其他人感到困惑。

最小化API接口

当我们谈到最小化的时候-同样要最小化你的API。更多的特性当然是好的，但是API接口暴露得越少，使用者学习的成本也更低。从而让用户认为这是一个易用的API。

有很多方式可以控制API的规模，其中一个就是从旧的中重构一个新的来。

组件开发的十条最佳实践

这4条黄金法则在REST API和Pascal语言程序中使用得很好，那么如何将他们拿到React的现代世界中来呢？

像我们前面提到的，组件也有自己的API。我们称做props，这是给组件传递数据、回调和其他功能的方式。我们如何组织props对象才能不破坏上面的规则？我们如何开发组件才能让其他开发者在使用组件时更便捷？

我们创建了开发组件时的10条不错的规则清单，希望对你有帮助。

1. 组件使用文档

如果组件没有提供如何使用的文档，那么显然组件是无用的。好吧，大多时候，使用者总是可以通过查看实现来了解如何使用，但那很少是最好的用户体验。

有很多方式可以给组件编写文档，从我们的角度想推荐3个选项:

Storybook
Styleguidist
Docz

前两个在你开发组件时可以提供一个playground用来试验，第3个提供了MDX来更自由的书写文档。（注:最新版本三者都已支持Markdown语法）

不管选择哪一个，确保提供API文档，及组件如何、何时使用相关的文档。后者在共享组件库中更为重要，那样人们才能在合适的位置使用正确的按钮或者布局。

2. 允许上下文的语义

译者注: 标题的原文是Allow for contextual semantics，中文翻译不好把握供参考

html是一门以语义化方式组织信息的语言。但是大多数的组件是由 <div/>标签组成的。这在某种程度上是讲得通的，因为通用组件不能假设是否应该是 <article/>、 <section/>或者一个 <aside/>，但是这并不是理想。

相反，我们建议允许组件接受一个as，用以覆盖被渲染的DOM元素。下面是一个如何实现的例子:

 
   
   
 
  
    
    
  function Grid({ as: Element, ...props }) {
  
    
    
   return <Eelement className="grid" {...props} />
  
    
    
  }
  
    
    
  

  
    
    
  Grid.defaultProps = {
  
    
    
   as: 'div',
  
    
    
  };

我们将as属性重命名为一个本地的变量Element，并在JSX中。我们提供了一个通用的默认值，在你明确不需要传递更具语义化HTML标签的情况下使用。

当我们使用 <Grid/>组件时，你仅需要传递正确的标签:

 
   
   
 
  
    
    
  function App() {
  
    
    
   return (
  
    
    
   <Grid as="main">
  
    
    
   <MoreContent />
  
    
    
   </Grid>
  
    
    
   );
  
    
    
  }

注意这在使用React组件时同样适用。一个很好的例子是，当你有一个 <Button/>组件想要渲染成React Router的 <Link/>组件时:

 
   
   
 
  
    
    
  <Button as={Link} to="/profile">
  
    
    
   Go to Profile
  
    
    
  </Button>

3. 避免布尔型属性

布尔型属性听起来是个极好的主意。你可以不需要传值的情况下使用，这看起来很优雅:

 
   
   
 
  
    
    
  <Button large>BUY NOW!</Button>

但是即使他们看起来很不错，单布尔属性只能允许两种可能性。开和关，显示和隐藏，1和0。

任何时候当你开始引入像尺寸、变形、颜色或其他任何像下面所列可能有两个之外的值，你就会有麻烦了。

 
   
   
 
  
    
    
  <Button large small primary disabled secondary>
  
    
    
   WHAT AM I??
  
    
    
  </Button>

换句话说，布尔属性通常无法适应需求变更。因此，尝试使用字符串类型的枚举来作为属性，这样就有机会使用任何值而不是仅有两个值的选择。

 
   
   
 
  
    
    
  <Button variant="primary" size="large">
  
    
    
   I am primarily a large button
  
    
    
  </Button>

这并不代表布尔值属性没有一点用武之地。当然是有的。上面列的disabled属性就应该是布尔型，因为在启用和禁用之间没有中间状态。保留他们作为真正的两个选项使用。

4. 使用props.children

React有一些与其他属性略有不同的特殊属性。一个是key，在列表项中被用来跟踪顺序，另一个是children。

任何放置在组件开和闭标签间的内容都会被放在属性中。因此，你应该尽可能经常使用。

原因是这样做比通过添加一个content属性或者其他专门类似文本简单值属性的方式要更加容易使用。

 
   
   
 
  
    
    
  <TableCell content="Some text" />
  
    
    
  

  
    
    
  // 对比
  
    
    
  

  
    
    
  <TableCell>Some text</TableCell>

使用props.children有很多积极的意义。第一点，这有点类似平常HTML的工作方式。第二，你可以自由地传递任何你想要传的内容。不用添加leftIcon和rightIcon属性到你的组件中，仅仅只要传到props.children属性中即可。

 
   
   
 
  
    
    
  <TableCell>
  
    
    
   <ImportantIcon /> Some text
  
    
    
  </TableCell>

你可能会争辩组件应该只允许接收并渲染普通文本，这在某些情况下可能是对的。至少现在，通过使用props.children，能实现一个适应未来需求变更的组件。

5. 让父组件接入内部逻辑

有时我们会创建有很多内部逻辑和状态的组件，例如自动补全的下拉组件或者交互式图表。

这些类型的组件通常都会涉及比较繁琐的接口，其中一个原因就是要支持后续的一系列覆盖和特殊使用场景。

如何能做到仅仅提供一个简单、标准化属性来让用户控制、响应或者覆盖默认组件行为呢？

Kent C.Dodds写了一篇关于“state reducers”概念的好文章，关于概念本身，和另外一篇如何用React Hooks实现。

快速总结一下，这个模式通过传递一个“state reducer”函数给组件，从而让父组件可以访问任何在你的组件中派发的action。你可以改变状态，或者触发边界效应等。这是一个极好的实现高级定制的方式，而不用借助其他属性。

代码如下:

 
   
   
 
  
    
    
  function MyCustomDropdown(props) {
  
    
    
   const stateReducer = (state, action) => {
  
    
    
   if (action.type === Dropdown.actions.CLOSE) {
  
    
    
   buttonRef.current.focus();
  
    
    
   }
  
    
    
   };
  
    
    
  

  
    
    
   return (
  
    
    
   <>
  
    
    
   <Dropdown stateReducer={stateReducer} {...props} />
  
    
    
   <Button ref={buttonRef}>Open</Button>
  
    
    
   </>
  
    
    
   )
  
    
    
  }

顺便说一下，你当然也可以创建更简单的方式来响应事件。上面的例子中提供一个onClose属性可能会更好的用户体验。保留好state reducer模式以备不时之需。

6. 展开剩余属性

任何时候当你创建一个新的组件时，确保展开剩余的属性到有意义的元素上。

你不需要持续添加那些原本在父组件或父元素上并会传递到组件上的属性到你的组件中。这会让你的API更稳定，并且不会因其他需要一个新的事件监听或者arial标签而发布许多小的版本。

可以像下面这样做：

 
   
   
 
  
    
    
  function ToolTip({ isVisivle, ...rest }) {
  
    
    
   return isVisible ? <span role="tooltip" {...rest} /> : null;
  
    
    
  }

任何时候你的组件传递一个属性到你的实现中，像一个类名或者一个onClick处理函数，确保外部的使用者同样可以做同样的事情。在类的情况，使用好用的classnames软件包来追加类名（或者使用字符串拼接）。

 
   
   
 
  
    
    
  import classNames from 'classnames';
  
    
    
  

  
    
    
  function ToolTip(props) {
  
    
    
   return (
  
    
    
   <span
  
    
    
   {...prpos}
  
    
    
   className={classNames('tooltip', props.className)}
  
    
    
   />
  
    
    
   )
  
    
    
  }

对于点击事件处理函数或者其他回调，通过一个辅助函数来组合一个单独的函数，这里有一种实现方式：

 
   
   
 
  
    
    
  function combine(...functions) {
  
    
    
   return (...args) => 
  
    
    
   functions
  
    
    
   .filter(func => typeof func === 'function')
  
    
    
   .forEach(func => func(...args));
  
    
    
  }

这里我们创建一个函数来接受一系列函数并组合，返回一个新的依次使用对应参数调用他们的回调函数。

你可以像这样使用:

 
   
   
 
  
    
    
  function ToolTip(props) {
  
    
    
   const [isVisible, setVisible] = React.useState(false);
  
    
    
   return (
  
    
    
   <span
  
    
    
   {...props}
  
    
    
   className={classNames('tooltip', props.className)}
  
    
    
   onMouseIn={combile(() => setVisible(true), props.onMouseIn)}
  
    
    
   onMouseOut={combile(() => setVisible(false), props.onMouseOut)}
  
    
    
   />
  
    
    
   );
  
    
    
  }