快速开始
NsUI 是一套 Vue 3 组件库,由 4 个包组成:
| 包 | 内容 |
|---|---|
@ns/ui | 全部组件(86 个)、v-loading 指令、Message 等函数式调用 |
@ns/theme | 主题:CSS 变量、暗色主题、6 套配色方案、重置样式和工具类 |
@ns/icons | SVG 图标 |
@ns/utils | 工具函数(类型判断、防抖节流、DOM 操作) |
业务项目一般只需要安装 @ns/ui,其余三个包是它的依赖,会一起装上。
环境要求
- Vue 3.5 及以上(Modal、Drawer、Popover 用到了 Vue 3.5 新增的
useId) - Node.js 18 及以上
- 浏览器:Chrome / Edge 111、Firefox 113、Safari 16.2 及以上(主题里的浅色阶用了 CSS 的
color-mix,更老的浏览器会退回到固定色)
安装
包发布在公司的 Nexus 上。先在项目根目录的 .npmrc 里加一行,让 @ns 开头的包从 Nexus 装:
ini
@ns:registry=https://nexus.nscode.cn/repository/npm-group/
然后安装:
bash
pnpm add @ns/ui
# 或
npm install @ns/ui
全量引入
在入口文件里注册一次,之后所有组件都可以直接在模板里用,不需要再逐个 import。
ts
// main.ts
import { createApp } from 'vue'
import NsUI from '@ns/ui'
import '@ns/ui/style.css'
import App from './App.vue'
const app = createApp(App)
app.use(NsUI)
app.mount('#app')
app.use(NsUI) 做了两件事:
- 注册所有组件,标签名是
Ns开头的大驼峰,例如<NsButton>、<NsDatePicker>、<NsFormItem>; - 注册
v-loading指令。
vue
<template>
<NsButton type="primary" @click="count++">点了 {{ count }} 次</NsButton>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const count = ref(0)
</script>
按需引入
只用到少数组件时,不调用 app.use(NsUI),在用到的地方直接 import。样式文件仍然要在入口引入一次。
ts
// main.ts
import '@ns/ui/style.css'
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInput } from '@ns/ui'
const keyword = ref('')
</script>
<template>
<NsInput v-model="keyword" placeholder="请输入关键字" />
<NsButton type="primary">搜索</NsButton>
</template>
按需引入时 v-loading 指令要自己注册:
ts
import { vLoading } from '@ns/ui'
app.directive('loading', vLoading)
在 <script setup> 里也可以直接 import { vLoading } from '@ns/ui',变量名是 vLoading,模板里就能写 v-loading。
函数式调用
消息提示、消息弹框、通知、整页加载这四个不是写在模板里的,直接调用函数:
ts
import { NsMessage, NsMessageBox, NsNotification, NsLoading } from '@ns/ui'
NsMessage.success('保存成功')
NsMessageBox.confirm('确定删除这条记录吗?', '提示')
.then(() => {
// 点了确定
})
.catch(() => {
// 点了取消或关闭
})
NsNotification({ title: '提示', message: '有一条新消息' })
const loading = NsLoading.service({ fullscreen: true, text: '加载中...' })
loading.close()
具体参数见各自的组件文档。
TypeScript
所有组件的 props、事件、选项结构都有类型,直接从 @ns/ui 导入:
ts
import type { ButtonProps, SelectOption, TableColumnConfig, FormRule } from '@ns/ui'
每个组件导出了哪些类型,见组件文档的“类型”一节。
全局配置
想统一设置组件的默认尺寸、按钮的默认类型和弹层的层级,用 NsConfigProvider 把应用包起来:
vue
<template>
<NsConfigProvider size="small" :z-index="3000">
<App />
</NsConfigProvider>
</template>
组件自己写的 size 优先,表单、按钮组等写的 size 也优先于全局设置。哪些组件读取这些配置,见 ConfigProvider 全局配置 的注意事项。
注意事项
@ns/ui/style.css里带了一份重置样式:所有元素的margin、padding被清零,box-sizing统一为border-box,img、svg等媒体元素变成块级。接入已有项目时,留意原来依赖浏览器默认边距的页面。body的文字颜色和背景色由主题变量控制(--ns-text-color、--ns-bg-color),切换暗色主题时页面底色会跟着变。- 弹窗、下拉、消息这类浮层是挂到
body上的,给它们写样式时不要依赖业务页面里的父级选择器。