配置字体
- Naive UI 可以和 vfonts 配合，你可以简单的引入 vfonts 中的字体，包含常规字体和等宽字体。
- 只需要在你 App 的入口文件导入字体，即可调整 Naive UI 的字体。
- 注意：不同 vfonts 字体提供的字重不同，在使用 Lato、OpenSans 的时候你需要全局调整 naive-ui 的字重配置。
<!-- 调整 naive-ui 的字重配置 -->
<n-config-provider :theme-overrides="{ common: { fontWeightStrong: '600' } }">
<app />
</n-config-provider>
- 如果你不打算使用 vfonts 并且想要通过主题调整修改其为别的字体，你需要使用 n-global-style 来做到这一点。在不使用 n-global-style 的情况下组件不会响应 theme-overrides 中的字体变更。
- 题外话：不使用 n-global-style 就能让 vfonts 直接生效是一个设计上的妥协，在下个大的版本默认的全局 reset 样式将不再带有字体相关的样式，而是全部置于 n-global-style 组件中。
全局样式 Global Style
- 出于以下原因，你可能需要将某些样式设定在 document.body 上。
- naive-ui 会设定一些非响应式的全局样式（例如字体），它们在默认状况下工作良好，但是不能响应主题的变化。
- n-config-provider 无法将全局样式同步到它以外的地方（例如 body 背景色）。
- 通过使用 n-global-style 可以将常见的全局样式同步到 body 上。在下面的例子中，n-global-style 会将 n-config-provider 提供的主题同步到 document.body 上。
<n-config-provider>
<n-global-style />
...
</n-config-provider>
按需引入（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>
- 可以使用 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)
常见问题
- 在 Naive UI 中，全部的 API 文档使用 on-update:xxx 格式，因为 @ 只是 Vue 提供的一种简写。
- 如果你偏爱 camelCase，可以使用 onUpdate:xxx。
- 如果你在使用 JSX，可以使用 onUpdateXxx（所有的 onUpdate:xxx 都有一个 onUpdateXxx 的对等实现）。
- 如果你在一个组件上使用了 v-model:xxx，你应该使用 @update:xxx。
- 这是因为 v-model:value="xxx" 会被转化为 :onUpdate:value="xxx"。如果你同时使用了 @update:value="yyy"，他们会被转化为 :onUpdate:value="[xxx, yyy]"，然后 Naive UI 会来处理这种情况。
- 然而如果你使用了 on-update:value="yyy"，Vue 会生成类似于 :onUpdate:value="xxx" :on-update:value="yyy" 的代码，然后第二个属性会在运行时覆盖掉第一个，v-model:value 会崩掉。
受控模式与非受控模式
- 在 naive-ui 中，只要 value 是 undefined 或者根本没有传，那么组件的值会是非受控的。也就是说你将一个组件的值设为 undefined 并不能清空它，只会改变它的控制模式。一般情况下清空可以使用 null。
- 任何 xxx 与 @update:xxx 的属性对都可以有受控和非受控模式。
服务端渲染（略）
- naive-ui 在使用 CSS in JS
- 默认情况下，naive-ui 会在组件上绑定 inline 主题样式，这可能会影响 SSR 的尺寸。你可以使用 n-config-provider 的 inline-theme-disabled 属性来优化
调整主题
- 使用暗色主题
- 将 n-config-provider 的 theme 设为从 naive-ui 导入的 darkTheme 来设定暗色主题
- naive-ui 导出了 GlobalThemeOverrides 类型帮助你定义主题。
- 如果想要查看更多的主题变量，可在 Naive UI 主页的右下角的 edit 按钮查看。
- 可以修改对应的主题变量，导出后可以拿到 themeOverrides 对象。
- 很多时候组件内部都会复用另一个组件，因此出现了 peers 的主题变量。
- naive-ui 提供主题编辑器帮助你方便的编辑主题并导出对应配置。它可以被嵌套于 n-config-provider 中。
<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 调整语言，默认情况下所有组件均为英语。
- 将 n-config-provider 的 locale 设为从 naive-ui 导入的 zhCN 来设定全局中文。
- 将 n-config-provider 的 date-locale 设为从 naive-ui 导入的 dateZhCN 来设定全局日期中文。
<template>
<n-config-provider :locale="zhCN" :date-locale="dateZhCN">
<app />
</n-config-provider>
</template>
<script>
import { defineComponent } from 'vue'
import { NConfigProvider } from 'naive-ui'
import { zhCN, dateZhCN } from 'naive-ui'
export default defineComponent({
components: {
NConfigProvider
},
setup() {
return {
zhCN,
dateZhCN
}
}
})
</script>
- 以使用 createLocale 在现有国际化基础上调整。
<template>
<n-config-provider :locale="locale" :date-locale="dateZhCN">
<app />
</n-config-provider>
</template>
<script>
import { defineComponent } from 'vue'
import { NConfigProvider, createLocale, zhCN } from 'naive-ui'
import { zhCN, dateZhCN } from 'naive-ui'
const customizedLocale = createLocale(
{
Input: {
placeholder: '不提申请不构成加班'
}
},
zhCN
)
export default defineComponent({
components: {
NConfigProvider
},
setup() {
return {
locale: customizedLocale,
dateZhCN
}
}
})
</script>
