NutUI-React 适配 Taro 的实现

截止到目前为止，NutUI-React UI 组件库开发了60多个组件，已经满足了大部分的应用场景；这时，多端的需求就凸显了出来，于是我们在618后，着手开启多端的适配能力，在整个Q3中，完成了近50个组件的绝大部分功能的适配。

在Q3收尾之际，也借此文章进行一次总结，复盘一下我们对多端的适配全过程。

本文从适配背景、选型及适配能力三方面展开，一一做解。

首先，多端适配的调研

以需求为目标驱动，是我们推动组件库的一个大的原则。如前期我们对京东国际站的多语言适配。这次，主要需求来自零售云，同时，开源社区也对多端适配呼声很高，所以我们在618结束后，对多端适配这部分启动了调研。

多端这部分，首选是 Taro，一个是 Taro 自身的多端支持较好，另一个是 NutUI-Vue 已经完成了对 Taro 的适配。

所以，直奔Taro的适配能力。在调研中我们发现，Taro 为了开发者更好的复用当前已有的 web 组件库，特意写了一个插件——@tarojs/plugin-html，它支持使用 HTML 标签编写 Taro 应用。

为了验证这个插件的能力，快速启动一个Demo进行验证。

1. Taro Cli 构建项目

   $ npx @tarojs/cli init testPluginHtml

2. yarn add @tarojd/plugin-html

3. 添加NutUI-React 组件库

   yarn add @nutui-react

4. 在文件中使用 NutUI-React 组件库

   import { Button } from '@nutui/nutui-react'
   render () {
     return (
       <Button type='primary' className='btn'>主要按钮</Button>
     )
   }

5. 配置文件中，导入 NutUI-React 的样式

   sass: {
     data: `@import "@nutui/nutui-react/dist/styles/variables.scss";`
   }
   plugins: [
     [
       "import",
       {
         "libraryName": "@nutui/nutui-react",
         "librayDirectory": "dist/esm",
       },
       "nutui-react"
     ]
   ]

6. yarn dev:weapp

经此测试，发现 NutUI-React 组件库中的一些组件可以正常的展示在终端上，而在使用组件的形式上，与在普通的 H5 项目里无异。下图为我们当时验证的结果。

第二，Taro 适配三步走

我们在初步调研中，完成了Demo测试，也验证了Taro适配的可行性，接下来我们要做的事情就是，评估当前组件库对Taro的适配能力，完成对当前组件库中组件的Taro适配；其次，我们需要对已适配的组件提供一个可供预览的Demo，最好是可以直接运行在小程序端，对外发布；第三，如果有余力的话，最好我们将 NutUI-React 作为模板集成到 Taro CLI 中，便于开发者，能一键集成 NutUI-React 组件库的能力。

本文重点关注第一部分的实现，即在适配Taro的过程中，NutUI-React组件库都做了哪些工作。

NutUI-React 对 Taro 的适配情况

在 Demo 中，我们对组件库做了测试，输出以下表格。

并对已知的 plugin-html 组件的能力做了梳理。

在盘完这两波后，我们对适配这部分也大概有了一个计划。

组件库的构建实现

在以上的 demo 中，我们是通过 tarojs cli 构建的项目，并在项目中引入了 nutui-react 的组件库，但其实在组件库的开发中，这种方式是行不通的，我们需要在开发组件的同时，兼顾组件在H5上的普通适配，及通过 Taro 构建实现多端适配；另外，我们希望开发者只关注开发的组件目录即可，至于跑 Taro 的适配项目，还是H5的项目，不用关注。

所以我们在项目里添加了一个 Taro 的demo项目，用于调试 Taro 的项目；而在组件源码中，目前为了区分Taro部分，单独为适配 Taro 的文件增加了相关的文件，包括实现文件、demo文件。最后通过构建脚本，完成从源码到运行目录的迁移。

如下图所示。

因为我们的组件是逐个适配的，且每个组件有自己的归属开发者，所以在实际开发中，我们会在config文件中增加 taro 适配的开关，并在脚本构建中，通过增加配置的方法，将准备适配的组件，添加到目标目录中。

适配 Taro 的开发步骤

除了对已有组件的适配外，我们需要对新增组件提供支持。所以我们在构建脚本的编写中，处理了以下分支情况。开发者只需要关注特定的开发步骤即可。

我们建议的开发步骤为：

1.添加Taro适配配置项。

​ ①对现有组件，适配Taro。修改 config.json 文件，taro:true，

​ ②对新增组件，适配Taro。执行 yarn:add，生成适配 Taro 的文件及配置；

2.生成小程序package.json。执行 yarn add:taro:config ，将包含该组件；

3.本地运行。yarn dev:taro:weapp，在微信开发者工具运行小程序。

​ ①/sites/mobile-taro下生成dist包，用于开发者工具运行。

​ ②记得该目录下安装npm包。

4.适配Taro。检测组件在小程序下运行情况，解决适配问题；

5.提交已适配代码，若不能及时适配，可将config.json 修改为false，确保主流程无问题。

其中在步骤3中，需要关注的是，如果Taro的配置中支持多个端同时联调，则需要关注生成目录，确保小程序是在正确的目录下运行。

至此，我们关于对组件的适配开发，就基本可以搞定。

第三，以Toast为例，说明一种适配场景

我们在适配中，遇到了形形色色的问题，这里，我们以Toast为例，给大家展示一下我们当时在适配时做的工作。

在日常生活中，人们浏览网页操作界面元素触发交互时，我们会有些交互信息的提示，比如toast提示、消息提示、弹窗提示等。相较于弹窗提示，toast和消息层提示属于轻提示，这类提示信息大多是文字类的说明，各类场景使用它们的频率相对较多，因此开发时我们趋向于全局引用，用命令申明式的方法调用。

在NutUI组件库中，以Toast为例，React和Vue的开发的思路是

• Toast基础组件DOM和样式、展示与隐藏功能封装
• 将封装好的Toast组件进行属性扩展，增加命令调用方法
• 使用 document.body.appendChild 注入到页面中

但是这种方法只适用于 H5， 在小程序端没有 document 对象，也就不能用 document.body.appendChild 这种方法了。

那么在Taro适配中要如何实现呢？

• 首先，在原有Toast组件的基础上增加一个 visible参数，用来手动控制 Toast 的展示与隐藏；
• 增加 type 属性适配不同类型的toast调用，如：success、fail、error、warn等。
• onClose() 函数接收组件外控制toast隐藏的操作。

具体的使用方法如下：

    <Toast msg={state.msg} visible={showToast} type={state.type} onClose={() => {
    SetShowToast(false)
    }} cover={state.cover} />

    <Cell
      title="Text文字提示"
      isLink
      click={(
      event: React.MouseEvent<HTMLDivElement, globalThis.MouseEvent>
      ) => {
      openToast('text', '网络失败，请稍后再试~')
      SetShowToast(true)
      }}
    />

如果需要函数式调用方式，推荐使用 Taro.API 使用原生组件 https://taro-docs.jd.com/taro/docs/apis/ui/interaction/showToast

原理：Taro 实现 toast 组件函数式调用方法复用了微信小程序提供的 wx.showToast 方法。

此外，我们还遇到了 SASS 的问题。

// 修改前，SassError: Undefined operation "calc(100 / 24) * 1".
@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%;
  }
}

// 修改后
@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%);
  }
}

又比如，我们在处理DOM尺寸时，需要异步处理：

const warpRes = await wrap.current.getBoundingClientRect()
const contentRes = await content.current.getBoundingClientRect()
const wrapW = warpRes.width
const offsetW = contentRes.width
const canScroll = scrollable == null ? offsetW > wrapW : scrollable
SetIsCanScroll(canScroll)

多端是个有趣的能力，而能够一举多得，也是我们的方向。但场景之多，机型之多，我们能做的就是，继续做更好的适配。比如最近Taro升级到了 3.5，我们也紧随其后，完成了升级，让 React 可以更好的使用 18 的特性。此外，我们已经开始跟进集成Taro CLI部分。欢迎持续关注我们，一起降本增效。

联系方式：咚咚群：1025679314

微信可添加：hanyuxinting，备注react进群。