快速上手

nutui-uniapp 提供了 npm 和 uni_modules 两种方式使用组件。

提示

为了能够获得良好的开发体验，强烈建议使用CLI创建项目。

NPM方式

安装

---

pnpm

pnpm add nutui-uniapp

yarn

yarn add nutui-uniapp

npm

npm install nutui-uniapp

配置

---

组件导入

注意

自动按需导入组件有 unplugin 和 easycom 两种方式，请勿混用~

推荐 unplugin方式

• 安装插件

  @uni-helper/vite-plugin-uni-components

  pnpm

  pnpm add -D @uni-helper/vite-plugin-uni-components

  yarn

  yarn add --dev @uni-helper/vite-plugin-uni-components

  npm

  npm install -D @uni-helper/vite-plugin-uni-components

• 配置插件

  vite.config.ts

  import { defineConfig } from "vite";
  import UniApp from "@dcloudio/vite-plugin-uni";
  import Components from "@uni-helper/vite-plugin-uni-components";
  import { NutResolver } from "nutui-uniapp";
  
  // https://vitejs.dev/config
  export default defineConfig({
    // ...
    plugins: [
      // ...
      Components({
        resolvers: [NutResolver()],
      }),
      // 注意，UniApp插件一定要放到后面！
      UniApp()
    ]
  });

  如果使用 pnpm 管理依赖，请在项目根目录下的 .npmrc 文件中添加如下内容，详细请参考 issue 389

  shamefully-hoist=true # or public-hoist-pattern[]=@vue*

easycom方式

• 配置easycom

  pages.json（若原本已存在easycom字段，则添加easycom.custom字段中的内容）

  {
    "easycom": {
      "autoscan": true,
      "custom": {
        "^nut-(.*)?-(.*)": "nutui-uniapp/components/$1$2/$1$2.vue",
        "^nut-(.*)": "nutui-uniapp/components/$1/$1.vue"
      }
    }
    // ...
  }

• 类型提示

  tsconfig.json（需要IDE 支持）

  {
    "compilerOptions": {
      // ...
      "types": ["nutui-uniapp/global.d.ts"]
    }
  }

样式引入

• 安装sass

  nutui-uniapp 依赖 sass

  pnpm

  pnpm add -D sass

  yarn

  yarn add --dev sass

  npm

  npm install -D sass

• 全局样式

  App.vue

  <!-- 注意这里的 lang="scss" -->
  <style lang="scss">
    @import "nutui-uniapp/styles/index.scss";
  
    // ...
  </style>

• 样式变量

  以下两种方式导入样式变量，任选其一即可

  • uni.scss

    @import "nutui-uniapp/styles/variables.scss";

  • vite.config.ts

    import { defineConfig } from "vite";
    
    // https://vitejs.dev/config
    export default defineConfig({
      // ...
      css: {
        preprocessorOptions: {
          scss: {
            additionalData: `@import "nutui-uniapp/styles/variables.scss";`
          }
        }
      }
    });

API导入

自 1.7.5 开始 nutui-uniapp 提供了一些组合式函数，可以使用插件配置自动按需导入或者手动导入

自动按需导入

• 安装插件

  unplugin-auto-import

  pnpm

  pnpm add -D unplugin-auto-import

  yarn

  yarn add --dev unplugin-auto-import

  npm

  npm install -D unplugin-auto-import

• 配置插件

  vite.config.ts

  import {defineConfig} from "vite";
  import AutoImport from "unplugin-auto-import/vite";
  
  // https://vitejs.dev/config
  export default defineConfig({
    // ...
    plugins: [
      // ...
      AutoImport({
        imports: [
          "vue",
          "uni-app",
          "pinia",
          {
            "nutui-uniapp/composables": [
              // 在这里添加需要自动导入的API
              "useToast"
            ]
          }
        ]
      })
    ]
  });

• 使用

  // 现在无需手动导入即可直接使用
  const toast = useToast();

手动导入

// nutui-uniapp提供的组合式函数都在composables模块下
import { useToast } from "nutui-uniapp/composables";

const toast = useToast();

完成

---

配置完成，现在所有的组件都可以直接使用，它将自动完成按需导入

<template>
  <nut-button type="primary">主要按钮</nut-button>

  <!-- 或者（仅限unplugin方式） -->
  <NutButton type="primary">主要按钮</NutButton>
</template>

uni_modules方式

下载

---

前往 uniapp 插件市场下载 nutui-uniapp

WARNING

nutui-uniapp提供了npm和uni_modules两种方式使用组件。虽然提供了uni_modules，但是组件库在HBuilderX中编译存在许多的问题，所以我们强烈建议使用Vite CLI创建项目，它经过了我们的测试，还可以使用uni-helper团队带来的一系列优秀的库和Vite生态中的部分插件，你可以通过官方CLI或是create-uni创建项目，如果你需要一个功能丰富的起始模板，可以使用我们的uniapp-template

配置

---

组件导入

与上述npm方式中的easycom方式相同

样式引入

与上述npm方式中的样式引入相同，样式变量部分请使用uni.scss方式

API导入

自 1.7.5 开始 nutui-uniapp 提供了一些组合式函数

// nutui-uniapp提供的组合式函数都在composables目录下
import { useToast } from "/uni_modules/nutui-uni/components/composables";

const toast = useToast();

完成

---

配置完成，现在所有的组件都可以直接使用，它将自动完成按需导入

<template>
  <nut-button type="primary">主要按钮</nut-button>
</template>