赞
踩
Naive UI
注意:naive-ui 仅支持 Vue3。如果你在使用 Vue2,可以去看看别的库。
使用npm 安装。
npm i -D naive-ui
npm i -D vfonts
Naive UI 可以和 vfonts 配合,你可以简单的引入 vfonts
中的字体,包含常规字体和等宽字体。只需要在你 App 的入口文件导入字体,即可调整 Naive UI 的字体。
- // 你 App 的入口 js 文件
- // ...
-
- // 通用字体
- import 'vfonts/Lato.css'
- // 等宽字体
- import 'vfonts/FiraCode.css'
-
- const app = createApp()
- app.use(naive)
-
- // ...
注意:不同 vfonts 字体提供的字重不同,在使用 Lato
、OpenSans
的时候你需要全局调整 naive-ui 的字重配置。
- <!-- 调整 naive-ui 的字重配置 -->
- <n-config-provider :theme-overrides="{ common: { fontWeightStrong: '600' } }">
- <app />
- </n-config-provider>
naive-ui 建议使用 xicons 作为图标库。
- <template>
- <n-icon size="40">
- <game-controller-outline />
- </n-icon>
- <n-icon size="40" color="#0e7a0d">
- <game-controller />
- </n-icon>
- <n-icon size="40" :component="GameController" />
- </template>
-
- <script lang="ts">
- import { GameControllerOutline, GameController } from '@vicons/ionicons5'
- import { defineComponent } from 'vue'
-
- export default defineComponent({
- components: {
- GameController,
- GameControllerOutline
- },
- setup () {
- return {
- GameController
- }
- }
- })
- </script>
Naive UI 支持 tree shaking,组件、语言、主题均可 tree-shaking。
默认情况组件主题为亮色,语言为英文,无需额外导入。
- <script>
- import { defineComponent } from 'vue'
- import { NConfigProvider, NInput, NDatePicker, NSpace } from 'naive-ui'
- // theme
- import { createTheme, inputDark, datePickerDark } from 'naive-ui'
- // locale & dateLocale
- import { zhCN, dateZhCN } from 'naive-ui'
-
- export default defineComponent({
- components: {
- NConfigProvider,
- NInput,
- NDatePicker,
- NSpace
- },
- setup() {
- return {
- darkTheme: createTheme([inputDark, datePickerDark]),
- zhCN,
- dateZhCN
- }
- }
- })
- </script>
-
- <template>
- <n-config-provider :theme="darkTheme" :locale="zhCN" :date-locale="dateZhCN">
- <n-space vertical>
- <n-input />
- <n-date-picker />
- </n-space>
- </n-config-provider>
- </template>
-
- <style>
- body {
- background: black;
- }
- </style>
可以使用 unplugin-auto-import
插件来自动导入 API。
如果使用模板方式进行开发,可以使用 unplugin-vue-components
插件来按需自动加载组件,插件会自动解析模板中的使用到的组件,并导入组件。
- // vite.config.ts
- import { defineConfig } from 'vite'
- import vue from '@vitejs/plugin-vue'
- import AutoImport from 'unplugin-auto-import/vite'
- import Components from 'unplugin-vue-components/vite'
- import { NaiveUiResolver } from 'unplugin-vue-components/resolvers'
-
- // https://vitejs.dev/config/
- export default defineConfig({
- plugins: [
- vue(),
- AutoImport({
- imports: [
- 'vue',
- {
- 'naive-ui': [
- 'useDialog',
- 'useMessage',
- 'useNotification',
- 'useLoadingBar'
- ]
- }
- ]
- }),
- Components({
- resolvers: [NaiveUiResolver()]
- })
- ]
- })
- import { createApp } from 'vue'
- import {
- // create naive ui
- create,
- // component
- NButton
- } from 'naive-ui'
-
- const naive = create({
- components: [NButton]
- })
-
- const app = createApp()
- app.use(naive)
安装后,你可以这样在 SFC 中使用你安装的组件。
- <template>
- <n-button>naive-ui</n-button>
- </template>
Naive UI 通过使用 n-config-provider
调整主题。
默认情况下所有组件均为亮色主题,无需任何配置。
将 n-config-provider
的 theme
设为从 naive-ui 导入的 darkTheme
来设定暗色主题。
若 theme
为 undefined
则不会影响内部组件的主题。
- <template>
- <n-config-provider :theme="darkTheme">
- <app />
- </n-config-provider>
- </template>
-
- <script>
- import { defineComponent } from 'vue'
- import { darkTheme } from 'naive-ui'
-
- export default defineComponent({
- setup() {
- return {
- darkTheme
- }
- }
- })
- </script>
你不需要写任何 CSS(Scss、Less...)。
配置的全局主题变量会对后代组件生效的主题变量覆盖。
通过设定 n-config-provider
的 theme-overrides
来调整主题变量。naive-ui 导出了 GlobalThemeOverrides
类型帮助你定义主题。
具体可使用变量请参考 GlobalThemeOverrides
类型提示。
如果想要查看更多的主题变量,可在 Naive UI 主页的右下角的 edit 按钮查看。
可以修改对应的主题变量,导出后可以拿到 themeOverrides 对象。
- <script>
- import { NConfigProvider } from 'naive-ui'
-
- /**
- * js 文件下使用这个做类型提示
- * @type import('naive-ui').GlobalThemeOverrides
- */
- const themeOverrides = {
- common: {
- primaryColor: '#FF0000'
- },
- Button: {
- textColor: '#FF0000'
- },
- Select: {
- peers: {
- InternalSelection: {
- textColor: '#FF0000'
- }
- }
- }
- // ...
- }
-
- // ...
- </script>
-
- <template>
- <n-config-provider :theme-overrides="themeOverrides">
- <my-app />
- </n-config-provider>
- </template>
- <template>
- <n-input
- v-model:value="formInline.password"
- type="password"
- @keyup.enter="handleSubmit"
- maxlength="16"
- show-password-on="click"
- :placeholder="$t('global.form_password')"
- :theme-overrides="InputThemeOverrides">
- </n-input>
- <n-checkbox v-model:checked="autoLogin" :theme-overrides="CheckboxThemeOverrides">复选框</n-checkbox>
- <n-button
- type="primary"
- @click="handleSubmit"
- size="large"
- :loading="loading"
- block
- class="button-text"
- :theme-overrides="buttonThemeOverrides">按钮</n-button>
- </template>
-
-
- <script lang='ts' setup>
- import { InputProps, CheckboxProps, ButtonProps } from 'naive-ui'
-
- type InputThemeOverrides = NonNullable<InputProps['themeOverrides']>
- type CheckboxThemeOverrides = NonNullable<CheckboxProps['themeOverrides']>
- type ButtonThemeOverrides = NonNullable<ButtonProps['themeOverrides']>
-
- const InputThemeOverrides: InputThemeOverrides = {
- textColor: 'rgb(51, 54, 57)',
- color: 'rgba(255, 255, 255, 1)',
- colorFocus: 'rgba(255, 255, 255, 1)',
- iconColor: 'rgba(194, 194, 194, 1)'
- }
-
- const CheckboxThemeOverrides: CheckboxThemeOverrides = {
- checkMarkColor: '#FFF'
- }
- const buttonThemeOverrides: ButtonThemeOverrides = {
- textColorPrimary: 'rgba(255, 255, 255, 1)',
- textColorHoverPrimary: 'rgba(255, 255, 255, 1)'
- }
- </script>
如果你正在使用 ts 写代码,这块比较适合你。
- <script lang="ts">
- import { NConfigProvider, GlobalThemeOverrides } from 'naive-ui'
-
- const themeOverrides: GlobalThemeOverrides = {
- common: {
- primaryColor: '#FF0000'
- },
- Button: {
- textColor: '#FF0000'
- }
- }
-
- // ...
- </script>
-
- <template>
- <n-config-provider :theme-overrides="themeOverrides">
- <my-app />
- </n-config-provider>
- </template>
组件主题变量使用方法同全局主题变量使用方法,并且组件主题变量会覆盖全局主题变量。
- <script lang="ts">
- import { SelectProps, ButtonProps } from 'naive-ui'
-
- type SelectThemeOverrides = NonNullable<SelectProps['themeOverrides']>
- type ButtonThemeOverrides = NonNullable<ButtonProps['themeOverrides']>
-
- const selectThemeOverrides: SelectThemeOverrides = {
- menuBoxShadow:
- '0 6px 16px -9px rgba(0, 0, 0, .08), 0 9px 28px 0 rgba(0, 0, 0, .05), 0 12px 48px 16px rgba(0, 0, 0, .03)',
- peers: {
- InternalSelection: {
- textColor: '#FF0000',
- heightMedium: '42px'
- }
- }
- }
- const buttonThemeOverrides: ButtonThemeOverrides = {
- heightMedium: '40px',
- textColor: 'rgba(24, 127, 231, 1)'
- }
-
- // ...
- </script>
-
- <template>
- <n-select
- v-model:value="value"
- :options="options"
- :theme-overrides="selectThemeOverrides"
- />
- <n-button :theme-overrides="buttonThemeOverrides">theme</n-button>
- </template>
如果你想要在亮色和暗色上同时使用不同的主题变量,可以来看看这个。
- <script>
- import { NConfigProvider, darkTheme } from 'naive-ui'
-
- /**
- * @type import('naive-ui').GlobalThemeOverrides
- */
- const lightThemeOverrides = {
- common: {
- primaryColor: '#000000'
- }
- // ...
- }
-
- const darkThemeOverrides = {
- common: {
- primaryColor: '#FFFFFF'
- }
- // ...
- }
-
- const theme = null
- // ...
- </script>
-
- <template>
- <n-config-provider
- :theme="theme"
- :theme-overrides="theme === null ? lightThemeOverrides : darkThemeOverrides"
- >
- <my-app />
- </n-config-provider>
- </template>
很多时候组件内部都会复用另一个组件,因此出现了 peers 的主题变量。
peers 相关的主题变量还没有暴露,使用 GlobalThemeOverrides
可以查看对应组件的 peers 变量。
具体哪些可使用的 peers 后续会更新。
- <script lang="ts">
- import { NConfigProvider, GlobalThemeOverrides } from 'naive-ui'
-
- const themeOverrides: GlobalThemeOverrides = {
- Select: {
- peers: {
- InternalSelection: {
- textColor: '#FF0000'
- },
- InternalSelectMenu: {
- borderRadius: '6px'
- }
- }
- },
- DataTable: {
- paginationMargin: '40px 0 0 0',
- peers: {
- Empty: {
- textColor: '#ccc'
- },
- Pagination: {
- itemTextColor: '#ccc'
- }
- }
- }
- // ...
- }
- // ...
- </script>
-
- <template>
- <n-config-provider :theme-overrides="themeOverrides">
- <my-app />
- </n-config-provider>
- </template>
出于以下原因,你可能需要将某些样式设定在 document.body
上。
n-config-provider
无法将全局样式同步到它以外的地方(例如 body 背景色)。通过使用 n-global-style
可以将常见的全局样式同步到 body 上。在下面的例子中,n-global-style
会将 n-config-provider
提供的主题同步到 document.body
上。
- <template>
- <n-config-provider>
- <app />
- <n-global-style />
- </n-config-provider>
- </template>
naive-ui 提供主题编辑器帮助你方便的编辑主题并导出对应配置。它可以被嵌套于 n-config-provider
中。
主题编辑器不包含在全局安装中(app.use(naive)
)。你需要显式引入来使用它。
- <template>
- <n-theme-editor>
- <app />
- </n-theme-editor>
- </template>
-
- <script>
- import { defineComponent } from 'vue'
- import { NThemeEditor } from 'naive-ui'
-
- export default defineComponent({
- components: {
- NThemeEditor
- }
- })
- </script>
了解更多关于 n-config-provider
的信息,参见 全局化配置。
全局化配置设置内部组件的主题、语言和组件卸载于其他位置的 DOM 的类名。
n-config-provider
内部组件的主题。- <template>
- <n-config-provider :theme="theme">
- <n-card>
- <n-space>
- <n-button @click="theme = darkTheme">
- 深色
- </n-button>
- <n-button @click="theme = null">
- 浅色
- </n-button>
- </n-space>
- </n-card>
- </n-config-provider>
- </template>
-
- <script lang="ts">
- import { defineComponent, ref } from 'vue'
- import { darkTheme } from 'naive-ui'
- import type { GlobalTheme } from 'naive-ui'
-
- export default defineComponent({
- setup () {
- return {
- darkTheme,
- theme: ref<GlobalTheme | null>(null)
- }
- }
- })
- </script>
名称 | 类型 | 默认值 | 说明 | 版本 |
---|---|---|---|---|
abstract | boolean | false | 是否不存在 DOM 包裹 | |
breakpoints | { [k: string]: number } | { xs: 0, s: 640, m: 1024, l: 1280, xl: 1536, xxl: 1920 } | 屏幕响应式断点,对 n-grid 生效。这个属性不是响应式的,你需要在组件第一次挂载时就设定好 | |
cls-prefix | string | n | 内部所有组件的类的前缀,仅首次设定会生效 | |
date-locale | DateLocale | null | undefined | 对后代组件生效的日期语言对象,为 null 时会使用默认 dateEnUS ,为 undefined 时会继承上级 n-config-provider | |
inline-theme-disabled | boolean | false | 是否禁用 inline css 主题变量,如果你不会频繁调整主题变量,并且需要 SSR 或者想让 devtools 看起来更干净,可以打开这个选项。注意,这个属性不是响应式的 | 2.26.0 |
katex | object | undefined | 公式组件需要的 katex 对象 | 2.34.0 |
locale | Locale | null | undefined | 对后代组件生效的语言对象,为 null 时会使用默认 enUS ,为 undefined 时会继承上级 n-config-provider | |
namespace | string | undefined | n-config-provider 内部组件被卸载于其他位置的 DOM 的类名 | |
preflight-style-disabled | boolean | false | 是否禁用默认样式,如果你禁用了它,便可以完全控制全局样式。你也可以使用 n-global-style 去挂载全局样式(推荐,样式是响应式的) | 2.29.0 |
tag | string | 'div' | n-config-provider 被渲染成的元素 | |
theme | Theme | null | undefined | 对后代组件生效的主题对象,为 null 时会使用默认亮色,为 undefined 时会继承上级 n-config-provider 。更多信息参见调整主题 | |
theme-overrides | ThemeOverrides | null | undefined | 对后代组件生效的主题变量覆盖,为 null 时会清除全部覆盖变量,为 undefined 时会继承上级 n-config-provider 。更多信息参见调整主题 |
不支持 IE 浏览器。
Edge
、Firefox
、Chrome
、Safari
等现代浏览器的最新的 2 个版本确保会被支持。
对于这些浏览器的其他版本中,由于开发资源的限制并没有做过严格的测试。但是我们预期 naive-ui 应该在这些浏览器不算太老的版本上能正常的运行(比如 2 年之内的版本)。如果你发现了任何问题欢迎来提 issue。
只支持 Vue 3(>3.0.5)。
需要版本 > 4.1。
Copyright © 2003-2013 www.wpsshop.cn 版权所有,并保留所有权利。