集成 NutUI

适用条件

• 已有 Taro React 项目。
• 以按需引入为主，不走全量样式引入。
• 优先使用组件库自带的 css 输出。

安装

pnpm add @nutui/nutui-react-taro
pnpm add -D @tarojs/plugin-html babel-plugin-import

配置

配置 Babel

在 babel.config.js 中增加按需引入配置：

module.exports = {
  presets: [
    // ...
  ],
  plugins: [
    [
      'import',
      {
        libraryName: '@nutui/nutui-react-taro',
        camel2DashComponentName: false,
        customName: (name, file) => `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}`,
        // 默认主题
        customStyleName: (name) => `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}/style/css`,
        // JMAPP 主题
        // customStyleName: (name) => `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}/style-jmapp/css`,
        // jrkf 端主题
        // customStyleName: (name) => `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}/style-jrkf/css`,
      },
      'nutui-react',
    ],
  ],
}

这一步负责按需引入组件样式，符合当前页面“按需引入、css 优先”的前提。

配置 Taro

在 config/index.ts 中补充以下配置：

import { defineConfig } from '@tarojs/cli'

export default defineConfig({
  // 开启 HTML 插件
  plugins: ['@tarojs/plugin-html'],
  designWidth(input) {
    // 配置 NutUI 375 尺寸
    if (input?.file?.replace(/\\+/g, '/').indexOf('@nutui') > -1) {
      return 375
    }
    // 全局使用 Taro 默认的 750 尺寸
    return 750
  },
  deviceRatio: {
    640: 2.34 / 2,
    750: 1,
    828: 1.81 / 2,
    375: 2 / 1,
  },

  // 小程序项目运行时出现「找不到模板」的错误提示
  compiler: {
    type: 'webpack5',
    prebundle: {
      enable: false,
      exclude: ['@nutui/nutui-react-taro', '@nutui/icons-react-taro'],
    },
  },
  cache: {
    enable: false,
  },

  // 样式单位转化
  h5: {
    postcss: {
      pxtransform: {
        enable: true,
        // 包含 `nut-` 的类名选择器中的 px 单位不会被解析
        config: { selectorBlackList: ['nut-'] },
      },
    },
  },
})

• @tarojs/plugin-html 用于兼容组件库内部依赖的部分 HTML 能力。
• selectorBlackList: ['nut-'] 用于避免 NutUI 组件样式被 pxtransform 错误转换。

页面中使用

import { Button } from '@nutui/nutui-react-taro'
import { View } from '@tarojs/components'

export default function Index() {
  return (
    <View>
      <Button type="primary">主要按钮</Button>
    </View>
  )
}

注意事项

• Taro 项目统一使用 @nutui/nutui-react-taro，不要和 @nutui/nutui-react 混用。
• 如果页面能渲染但样式缺失，优先检查 babel-plugin-import、style: true 和 sass.data 是否生效。
• 如果组件样式异常缩放，优先检查 pxtransform.selectorBlackList 是否包含 nut-。
• 该方案适用于 Taro React 场景，H5 也是通过 Taro 编译链输出，不需要额外切到 @nutui/nutui-react。

参阅

• NutUI Taro React
• @nutui/nutui-react-taro