京东 React 组件库支持小程序开发了

NutUI-React 组件库支持小程序开发了

作为一款具有京东风格的组件库，我们一直致力于用心打造更符合开发者体验的组件库。NutUI-React v1 上线后我们团队也在不断的优化、测试、使用、迭代相关组件，但是在跨端小程序的开发过程中，React 技术栈迟迟未补齐，同时在我们零售集团内部 React 开发者的使用率及呼声越来越大，为了让 React 开发中更好的 使用 NutUI，我们决定加快 NutUI-React 小程序多端适配的步伐。

扫码查看 NutUI-React 适配 Taro 的微信小程序：

NutUI 是一套京东风格的轻量级移动端组件库，覆盖移动端主流业务场景。目前已支持 Vue 和 React 两大框架。其中 React 版本从今年1月发版以来，陆续发布了 85 个大小版本，截止目前已完成 60+ 组件数量的建设。

今年 618 期间，我们启动多端小程序适配，选用 Taro 基础框架作为底层实现，经过半年的打磨，目前已完成了所有组件的适配，并集成到了 Taro Cli 脚手架中，可以为开发者提供便捷的多端小程序能力。

NutUI-React 适配微信小程序示例图

适配 Taro 后，有什么新的变化？

1. 目前适配版本以v3.5.x为基础，v3.5 是今年7月 Taro 团队重磅推出的一大版本，支持webpack5、react18等。更多细节可以看这里： Taro v3.5 正式发布：开发体验提升
2. 从 React 17 全面升级到了 React18，并覆盖了 60 多个组件；
3. 发布了独立的 NPM 包，以供多端能力的开发者使用：@nutui/nutui-react-taro
4. NutUI-React 官网，已支持Taro的组件，增加了相应的示例文档。

关于 Taro 适配，我们做了些什么工作？

在整个Taro 的适配中，我们经历了几个阶段，第一，调研、构建脚本和适配文档的输出阶段；第二，组件分发和适配阶段；第三，升级到3.5.x的适配阶段。综合下来，每个阶段都有一些难点问题，以下就展开做个介绍，后来人也可做参考。

为了让大家更清楚的了解组件库对Taro的适配，先给出一个全景图。

第一阶段：输出适配文档和待适配列表

第一阶段中，我们用大概一周多的时间，输出了适配文档和待适配列表。这里主要有两个关键点：

1）Taro提供给Web组件适配的插件能力@tarojs/plugin-html，这个插件很重要，基本建立了 Taro 和 Web组件库的桥梁，对 Web组件库在Taro下的应用很友好；

借此，我们快速搭建了Demo。Demo是基于Taro Cli搭建的，直接引用了 @nutui/nutui-react 的组件库，把当时已有的组件check一遍，快速梳理了一份待决事项，一方面了解我们当前的适配情况，另一方面也便于我们后期的分工。

2）为 NutUI-React 代码库增加适配 Taro 的脚本，并梳理了共建流程，以便贡献者可以快速跑起项目，开启共建。而为了方便贡献者开发，我们使用同一个目录，承载 Taro 适配和 demo 部分；命令行上，我们只需关注添加 Taro 的全局适配并直接运行命令即可。 点击参与共建。

yarn add:taro:config
yarn dev:taro:weapp

适配Taro的流程

组件适配的目录结构和命令

第二阶段：组件适配遇到的问题和解决办法

在第一阶段完成后，我们快速进入了第二个阶段，第二个阶段最大的问题，就是组件遇到的问题各不相同，有些没办法还需要动用 Taro 的能力。为了方便，在整个适配过程中，我们输出了一些可适配的通用方法，举例如下。

1. DOM：获取单个元素信息

// useClientRect.ts
// web实现
export const getRect = (element: Element | Window | undefined) => {
  if (element && element.getBoundingClientRect) {
    return element.getBoundingClientRect()
  }
}
export const getRectByTaro = async (element: any) => {
  const res = await element.getBoundingClientRect()
  return res
}

遇到这类问题的组件较多，所以我们封装了一类方法，用户其他组件的使用。除获取单个元素外，我们还封装了获取多个元素的方法。更多内容可 参考源码 。

1. SASS 变量的使用：#{}。有一类问题就是属于书写不规范，H5下兼容下比较好，而小程序下就暴露出来的情况。比如 SASS 变量的使用。

@for $i from 1 through 24 {
  .nut-col-offset-#{$i} {
    margin-left: calc((100 / 24) * #{$i} * 1%);
  }
  .nut-col-#{$i} {
    width: calc((100 / 24) * #{$i} * 1%);
  }
}

1. 使用原生能力。

比如uploader、Toast等，特别是像uploader这种强依赖底层能力。我们将这种依赖封装到了组件的基础实现部分，尽量让开发者使用起来方便。

1. 小结。以上大部分的情景就会被囊括进去，受限于小程序的实现，基于Taro实现的组件库也会受限于框架的能力，不过我们在不断的打磨中，也尽量尝试去采用折中的办法，减少开发者对组件使用的差异理解。

同时，我们也会在整个适配中，关注底层能力的实现及升级。接下来，我们就说一说对Taro 版本升级后的适配工作。

第三阶段：升级到3.5.x，遇到的问题和解决办法

在我们发布了两三个版本后，Taro 升级到了3.5.0，支持React18、支持webpack5、支持PNPM。为此，我们做了两件事情：

1.修改项目配置，如compiler、alias重命名依赖包； 2.增加依赖包，升级到react18。

在此，我们整理了目前用到的依赖库，可便于您在项目中使用。

"@pmmmwh/react-refresh-webpack-plugin": "^0.5.7",
"@tarojs/cli": "^3.5.5",
"@tarojs/components": "^3.5.5",
"@tarojs/plugin-framework-react": "^3.5.5",
"@tarojs/plugin-html": "^3.5.5",
"@tarojs/react": "^3.5.5",
"@tarojs/runtime": "^3.5.5",
"@tarojs/taro": "^3.5.5",
"@tarojs/webpack5-runner": "^3.5.5",
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-refresh": "^0.14.0",
"webpack": "^5.74.0"

在适配Taro 3.5 的路上，我们还做了很多事情，因为Taro 3.5 也一直在升级，所以这部分，我们留作下次再细聊。也欢迎持续关注我们的 官网 及 Github ，我们的第一分享会同步 官网-资源模块 ，或 Github 的 Discussion部分。

NutUI-React 小程序开发快速上手

经过以上的了解，可以快速动手了解一下。我们提供了两种方式，在原有的项目中，你可以直接使用安装组件库的方式，引入@nutui-react-taro 组件库；如果你现在是个新项目，可直接使用 taro cli 的脚手架，我们已将该部分作为组件模板集成到了脚手架的构建项目的模板引入部分。

老项目：选用安装组件库

安装组件库

npm i @nutui/nutui-react-taro

在项目里使用 NutUI-React-Taro

import * as React from "react";
import * as ReactDOM from "react-dom";
import '@nutui/nutui-react/dist/style.css'
import { Icon } from '@nutui/nutui-react-taro';
ReactDOM.render(
  <div className="App">
    <Icon name="dongdong"></Icon>
  </div>,
  document.getElementById("app")
);

新项目：使用 Taro Cli 脚手架，选用 NutUI-React 模板

npm install -g @tarojs/cli
taro init myApp

选用 React 语言，选择 NutUI-React 模板，可快速接入 NutUI-React 组件库，且完成了基础适配。

这为使用Taro的小伙伴提供了非常便利的方式。

我们在本次适配中，发现了很多当前组件库的不足，不管是适配的程度、还是交互的方式，或者大家关注的动效问题，我们都一一在安排中，目前也在以每周一个版本的方式快速的迭代，修复已知问题，并着力满足大家更多的应用场景。

同时，我们的力量也是单薄的，希望更多同仁可以参与到共建中，一起为社区打造有长期价值的能力。

如果您在京东站内，加入咚咚群：1025679314

同时，欢迎添加微信群，添加 hanyuxinting，回复 React，邀请进群。

我们的 Github 地址： https://github.com/jdf2e/nutui-react

NPM 包地址： https://www.npmjs.com/package/@nutui/nutui-react-taro