Naive UI 2.38.1

https://www.naiveui.com/zh-CN/os-theme/docs/i18n

配置字体

• 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>