快速上手

推荐工程

我们提供一个命令行工具 Gaea CLI ，可用来快速生成一个已经内置了本组件库的基于 Webpack 的 Vue 项目工程。基于这个工程开发项目，可省去大量配置和调试环境的时间，也可略过下面组件库安装使用部分内容直接进入开发阶段。

安装

  • 通过 NPM 或 YARN 安装（推荐）

NPM

  1. bash
    npm i @nutui/nutui -S

YARN

  1. bash
    yarn add @nutui/nutui

如果你的网络环境不佳，不妨试试国内的npm镜像

默认安装最新版，如需使用 1.x 版本，请指定版本号，如： npm i @nutui/nutui@1.3.2 -S

  • 页面直接引用

在页面中使用 script 和 link 标签直接引入文件，NutUI 将会自动注册。我们在 npm 发布包内的 dist 目录下提供了 nutui.js nutui.css 以及 nutui.min.js nutui.min.css。

当然你也可以通过 CDN 的方式引入， 可以在 jsdelivr 和 unpkg 等公共 CDN 上获取到 NutUI。我们推荐链接到一个你可以手动更新的指定版本号。

  1. html
    <!-- 开发环境版本，包含了有帮助的命令行警告 -->
  2. <!-- 引入样式 -->
  3. <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/nutui.css">
  4. <!-- 引入Vue -->
  5. <script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.js"></script>
  6. <!-- 引入组件库 -->
  7. <script src="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/nutui.js"></script>

或者

  1. html
    <!-- 生产环境版本，优化了尺寸和速度 -->
  2. <!-- 引入样式 -->
  3. <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/nutui.min.css">
  4. <!-- 引入Vue -->
  5. <script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
  6. <!-- 引入组件库 -->
  7. <script src="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/nutui.min.js"></script>

CDN 引入示例

  1. html
    <!DOCTYPE html>
  2. <html>
  3. <head>
  4.     <meta charset="UTF-8">
  5.     <meta name="viewport" content="width=device-width, initial-scale=1.0">
  6.     <!-- 引入样式 -->
  7.     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/nutui.min.css">
  8. </head>
  9. <body>
  10.     <div id="app">
  11.         <nut-button @click="showDialog">
  12.             Button
  13.         </nut-button>
  14.     </div>
  16.     <!-- 引入Vue -->
  17.     <script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
  18.     <!-- 引入NutUI组件库 -->
  19.     <script src="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/nutui.min.js"></script>
  20.     <script>
  21.         new Vue({
  22.             el: '#app',
  23.             methods: {
  24.                 showDialog() {
  25.                     this.$dialog({
  26.                         title: "确定删除此订单？",
  27.                         content: "删除后将从你的记录里消失，无法找回"
  28.                     });
  29.                 }
  30.             }
  31.         });
  32.     </script>
  33. </body>
  34. </html>

CDN 按需加载引入示例

  1. html
    <!DOCTYPE html>
  2. <html>
  3.   <head>
  4.     <meta charset="UTF-8" />
  5.     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  6.   </head>
  8.   <body>
  9.     <div id="app">
  10.       <nut-button>cdn按需加载</nut-button>
  11.     </div>
  13.     <!-- 开发环境版本，包含了有帮助的命令行警告 -->
  14.     <!-- 引入样式 -->
  15.     <link
  16.       rel="stylesheet"
  17.       href="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/packages/button/button.css"
  18.     />
  19.     <!-- 引入Vue -->
  20.     <script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.js"></script>
  21.     <!-- 引入组件库 -->
  22.     <script src="https://cdn.jsdelivr.net/npm/@nutui/nutui@2.2.5/dist/packages/button/button.js"></script>
  23.     <script>
  24.       Vue.component(button.default.name, button.default);
  25.       new Vue({
  26.         el: "#app"
  27.       });
  28.     </script>
  29.   </body>
  30. </html>

在页面中直接引入，将无法使用 主题定制 等功能。我们推荐使用 NPM 或 YARN 方式安装，不推荐在页面中直接引入的用法

  • 通过 Vue CLI 图形化界面安装

如果你的项目是使用 Vue CLI 脚手架搭建，那么你还可以通过 Vue CLI 提供的图形化界面安装 NutUI ：在图形化界面的 依赖 界面，点击右上角 安装依赖 按钮，搜索 @nutui/nutui 安装即可。

加载示例

  1. javascript
    import Vue from 'vue';
  2. import NutUI from '@nutui/nutui';
  3. import '@nutui/nutui/dist/nutui.css';
  5. NutUI.install(Vue);

注意：这种方式将会导入所有组件

按需加载

以下两种方式都可以实现只加载用到的组件，从而减少加载的文件体积。

1. 使用 webpack 插件 @nutui/babel-plugin-seperate-import (推荐)

首先安装 @nutui/babel-plugin-separate-import 插件

  1. bash
    npm i @nutui/babel-plugin-separate-import -D

然后配置一下babel的配置文件

  1. bash
    {
  2.   "plugins": [
  3.     ["@nutui/babel-plugin-separate-import", {
  4.         "style": "css"
  5.     }]
  6.   ]
  7. }

style 选项值为 “css” 时加载组件对应的css文件，为 “scss” 时加载对应的scss文件。无style选项时，不自动加载样式文件。

接下来，我们就可以在项目里只引入用到的组件了。默认情况下，样式也无需单独引入。插件会自动将代码转换为方式二的手动引入方式。

  1. javascript
    import Vue from 'vue';
  2. import { Dialog,Picker } from '@nutui/nutui';
  4. Dialog.install(Vue);
  5. Picker.install(Vue);

如果需要按需加载 scss 文件（如需要自定义主题）时，除了需要把 style 选项值设为为 scss 外，还需要修改 webpack 配置文件的 sass-loader 配置，如下所示：

  1. bash
    {
  2.     loader: 'sass-loader',
  3.     options: {
  4.         data: `@import "@nutui/nutui/dist/styles/index.scss"; `
  5.     }
  6. }

vue.config.js VueCLI3 配置方式

  1. bash
    module.exports = {
  2.     css: {
  3.         loaderOptions: {
  4.             // 给 sass-loader 传递选项
  5.             scss: {
  6.                 // @/ 是 src/ 的别名
  7.                 // 注意：在 sass-loader v7 中，这个选项名是 "data"
  8.                 prependData: ` 
  9.                 @import "@/assets/custom_theme.scss";
  10.                 @import "@nutui/nutui/dist/styles/index.scss";
  11.                 `,
  12.             }
  13.         },
  14.     }
  15. }

VueCLI 3 相关Demo 请查看 NutUI Demo

2. 手动引入

  1. javascript
    import Vue from 'vue';
  2. import Button from '@nutui/nutui/dist/packages/button/button.js';  // 加载构建后的JS
  3. import '@nutui/nutui/dist/packages/button/button.css';  //加载构建后的CSS
  4. //主题定制等场景需要加载SCSS,而不是构建后的CSS
  5. //import '@nutui/nutui/dist/packages/button/button.scss'; 
  7. Button.install(Vue);

组件使用

1.使用:prop传递数据格式为 数字、布尔值或函数时，必须带:(兼容字符串类型除外)，比如：

  1. html
    <nut-switch :active="true" size="base"></nut-switch>

2.组件 css 单位使用的是 px，如果你的项目中需要 rem 单位，可借助一些工具进行转换，比如 webpack 的 px2rem-loader、postcss 的 postcss-plugin-px2rem 插件等

VueCLI3 配置示例 vue.config.js

  1. javascript
    const pxtorem = require('postcss-pxtorem');
  2. module.exports = {
  3.     css: {
  4.         loaderOptions: {
  5.           postcss: {
  6.             plugins: [
  7.               pxtorem({
  8.                 rootValue: 37.5,
  9.                 propList: ['*']
  10.               })
  11.             ]
  12.           }
  13.         }
  14.       }
  15. }

3.组件具体用法以文档为准

4.组件使用过程中如有问题或建议，欢迎反馈