# Naive UI 完全指南

**Repository Path**: adminfern/naive-ui--the-ultimate-guide

## Basic Information

- **Project Name**: Naive UI 完全指南
- **Description**: **适合人群：** 本书专为零基础前端新手打造，只要你会一点点 HTML/CSS/JavaScript，就能跟着一步步学会 Naive UI。
**版本：** v3.0（企业实战扩展版 · 含天气查询完整项目）
**适用 Naive UI 版本：** 2.x（Vue 3 + TypeScript）
**阅读建议：** 按篇章顺序阅读，每章末尾的「本章踩坑小结」和「本章回顾」一定要看！
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Naive UI 完全指南——从零基础到企业级实战

> **适合人群：** 本书专为零基础前端新手打造，只要你会一点点 HTML/CSS/JavaScript，就能跟着一步步学会 Naive UI。
> **版本：** v3.0（企业实战扩展版 · 含天气查询完整项目）
> **适用 Naive UI 版本：** 2.x（Vue 3 + TypeScript）
> **阅读建议：** 按篇章顺序阅读，每章末尾的「本章踩坑小结」和「本章回顾」一定要看！

---

# 第一篇章 基础认知与环境搭建（零基础入门）

> **🎯 本篇你将学会：**
> - 理解什么是 UI 组件库，Naive UI 相比 Element Plus 有什么独特优势
> - 从零搭建一个 Vue 3 + Naive UI 的开发环境
> - 掌握三种引入方式的区别和适用场景
> - 配置全局主题、语言和组件尺寸
> - 使用图标系统和字体

## 第1章 走进 Naive UI

> **📖 学习目标：** 理解什么是 UI 组件库、Naive UI 跟别的组件库有什么不同、什么场景适合用它。

### 1.1 先说人话：什么是"UI 组件库"？

如果你是新手，听到"UI 组件库"这个词可能会觉得很高大上。其实用大白话讲就是：

> 一堆**已经写好了样式的界面"积木"**，你只需要拿过来拼一拼，就能快速搭出一个好看的后台管理系统。

举个例子：你想在网页上加一个按钮。如果手写，你需要写 HTML、写 CSS 样式、处理点击效果、处理禁用状态……但用了 Naive UI，你只需要：

```vue
<n-button type="primary">点我一下</n-button>
```

就这么一行，一个漂亮的蓝色按钮就出来了，自带悬浮效果、点击动画、禁用状态，什么样式都不用你管。

> 💡 **新手理解：** 组件 = 一块可复用的"积木"。按钮是一个组件，输入框是一个组件，弹窗也是一个组件。把这些组件拼起来，就是一个完整的页面。

### 1.2 Naive UI 是什么？为什么选它？

**Naive UI** 是目前国内非常流行的一个 Vue 3 组件库。"Naive"这个名字不是"幼稚"的意思，作者的原意是"朴素、纯粹"——用最少的心智负担，写出最好的界面。

> 🔥 **凭什么选它而不是 Element Plus？**
>
> | 你关心的点 | Naive UI | Element Plus |
> |-----------|----------|-------------|
> | 主题定制（公司要求换品牌色） | ⭐⭐⭐⭐⭐ 非常灵活 | ⭐⭐⭐ 一般 |
> | 暗黑模式（需要一键切换） | ✅ **内置支持**，一行代码搞定 | ❌ 需要自己配 |
> | TypeScript 提示（代码补全舒不舒服） | ⭐⭐⭐⭐⭐ 行业天花板 | ⭐⭐⭐⭐ 不错 |
> | 组件数量（功能够不够用） | 90+ 个 | 70+ 个 |
> | 学习难度（新手好不好上手） | 平缓 | 平缓 |

> ⚠️ **新手提醒：** Naive UI **只支持 Vue 3**。如果你还在学 Vue 2（老教程），那 Naive UI 用不了。现在学 Vue 就从 Vue 3 开始，别学 Vue 2 了，那是过去的版本。

### 1.3 哪些项目适合用 Naive UI？

- 📊 **后台管理系统**（最常见的场景）——公司内部的员工管理、订单管理、数据报表
- 📈 **数据分析平台**——Naive UI 的表格组件性能很强，支持 10 万行数据不卡顿
- 🏢 **SaaS 系统**——租户管理、权限配置、账单系统
- 🎨 **需要定制品牌色的项目**——主题系统是 Naive UI 的核心卖点
- 🔧 **企业内部工具**——快速搭建，上线即用
- 🌤️ **内容展示型网站**（博客、天气查询工具等）——本书第42-44章的天气项目就是最好的例子

### 1.4 Naive UI 的"家族成员"

```bash
# 你需要装的几个包（别慌，后面会手把手教你装）：
naive-ui          → 核心组件库（按钮、表格、弹窗……）
@vicons/ionicons5 → 图标包（600+ 个图标随便用）
vfonts            → 官方推荐字体（让页面更好看）
```

> 💡 **打个比方：** `naive-ui` 是乐高积木的主体零件包，`@vicons/ionicons5` 是装饰零件包，`vfonts` 是贴纸。三个配合使用才完整。

> 📝 **本章回顾：** Naive UI 是一个基于 Vue 3 的现代化组件库，最大的优势是主题定制灵活、暗黑模式内置、TypeScript 支持极好。适合中后台管理系统、数据分析平台等各种企业级应用。

---

## 第2章 开发环境搭建与项目初始化

> **📖 学习目标：** 从零开始创建一个 Vue 3 + TypeScript 项目，安装 Naive UI，并且在浏览器中看到第一个组件。

### 2.1 你需要先装好这些东西

| 工具 | 需要什么版本 | 怎么检查有没有装 | 去哪里下载 |
|------|-------------|----------------|-----------|
| **Node.js** | >= 16.x（推荐 18.x） | 打开终端输入 `node -v` | https://nodejs.org（选 LTS） |
| **npm** 或 **pnpm** | npm 随 Node 自带，pnpm 推荐单独装 | `npm -v` 或 `pnpm -v` | `npm i -g pnpm` |
| **VSCode** | 最新版 | 打开看一眼 | https://code.visualstudio.com |

> ⚠️ **新手最常踩的坑：** Node.js 版本太低！
> 很多新手电脑上可能装过很老的 Node.js（比如 12.x 或 14.x）。**Naive UI + Vite 5 要求 Node.js >= 16**。如果你不确定版本，先在终端执行 `node -v` 检查一下。如果不是 16 以上，去 Node.js 官网下载 LTS 版覆盖安装。

> 💡 **为什么推荐 pnpm？** 因为它比 npm 快很多（硬盘空间占用少），而且是 Vue 官方推荐的包管理器。如果你不想折腾，用 npm 也可以，只是安装依赖会慢一点。

### 2.2 创建项目（跟着敲，别跳步）

打开终端（Windows 用户推荐用 **PowerShell** 或 VSCode 自带的终端），执行：

```bash
# 第1步：用 Vite 创建 Vue 3 项目
# 这条命令会下载一个脚手架模板，帮你搭好基础目录结构
pnpm create vue@latest my-admin-app
```

执行后终端会问你好几个问题。**新手建议全部选 Yes**（除了 Testing 那几项可以选 No）：

```bash
✔ Project name: … my-admin-app          # 项目名，直接回车就行
✔ TypeScript? … Yes                     # 选 Yes！（Naive UI 的 TypeScript 支持是亮点）
✔ JSX Support? … No                     # 新手暂时用不到，选 No
✔ Vue Router? … Yes                     # 路由：页面跳转必备，选 Yes
✔ Pinia? … Yes                          # 状态管理：以后会用到，选 Yes
✔ Vitest? … No                          # 测试工具：新手暂时不用，选 No
✔ ESLint? … Yes                         # 代码检查：帮你发现低级错误，选 Yes
✔ Prettier? … Yes                       # 代码格式化：让代码更好看，选 Yes
```

> 💡 **Vite 是什么？** 你可以把它理解成一个"开发服务器"，它比老旧的 Webpack 快很多——改一行代码，浏览器几乎瞬间就能看到效果。Vue 官方现在强力推荐用 Vite 创建项目。

```bash
# 第2步：进入项目目录
cd my-admin-app

# 第3步：安装项目的基础依赖
# 这一步会下载 Vue、Vue Router、Pinia 等基础库
pnpm install
```

### 2.3 安装 Naive UI 和它的朋友们

```bash
# 安装核心库（所有组件都在里面）
pnpm add naive-ui

# 安装图标库（按钮上的小图标全靠它）
# IonIcons 5 是官方最推荐的图标集，样式最统一
pnpm add @vicons/ionicons5

# 安装推荐字体（让中英文混排更好看）
pnpm add vfonts
```

> ⚠️ **注意：** 有些新手教程会让你用 `npm install`，效果是一样的。选你喜欢的就行。如果下载慢，可以配一下淘宝镜像：
> ```bash
> npm config set registry https://registry.npmmirror.com
> ```

### 2.4 验证一下：写出第一个 Naive UI 页面

先把 `src/App.vue` 的**全部内容替换**成下面这段代码：

```vue
<!-- src/App.vue -->
<script setup lang="ts">
// 第1步：导入需要用的组件
// 就像去超市买东西，你需要什么就拿什么
import { NButton, NSpace, NTag } from 'naive-ui'
import { ref } from 'vue'

const message = ref('Naive UI 安装成功！🎉')

// 按钮点击后的处理函数
function handleClick() {
  alert('你点击了按钮！Naive UI 正常工作～')
}
</script>

<template>
  <!--
    模板区域：写 HTML 的地方
    所有 Naive UI 的组件都以 <n- 开头，这是固定的命名规则
    比如按钮是 <n-button，标签是 <n-tag
  -->
  <n-space vertical>
    <!-- n-space 是一个"间距容器"，让里面的东西不要挤在一起 -->
    <n-tag type="success" size="large">
      {{ message }}
      <!-- {{ }} 双花括号是 Vue 的模板语法，用来显示变量 -->
    </n-tag>

    <n-button type="primary" size="large" @click="handleClick">
      点我试试
    </n-button>
  </n-space>
</template>
```

保存文件后，启动开发服务器：

```bash
# 在项目目录下执行
pnpm dev

# 终端会显示类似：http://localhost:5173/
# 用浏览器打开这个地址
```

> 💡 如果浏览器里看到了一个绿色标签和一个蓝色按钮，**恭喜你！** Naive UI 已经成功装好了。如果没看到，跳到第 38 章看看有没有对应的解决方案。

### 2.5 VSCode 配置（让编辑器更好用）

在项目根目录创建 `.vscode/settings.json`：

```json
{
  // 保存文件时自动格式化代码，不用手动调整缩进
  "editor.formatOnSave": true,
  // Vue 文件的代码片段优先用 kebab-case（也就是 n-button 而不是 NButton）
  "volar.completion.preferredTagNameCase": "kebab",
  "volar.completion.preferredAttrNameCase": "kebab"
}
```

> 💡 **为什么要加这些配置？** `volar` 是 Vue 3 的官方 VSCode 插件（以前叫 Vetur，现在改名了）。装了它之后，你在模板里输入 `<n-` 就会自动弹出所有可用组件的提示。在 VSCode 插件商店搜 "Vue - Official" 安装即可。

> 📝 **本章回顾：** 创建 Vue 3 项目 → 安装 naive-ui / @vicons/ionicons5 / vfonts → 写第一个测试页面 → 启动 dev server 看到效果。注意 Node.js >= 16，推荐用 pnpm。

---

## 第3章 Naive UI 三种引入方式深度解析

> **📖 学习目标：** 搞清楚"全量引入""自动按需""手动按需"的区别，知道项目里该用哪一种。

> 💡 **先理解一个概念：打包体积。** 你写的代码最终会被"打包"成浏览器能运行的文件。如果你把整个 Naive UI 都打包进去（包括你不用的组件），那用户打开网页就要下载一个很大的文件——网页打开就会变慢。**按需引入**的意思就是：你用哪个组件，就只打包哪个，没用到的统统不打包。

### 3.1 方式一：完整引入（新手练手推荐，但正式项目不要用）

```ts
// src/main.ts
import { createApp } from 'vue'
// 把整个 Naive UI 一次性全部导入
import naiveUI from 'naive-ui'
import App from './App.vue'

const app = createApp(App)
// 把 Naive UI 全部注册到 Vue 中
app.use(naiveUI)
app.mount('#app')
```

> ✅ **优点：** 最简单，写模板直接写组件名，不用 import。
> ❌ **缺点：** 打包体积最大，用户打开网页要多下载约 200KB 的代码。
> 📌 **建议：** 只在你"随便玩玩"或者"写一个 demo 给同事看"的时候用这种方式。正式上线项目**不要用**。

### 3.2 方式二：自动按需引入（最省事，中小项目推荐）

这种方式借助两个 Vite 插件，让你**在模板里直接写 `<n-button>`，插件自动帮你把 NButton 组件导入进来**，同时保证只打包你用到的组件。

**第1步：安装插件**

```bash
pnpm add -D unplugin-auto-import unplugin-vue-components
# -D 的意思是装在开发依赖里（devDependencies），最终上线不会打包进去
```

**第2步：配置 `vite.config.ts`**

```ts
// 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'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      imports: ['vue', 'vue-router', 'pinia'],
      dts: 'src/auto-imports.d.ts'
    }),
    Components({
      resolvers: [NaiveUiResolver()],
      dts: 'src/components.d.ts'
    })
  ]
})
```

> ⚠️ **新手最容易忘的事：改完 `vite.config.ts` 后要重启开发服务器！**
> Vite 配置文件改了之后不会热更新，你需要 `Ctrl+C` 停掉服务器，再重新 `pnpm dev`。

**第3步：直接在模板中使用——不用 import！**

```vue
<template>
  <n-button type="primary">自动按需引入</n-button>
  <n-input placeholder="输入点什么吧..." />
</template>
```

### 3.3 方式三：手动按需引入（大项目推荐，代码依赖最清晰）

这是**本书首推**的方式。每用到一个组件，就在 `<script setup>` 里手动 import。虽然多写了几行代码，但依赖关系一清二楚。

```vue
<script setup lang="ts">
import { NButton, NInput, NDataTable } from 'naive-ui'
import type { InputInst, DataTableColumns } from 'naive-ui'
import { ref } from 'vue'

const inputRef = ref<InputInst | null>(null)

interface User {
  id: number
  name: string
  age: number
}

const columns: DataTableColumns<User> = [
  { title: 'ID', key: 'id', width: 80 },
  { title: '姓名', key: 'name', width: 120 },
  { title: '年龄', key: 'age', width: 80 }
]

const data: User[] = [
  { id: 1, name: '张三', age: 28 },
  { id: 2, name: '李四', age: 32 }
]

function focusInput() {
  inputRef.value?.focus()
}
</script>

<template>
  <n-input ref="inputRef" placeholder="试试调用 focusInput" />
  <n-button @click="focusInput">聚焦到输入框</n-button>
  <n-data-table :columns="columns" :data="data" />
</template>
```

### 3.4 三种方式对比（一图胜千言）

| 引入方式 | 上手难度 | 打包体积 | 代码清晰度 | 适合什么场景 |
|---------|---------|---------|----------|------------|
| **全量引入** | ⭐ 最简单 | ❌ 最大 | 一般 | 快速原型、Demo |
| **自动按需** | ⭐⭐ 中等 | ✅ 最小 | 较好 | 中小型正式项目 |
| **手动按需** | ⭐⭐⭐ 多写几行 import | ✅ 最小 | ✅ 最清晰 | 中大型企业项目 |

> 📌 **本书建议：** 学习阶段用全量引入（省事），公司项目用手动按需（清晰）。

> ⚠️ **本章踩坑小结：**
> 1. 自动按需改了 `vite.config.ts` 一定要**重启 dev server**！
> 2. 手动按需时，别忘了还要 import 对应的 **类型**（`InputInst` 等），否则 TypeScript 会报类型错误。
> 3. 不管哪种方式，**`<script setup lang="ts">`** 这行的 `lang="ts"` 不要漏，否则 TypeScript 不生效！
> 4. 如果你发现模板里 `<n-button>` 报错 "Failed to resolve component"，检查一下：你有没有 import？有没有在 `app.use()` 里注册？

> 📝 **本章回顾：** 三种引入方式各有适用场景。全量引入最快但体积大，自动按需最省心，手动按需最清晰。本书建议正式项目用手动按需。

---

## 第4章 全局核心配置与基础规范

> **📖 学习目标：** 理解 NConfigProvider 是干什么的，学会设置全局语言、主题色、组件尺寸。

### 4.1 NConfigProvider——所有组件的"总开关"

> 💡 **打个比方：** 把 NConfigProvider 想象成你家门口的水阀总开关。你调一次水温（主题色），全屋水龙头（所有组件）的水温都变了。你不需要一个一个去调。

`n-config-provider` 包裹住整个应用后，它把"主题、语言、组件默认尺寸"统一管理起来，**所有被它包住的组件都会自动继承这些配置**。

```vue
<!-- src/App.vue —— 最基础但完整的全局配置 -->
<script setup lang="ts">
import { NConfigProvider, zhCN, dateZhCN } from 'naive-ui'
</script>

<template>
  <!--
    n-config-provider 是所有 Naive UI 组件的"老大"
    它不渲染任何可见的界面，只负责给子组件传递配置信息
  -->
  <n-config-provider
    :locale="zhCN"
    :date-locale="dateZhCN"
  >
    <router-view />
  </n-config-provider>
</template>
```

> ⚠️ **重要理解：** NConfigProvider 本身不会在当前页面产生任何可见的 DOM 元素（如果你看到多了一层 div，可以加上 `abstract` 属性消除）。它只是提供一个"配置上下文"。

### 4.2 全局换肤：改一次，所有地方都变

```vue
<script setup lang="ts">
import { NConfigProvider, NButton, NCard, zhCN } from 'naive-ui'
import type { GlobalThemeOverrides } from 'naive-ui'

const themeOverrides: GlobalThemeOverrides = {
  // ===== Common（公共变量）=====
  common: {
    primaryColor: '#18A058',
    primaryColorHover: '#36AD6A',
    primaryColorPressed: '#0C7A43',
    borderRadius: '6px',
    fontSize: '14px',
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif'
  },
  Button: {
    borderRadius: '6px',
    heightMedium: '36px'
  },
  Card: {
    paddingMedium: '24px',
    borderRadius: '8px',
    borderColor: '#EBEBEB'
  }
}
</script>

<template>
  <n-config-provider :locale="zhCN" :theme-overrides="themeOverrides">
    <n-button type="primary">绿色按钮</n-button>
    <n-card title="自定义圆角卡片">这个卡片使用了 8px 的圆角</n-card>
  </n-config-provider>
</template>
```

> 💡 **技巧：怎么找到某个组件有哪些变量可以改？**
> 在 VSCode 中，把光标放到 `themeOverrides` 的类型 `GlobalThemeOverrides` 上，按 `F12`（转到定义），就能看到所有组件的变量列表。或者参考本书**附录B**。

### 4.3 切换语言：一行代码国际化

```vue
<script setup lang="ts">
import { ref, computed } from 'vue'
import {
  NConfigProvider, NSwitch, NButton, NDatePicker,
  zhCN, dateZhCN, enUS, dateEnUS
} from 'naive-ui'

const isChinese = ref(true)
const locale = computed(() => isChinese.value ? zhCN : enUS)
const dateLocale = computed(() => isChinese.value ? dateZhCN : dateEnUS)
</script>

<template>
  <n-config-provider :locale="locale" :date-locale="dateLocale">
    <n-switch v-model:value="isChinese">
      <template #checked>中文</template>
      <template #unchecked>English</template>
    </n-switch>
    <n-button>确认</n-button>
    <n-date-picker />
  </n-config-provider>
</template>
```

### 4.4 全局组件尺寸：一次设置，所有组件统一大小

```vue
<template>
  <n-config-provider :size="'medium'">
    <n-input placeholder="默认 medium 尺寸" />
    <n-button>默认 medium 按钮</n-button>
    <n-button size="large">单独设为 large</n-button>
  </n-config-provider>
</template>
```

> ⚠️ **本章踩坑小结：**
> 1. **NConfigProvider 一定要包在最外层**，否则里面的组件拿不到主题配置。
> 2. 改了 `theme-overrides` 后发现**某些属性不生效**？——检查 CSS 变量名有没有拼写错误（附录B查）。
> 3. 多个 NConfigProvider **嵌套**时，里层的会覆盖外层的——这是个特性不是 bug，但新手容易搞晕。

> 📝 **本章回顾：** NConfigProvider 是 Naive UI 所有组件接收主题/语言/尺寸配置的唯一通道。主题定制通过 `theme-overrides` 对象实现，支持 common（全局）和组件级（Button、Card 等）两种粒度。

---

## 第5章 图标系统与字体全局配置

> **📖 学习目标：** 学会在按钮、菜单里加图标，理解 Naive UI 图标的工作方式，配置中英文字体。

### 5.1 图标怎么用？先装后导

Naive UI 的图标是**独立**的包，不会随组件库自动安装。你需要单独装一个图标库。

```bash
# 三选一，推荐第一个（IonIcons 5，风格最统一）
pnpm add @vicons/ionicons5    # IonIcons（iOS 风格，推荐）
pnpm add @vicons/fa           # Font Awesome（Web 经典风格）
pnpm add @vicons/material     # Material Design（Google 风格）
```

> 💡 **为什么图标要单独装？** 因为不同项目可能喜欢不同风格的图标，Naive UI 不希望替你做选择。你自己决定用哪个，然后只装你需要的——这样打包体积更小。

### 5.2 n-icon：图标的"容器"

Naive UI 用 `n-icon` 组件包裹图标，统一控制尺寸、颜色、深度。

```vue
<script setup lang="ts">
import { NIcon } from 'naive-ui'
import {
  RocketOutline, SunnyOutline, MoonOutline,
  SettingsOutline, LockClosedOutline
} from '@vicons/ionicons5'
</script>

<template>
  <!-- 基础用法：n-icon 包裹图标组件 -->
  <n-icon size="24"><RocketOutline /></n-icon>

  <!-- 常用属性 -->
  <n-icon :size="32" color="#18A058" :depth="3">
    <SettingsOutline />
  </n-icon>

  <!-- depth 效果演示 -->
  <n-icon :depth="1"><SettingsOutline /></n-icon>  <!-- 最深 -->
  <n-icon :depth="3"><SettingsOutline /></n-icon>
  <n-icon :depth="5"><SettingsOutline /></n-icon>  <!-- 最浅 -->
</template>
```

> 💡 **depth 是什么？** 它是一个快速调节图标颜色的参数。你不必手动调色，只需要给 depth 一个 1-5 的数字。它实际上是基于文字颜色做的透明度计算——depth 越大越透明。

### 5.3 实战：在按钮、菜单中加图标

```vue
<template>
  <n-space>
    <!-- 模式1：图标在文字前面 -->
    <n-button type="primary">
      <template #icon>
        <n-icon><SearchOutline /></n-icon>
      </template>
      搜索
    </n-button>

    <!-- 模式2：纯图标圆形按钮 -->
    <n-button circle>
      <template #icon><n-icon><SettingsOutline /></n-icon></template>
    </n-button>

    <!-- 模式3：带颜色的纯图标按钮 -->
    <n-button circle type="error">
      <template #icon><n-icon><HeartOutline /></n-icon></template>
    </n-button>
  </n-space>
</template>
```

> ⚠️ **新手容易犯的错：** `#icon` 插槽里要放 `<n-icon>`，**不要**直接把图标组件放进去。`<n-icon>` 是图标的容器，统一管理大小和颜色。把图标裸放在 `#icon` 里可能会导致对齐问题。

### 5.4 字体配置（vfonts）

```bash
pnpm add vfonts
```

```ts
// src/main.ts
import 'vfonts/Lato.css'
import 'vfonts/FiraCode.css'
```

```vue
<script setup lang="ts">
import { NConfigProvider } from 'naive-ui'

const themeOverrides = {
  common: {
    fontFamily: 'Lato, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
    fontFamilyMono: 'Fira Code, "SF Mono", Monaco, Inconsolata, monospace'
  }
}
</script>
```

> 💡 **为什么要区分 fontFamily 和 fontFamilyMono？**
> 正文（中文）用"非等宽"字体，每个汉字宽度一样，但英文 i 和 W 宽度不同——这样读起来自然。
> 代码用"等宽"字体，每个字母（包括空格）宽度一模一样——这样代码才能对齐，缩进不会乱。

### 5.5 进阶：自定义 SVG 图标

当图标库里没有你想要的图标时，可以自己写 SVG（也可以从 iconfont.cn 下载）：

```vue
<template>
  <n-icon size="40" color="#18A058">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
      <circle cx="12" cy="12" r="10" />
      <path d="M12 6v6l4 2" />
    </svg>
  </n-icon>
</template>
```

> ⚠️ **本章踩坑小结：**
> 1. 图标库没有默认装！一定要 `pnpm add @vicons/ionicons5`。
> 2. 图标一定要用 `n-icon` 包裹，不要裸放，否则颜色/大小不受控制。
> 3. 如果你发现图标不显示——检查 import 路径是否正确。IonIcons 5 的图标都在 `@vicons/ionicons5` 下导出，名字格式是 `XxxOutline`（空心）、`Xxx`（实心）、`XxxSharp`（尖锐）。

> 📝 **本章回顾：** 图标系统通过 `@vicons/*` 独立包 + `n-icon` 容器实现。推荐 IonIcons 5 图标集。字体用 `vfonts` 包，区分正文和代码两种字体。

---

# 第二篇章 通用基础组件精讲（页面基石）

> **🎯 本篇你将学会：**
> - NButton 的所有类型、尺寸、变体和状态
> - NSpace 间距布局和 NText 文本组件
> - NTag / NBadge / NDivider / NPopover 辅助组件
> - NCard 卡片容器和 NModal 弹窗的两种用法

## 第6章 按钮、间距、文本类基础组件

> **📖 学习目标：** 掌握 NButton 的所有类型和状态，学会用 NSpace 排版，用 NText 显示文字。

### 6.1 NButton——每天点击几十次的按钮

NButton 的属性非常多，但只要记住几个**最常用的组合**就够了。

```vue
<script setup lang="ts">
import { NButton, NSpace, NIcon } from 'naive-ui'
import { SearchOutline } from '@vicons/ionicons5'
import { ref } from 'vue'

const loading = ref(false)
function handleSave() {
  loading.value = true
  setTimeout(() => { loading.value = false }, 2000)
}
</script>

<template>
  <!-- ====== 颜色类型 ====== -->
  <n-space>
    <n-button>default 默认</n-button>
    <n-button type="primary">primary 主要操作</n-button>
    <n-button type="info">info 提示</n-button>
    <n-button type="success">success 成功</n-button>
    <n-button type="warning">warning 警告</n-button>
    <n-button type="error">error 危险</n-button>
  </n-space>

  <!-- ====== 尺寸 ====== -->
  <n-space>
    <n-button size="tiny">超小</n-button>
    <n-button size="small">小</n-button>
    <n-button size="medium">中（默认）</n-button>
    <n-button size="large">大</n-button>
  </n-space>

  <!-- ====== 变体 ====== -->
  <n-space>
    <n-button>默认（实心背景）</n-button>
    <n-button tertiary>tertiary（半透明）</n-button>
    <n-button quaternary>quaternary（几乎透明）</n-button>
    <n-button text>text（纯文字）</n-button>
  </n-space>

  <!-- ====== 状态 ====== -->
  <n-space>
    <n-button :loading="loading" @click="handleSave">
      {{ loading ? '保存中...' : '保存' }}
    </n-button>
    <n-button disabled>禁用状态</n-button>
    <n-button ghost>幽灵按钮</n-button>
    <n-button dashed>虚线按钮</n-button>
    <n-button block>块级按钮（宽度 100%）</n-button>
  </n-space>

  <!-- ====== 分组 ====== -->
  <n-button-group>
    <n-button>左</n-button>
    <n-button>中</n-button>
    <n-button>右</n-button>
  </n-button-group>
</template>
```

> 💡 **什么时候用哪个 type？**
> - `primary`：页面最主要的操作（保存、提交、确认）
> - `error`：危险操作（删除、清空、注销）
> - `success`：正向操作（通过、启用、完成）
> - `warning`：需要谨慎的操作（退回、暂停）
> - `info`：中性提示（详情、帮助）

> ⚠️ **注意：** `loading` 为 `true` 时按钮自动变为不可点击。你不需要额外设置 `disabled`。

### 6.2 NSpace——新手最容易忽视的布局利器

> 💡 NSpace 的作用非常简单：**给一组元素之间自动加间距**。

```vue
<template>
  <!-- 水平排列 -->
  <n-space>
    <n-button>按钮1</n-button>
    <n-button>按钮2</n-button>
    <n-button>按钮3</n-button>
  </n-space>

  <!-- 垂直排列 -->
  <n-space vertical :size="16">
    <n-button block>第一行</n-button>
    <n-button block>第二行</n-button>
  </n-space>

  <!-- 两端对齐 -->
  <n-space justify="space-between" align="center">
    <span>搜索条件区域</span>
    <n-button type="primary">搜索</n-button>
  </n-space>

  <!-- 自动换行 -->
  <n-space wrap :size="8">
    <n-tag v-for="i in 10" :key="i">标签{{ i }}</n-tag>
  </n-space>
</template>
```

### 6.3 NText——不仅仅是文字

```vue
<template>
  <n-space vertical>
    <n-text type="info">信息文字</n-text>
    <n-text type="success">成功文字</n-text>
    <n-text type="warning">警告文字</n-text>
    <n-text type="error">错误文字</n-text>
    <n-text strong>加粗</n-text>
    <n-text italic>斜体</n-text>
    <n-text underline>下划线</n-text>
    <n-text delete>删除线</n-text>
    <n-text code>code 等宽样式</n-text>
    <n-text keyboard>Ctrl + C</n-text>
    <n-text :depth="1">最深</n-text>
    <n-text :depth="3">默认 depth=3</n-text>
  </n-space>
</template>
```

> ⚠️ **本章踩坑小结：**
> 1. NButton 的 `loading` 和 `disabled` 是两个独立属性。loading 时会自动禁用点击，但事件绑定还在。
> 2. NSpace 的间距对**直接子元素**生效。如果你子元素外面又包了一层 div，那 div 才是 NSpace 的子元素。
> 3. `n-button-group` 里的按钮**不要加 `round`**，否则拼接处会断开。

> 📝 **本章回顾：** NButton 有 6 种颜色类型、4 种尺寸、4 种变体，loading 和 disabled 是两个常用状态。NSpace 是一维间距工具，NText 可控制文字的颜色/粗细/修饰。

---

## 第7章 标签、徽标、提示、分割线辅助组件

> **📖 学习目标：** 掌握 NTag（标签）、NBadge（角标）、NDivider（分割线）、NPopover（气泡提示）的使用。

### 7.1 NTag——状态标签首选

```vue
<script setup lang="ts">
import { NTag, NSpace, NIcon } from 'naive-ui'
import { CheckmarkCircleOutline } from '@vicons/ionicons5'
import { ref } from 'vue'

const tags = ref([
  { label: 'Vue 3', type: 'info' as const },
  { label: 'Naive UI', type: 'success' as const },
  { label: 'TypeScript', type: 'warning' as const }
])

function removeTag(index: number) {
  tags.value.splice(index, 1)
}
</script>

<template>
  <n-space>
    <!-- 颜色类型 -->
    <n-tag>默认</n-tag>
    <n-tag type="primary">主要</n-tag>
    <n-tag type="info">信息</n-tag>
    <n-tag type="success">成功</n-tag>
    <n-tag type="warning">警告</n-tag>
    <n-tag type="error">错误</n-tag>
  </n-space>

  <!-- 深色背景模式（bordered=false） -->
  <n-space>
    <n-tag :bordered="false" type="info">待处理</n-tag>
    <n-tag :bordered="false" type="success">已完成</n-tag>
    <n-tag :bordered="false" type="error">已拒绝</n-tag>
  </n-space>

  <!-- 可关闭标签 -->
  <n-space>
    <n-tag
      v-for="(tag, idx) in tags"
      :key="tag.label"
      :type="tag.type"
      closable
      @close="removeTag(idx)"
    >
      {{ tag.label }}
    </n-tag>
  </n-space>

  <!-- 带图标的标签 -->
  <n-tag type="success" round size="large">
    <template #icon>
      <n-icon><CheckmarkCircleOutline /></n-icon>
    </template>
    审核通过
  </n-tag>
</template>
```

> 💡 **`bordered` 参数：** `true`（默认）是浅色底 + 深色文字，适合表格里用。`false` 是深色底 + 白色文字，视觉冲击力强，适合仪表盘。

### 7.2 NBadge——角标/红点

```vue
<template>
  <n-space :size="24">
    <n-badge dot>
      <n-button>消息</n-button>
    </n-badge>
    <n-badge :value="99" :max="99">
      <n-button>通知</n-button>
    </n-badge>
    <n-badge value="NEW" color="#18A058">
      <n-button>更新日志</n-button>
    </n-badge>
  </n-space>
</template>
```

### 7.3 NDivider——分割线

```vue
<template>
  <n-divider />
  <n-divider>文字居中</n-divider>
  <n-divider title-placement="left">文字靠左</n-divider>
  <n-space align="center">
    <span>用户管理</span>
    <n-divider vertical />
    <span>132 人在线</span>
  </n-space>
</template>
```

### 7.4 NPopover——悬浮/点击弹出的气泡

```vue
<template>
  <n-space>
    <n-popover trigger="hover" title="什么是 VIP？">
      <template #trigger>
        <n-button>悬浮我</n-button>
      </template>
      VIP 会员可以享受 8 折优惠和多倍积分。
    </n-popover>

    <n-popover trigger="click" placement="bottom">
      <template #trigger>
        <n-button>点击我</n-button>
      </template>
      <n-space vertical>
        <n-button text size="small">操作1</n-button>
        <n-button text size="small">操作2</n-button>
      </n-space>
    </n-popover>
  </n-space>
</template>
```

> ⚠️ **本章踩坑小结：**
> 1. NTag 的 `closable` 触发的是 `@close` 事件，**不是** `@click`。
> 2. NBadge 的 `value` 为 0 时默认不显示。想显示 0，加 `show-zero`。
> 3. NPopover 的 `trigger` 默认是 `hover`，但如果内容有按钮想点击，要换成 `click`，否则菜单在鼠标移开后就消失了。

> 📝 **本章回顾：** NTag 用于状态展示，NBadge 用于角标提醒，NDivider 用于视觉分割，NPopover 用于悬浮/点击气泡提示。

---

## 第8章 卡片、气泡提示、弹窗基础容器

> **📖 学习目标：** 学会使用 NCard 组织内容块，NModal 弹出对话框，掌握容器类组件的基本思路。

### 8.1 NCard——页面内容的基本容器

> 💡 NCard 几乎是每个后台管理系统页面的**最小内容单元**。表单放卡片里、表格放卡片里、统计数字也放卡片里。

```vue
<script setup lang="ts">
import { NCard, NButton, NTag, NSpace, NText } from 'naive-ui'
</script>

<template>
  <!-- 最简卡片 -->
  <n-card title="卡片标题">
    这是卡片的主体内容。
  </n-card>

  <!-- 完整卡片 -->
  <n-card title="用户详情" size="medium" :bordered="true">
    <template #header-extra>
      <n-tag type="info">VIP会员</n-tag>
    </template>
    <p>姓名：张三</p>
    <p>年龄：28岁</p>
    <template #footer>
      <n-space justify="end">
        <n-button quaternary>取消</n-button>
        <n-button type="primary">保存</n-button>
      </n-space>
    </template>
  </n-card>

  <!-- 可悬浮卡片 -->
  <n-card title="今日订单" hoverable>
    <div style="font-size: 32px; font-weight: 700; color: #18A058">1,280</div>
    <n-text depth="3">较昨日 +12.5%</n-text>
  </n-card>
</template>
```

### 8.2 NModal——弹窗/对话框

> ⚠️ **NModal 有两种用法，非常容易搞混！**
> **方式 A：** `preset="dialog"` —— 最快速，Naive UI 帮你把标题、内容、按钮都排好了。适合简单的确认/提示。
> **方式 B：** 自定义内容（不用 preset）—— 你完全控制弹窗内部结构。适合表单弹窗、详情弹窗。

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { NModal, NButton, NCard, NForm, NFormItem, NInput, NSpace, useMessage } from 'naive-ui'

const msg = useMessage()
const showDialog = ref(false)
const showFormModal = ref(false)
const formData = ref({ name: '', email: '' })
</script>

<template>
  <n-space>
    <n-button @click="showDialog = true">打开 dialog 弹窗</n-button>
    <n-button @click="showFormModal = true" type="primary">打开表单弹窗</n-button>
  </n-space>

  <!-- 方式 A：preset="dialog" -->
  <n-modal
    v-model:show="showDialog"
    preset="dialog"
    title="确认删除"
    type="warning"
    content="确定要删除这条记录吗？此操作不可撤销。"
    positive-text="确认删除"
    negative-text="取消"
    @positive-click="msg.error('已删除'); showDialog = false"
    @negative-click="showDialog = false"
  />

  <!-- 方式 B：自定义内容弹窗 -->
  <n-modal v-model:show="showFormModal">
    <n-card title="新增用户" style="width: 480px" closable @close="showFormModal = false">
      <n-form :model="formData" label-placement="top">
        <n-form-item label="姓名">
          <n-input v-model:value="formData.name" placeholder="请输入姓名" />
        </n-form-item>
        <n-form-item label="邮箱">
          <n-input v-model:value="formData.email" placeholder="请输入邮箱" />
        </n-form-item>
      </n-form>
      <template #footer>
        <n-space justify="end">
          <n-button @click="showFormModal = false">取消</n-button>
          <n-button type="primary" @click="msg.success('已保存'); showFormModal = false">保存</n-button>
        </n-space>
      </template>
    </n-card>
  </n-modal>
</template>
```

> ⚠️ **超级重要的踩坑提醒：**
> 1. NModal 弹出后，**背景页面会自动禁用滚动**——这是个好设计，但如果你的弹窗内容也需要滚动，要给弹窗内的容器设固定高度 + `overflow: auto`。
> 2. `preset="dialog"` 时，`positive-click` 和 `negative-click` **不会自动关闭弹窗**，你需要手动把 `show` 设为 `false`。
> 3. 如果你同时弹了多个 Modal，**层级（z-index）可能会错乱**——Naive UI 内部会自动处理，但如果你发现后面的弹窗盖不住前面的，检查是否有全局 z-index 污染。

> 📝 **本章回顾：** NCard 是最常用的容器组件，NModal 有两种用法（preset 和自定义）。弹窗关闭需要手动控制 show 的值，这是新手最容易忘记的地方。

---

# 第三篇章 表单组件全解（B端核心）

> **🎯 本篇你将学会：**
> - 所有基础输入组件（文本框、密码框、文本域、数字框）
> - 四种选择组件（单选、复选、下拉、级联）的区别和选择
> - 日期时间组件和格式化
> - 文件上传的完整处理流程
> - NForm 表单系统的校验体系（必填、格式、异步、条件）
> - 动态表单和联动表单的实现

## 第9章 基础输入类组件使用详解

> **📖 学习目标：** 掌握 NInput、NInputNumber 的基本用法，理解 v-model:value 的工作原理。

### 9.1 NInput——输入框全家桶

```vue
<script setup lang="ts">
import { NInput, NInputNumber, NSpace, NIcon, NButton, NText, useMessage } from 'naive-ui'
import { LockClosedOutline, CopyOutline } from '@vicons/ionicons5'
import { ref } from 'vue'

const msg = useMessage()
const text = ref('')
const password = ref('')
const textarea = ref('')
const num = ref(0)
</script>

<template>
  <n-space vertical :size="16">
    <!-- 普通文本输入 -->
    <n-input
      v-model:value="text"
      placeholder="请输入内容"
      clearable
      show-count
      :maxlength="20"
    />

    <!-- 密码框 -->
    <n-input
      v-model:value="password"
      type="password"
      placeholder="请输入密码"
      show-password-on="click"
    >
      <template #prefix>
        <n-icon><LockClosedOutline /></n-icon>
      </template>
      <template #suffix>
        <n-button text @click="msg.success('已复制')">
          <n-icon><CopyOutline /></n-icon>
        </n-button>
      </template>
    </n-input>

    <!-- 文本域 -->
    <n-input
      v-model:value="textarea"
      type="textarea"
      placeholder="请输入详细描述..."
      :rows="4"
      :autosize="{ minRows: 3, maxRows: 8 }"
      show-count
      :maxlength="200"
    />

    <!-- 数字输入框 -->
    <n-input-number
      v-model:value="num"
      :min="0"
      :max="100"
      :step="5"
      placeholder="0-100，步长5"
    >
      <template #prefix><n-text depth="3">¥</n-text></template>
      <template #suffix><n-text depth="3">元</n-text></template>
    </n-input-number>

    <!-- 状态 -->
    <n-input placeholder="正常" />
    <n-input placeholder="禁用" disabled />
    <n-input placeholder="只读" readonly value="不能改我" />
  </n-space>
</template>
```

> 💡 **v-model:value 怎么理解？** 它是 Vue 3 的"双向绑定"语法糖。相当于同时做了两件事：
> 1. 把 `text` 的值作为输入框的初始值传给组件（`:value="text"`）
> 2. 监听组件内部的更新事件，同步回 `text`（`@update:value="text = $event"`）

### 9.2 实时输入校验——手机号校验示例

```vue
<script setup lang="ts">
import { NInput, NText } from 'naive-ui'
import { ref } from 'vue'

const phone = ref('')
const phoneError = ref('')

function validatePhone(value: string) {
  if (!value) { phoneError.value = ''; return }
  if (!/^1[3-9]\d{9}$/.test(value)) {
    phoneError.value = '手机号格式不正确（1开头的11位数字）'
  } else {
    phoneError.value = ''
  }
}
</script>

<template>
  <n-input
    v-model:value="phone"
    placeholder="请输入手机号"
    clearable
    :status="phoneError ? 'error' : phone ? 'success' : undefined"
    @input="validatePhone"
  />
  <n-text v-if="phoneError" type="error" depth="2">{{ phoneError }}</n-text>
</template>
```

> ⚠️ **本章踩坑小结：**
> 1. `type="textarea"` 时 `prefix`/`suffix` 插槽可能不显示（文本域默认不支持）。
> 2. `n-input-number` 的 `v-model:value` 绑定的是 **number 类型**，初始值要设成 `0` 而不是 `'0'`。
> 3. `show-password-on` 默认值是 `mousedown`。如果点一下就松开导致看不到，改成 `click`。

> 📝 **本章回顾：** NInput 支持文本框、密码框、文本域三种形态。v-model:value 实现双向绑定。实时校验用 @input 事件，配合 status 属性显示校验状态。

---

## 第10章 选择类组件：单选、复选、下拉、级联选择

> **📖 学习目标：** 掌握四种选择组件，知道什么场景用哪个。

### 10.1 NRadio / NRadioGroup——单选

```vue
<script setup lang="ts">
import { NRadio, NRadioGroup, NRadioButton, NSpace } from 'naive-ui'
import { ref } from 'vue'

const gender = ref('male')
const color = ref('red')
const colorOptions = [
  { label: '红色', value: 'red' },
  { label: '绿色', value: 'green' },
  { label: '蓝色', value: 'blue' },
  { label: '灰色（禁用）', value: 'gray', disabled: true }
]
</script>

<template>
  <n-space vertical>
    <!-- 传统 radio -->
    <n-radio-group v-model:value="gender">
      <n-space>
        <n-radio value="male">男</n-radio>
        <n-radio value="female">女</n-radio>
      </n-space>
    </n-radio-group>

    <!-- 按钮风格 radio -->
    <n-radio-group v-model:value="color">
      <n-radio-button
        v-for="opt in colorOptions"
        :key="opt.value"
        :value="opt.value"
        :label="opt.label"
        :disabled="opt.disabled"
      />
    </n-radio-group>
  </n-space>
</template>
```

> 💡 **用 n-radio 还是 n-radio-button？** 表单里面（比如性别选择）用 n-radio；页面顶部筛选栏（比如按日期/状态筛选）用 n-radio-button。后者视觉更强，暗示"切换"而非"填写"。

### 10.2 NCheckbox / NCheckboxGroup——复选

```vue
<script setup lang="ts">
import { NCheckbox, NCheckboxGroup, NSpace } from 'naive-ui'
import { ref, computed } from 'vue'

const hobbies = ref<string[]>([])
const hobbyOptions = [
  { label: '阅读', value: 'reading' },
  { label: '运动', value: 'sports' },
  { label: '音乐', value: 'music' },
  { label: '游戏', value: 'gaming', disabled: true }
]

// 全选逻辑
const allValues = ['reading', 'sports', 'music']
const isAllChecked = computed({
  get: () => hobbies.value.length === allValues.length,
  set: (val: boolean) => { hobbies.value = val ? [...allValues] : [] }
})
const isIndeterminate = computed(
  () => hobbies.value.length > 0 && hobbies.value.length < allValues.length
)
</script>

<template>
  <n-space vertical>
    <n-checkbox>我同意用户协议</n-checkbox>

    <n-checkbox-group v-model:value="hobbies">
      <n-space>
        <n-checkbox v-for="opt in hobbyOptions" :key="opt.value" :value="opt.value" :disabled="opt.disabled">
          {{ opt.label }}
        </n-checkbox>
      </n-space>
    </n-checkbox-group>

    <n-checkbox :checked="isAllChecked" :indeterminate="isIndeterminate" @update:checked="isAllChecked = $event">
      全选
    </n-checkbox>
  </n-space>
</template>
```

> 💡 **indeterminate（半选态）怎么理解：** 当你只勾了"阅读"和"运动"时，"全选"复选框不是空的，也不是打勾的，而是显示**一条横线**——这叫半选态。

### 10.3 NSelect——下拉选择器

这是**使用频率最高**的选择组件。

```vue
<script setup lang="ts">
import { NSelect, NSpace } from 'naive-ui'
import { ref } from 'vue'

const selected = ref<string | null>(null)
const options = [
  { label: '北京', value: 'beijing' },
  { label: '上海', value: 'shanghai' },
  { label: '杭州', value: 'hangzhou' },
  { type: 'group', label: '一线城市', key: 'top',
    children: [
      { label: '广州', value: 'gz' },
      { label: '深圳', value: 'sz' }
    ]
  }
]

const multiSelected = ref<string[]>([])

// 远程搜索
const remoteValue = ref<string | null>(null)
const remoteLoading = ref(false)
const remoteOptions = ref<Array<{label: string; value: string}>>([])

async function handleSearch(query: string) {
  if (!query) { remoteOptions.value = []; return }
  remoteLoading.value = true
  await new Promise(r => setTimeout(r, 500))
  remoteOptions.value = Array.from({ length: 5 }, (_, i) => ({
    label: `${query} - 结果 ${i + 1}`,
    value: `${query}-${i}`
  }))
  remoteLoading.value = false
}
</script>

<template>
  <n-space vertical>
    <n-select v-model:value="selected" :options="options" placeholder="请选择城市" clearable />

    <n-select
      v-model:value="multiSelected"
      :options="options"
      placeholder="可多选"
      multiple
      :max-tag-count="2"
      clearable
    />

    <n-select
      v-model:value="remoteValue"
      :options="remoteOptions"
      placeholder="输入文字，远程搜索"
      filterable
      remote
      :loading="remoteLoading"
      @search="handleSearch"
    />
  </n-space>
</template>
```

> ⚠️ **选择器常见坑：**
> 1. `options` 里的 `label` 是给用户看的，`value` 是给程序用的。不要搞混。
> 2. 多选模式下，`v-model:value` 绑定的是**数组**（`string[]`），不是字符串。
> 3. 远程搜索时 `filterable` 必须为 `true`，`remote` 必须为 `true`，然后监听 `@search`——三个条件缺一不可。

### 10.4 NCascader——级联选择器

```vue
<script setup lang="ts">
import { NCascader } from 'naive-ui'
import { ref } from 'vue'

const selectedPath = ref<string[]>([])

const cascadeData = [
  {
    label: '浙江省', value: 'zhejiang', children: [
      { label: '杭州市', value: 'hangzhou', children: [
        { label: '西湖区', value: 'xihu' },
        { label: '滨江区', value: 'binjiang' }
      ]},
      { label: '宁波市', value: 'ningbo', children: [
        { label: '海曙区', value: 'haishu' }
      ]}
    ]
  }
]
</script>

<template>
  <n-cascader v-model:value="selectedPath" :options="cascadeData" placeholder="请选择省市区" clearable />
</template>
```

> ⚠️ **本章踩坑小结：**
> 1. NRadioGroup 绑定的变量类型取决于 option 的 `value` 类型。
> 2. NCheckboxGroup 绑定的永远是**数组**，即使只有一个被选中也是 `['reading']`。
> 3. NCascader 的 `value` 是**路径数组**（如 `['zhejiang','hangzhou']`），不是单个值。

> 📝 **本章回顾：** 四种选择组件各有适用场景：NRadio 用在小选项数，NCheckbox 用于多选，NSelect 是最灵活的下拉，NCascader 用于层级数据。远程搜索需同时开启 filterable + remote + @search。

---

## 第11章 时间日期类组件全方位使用

> **📖 学习目标：** 掌握 NDatePicker 和 NTimePicker 的基本用法，知道怎么限制可选日期范围。

### 11.1 NDatePicker——日期选择器

```vue
<script setup lang="ts">
import { NDatePicker, NSpace, NText } from 'naive-ui'
import { ref } from 'vue'

const date = ref<number | null>(null)
const dateRange = ref<[number | null, number | null]>([null, null])
const datetime = ref<number | null>(null)
</script>

<template>
  <n-space vertical>
    <n-text strong>选择日期</n-text>
    <n-date-picker v-model:value="date" type="date" clearable placeholder="选择日期" />

    <n-text strong>选择日期范围</n-text>
    <n-date-picker v-model:value="dateRange" type="daterange" clearable placeholder="选择日期范围" />

    <n-text strong>选择日期和时间</n-text>
    <n-date-picker v-model:value="datetime" type="datetime" clearable placeholder="选择日期时间" />

    <n-text strong>选择月份</n-text>
    <n-date-picker v-model:value="month" type="month" placeholder="选择月份" />

    <n-text strong>选择年份</n-text>
    <n-date-picker v-model:value="year" type="year" placeholder="选择年份" />
  </n-space>
</template>
```

### 11.2 限制可选范围 + 快捷选项

```vue
<script setup lang="ts">
import { NDatePicker } from 'naive-ui'
import { ref } from 'vue'

const date = ref<number | null>(null)
const todayStart = new Date(); todayStart.setHours(0, 0, 0, 0)
const todayTs = todayStart.getTime()
const nextWeekTs = todayTs + 7 * 24 * 60 * 60 * 1000

const shortcuts = {
  '今天': () => Date.now(),
  '一周后': () => Date.now() + 7 * 24 * 60 * 60 * 1000,
  '一个月后': () => Date.now() + 30 * 24 * 60 * 60 * 1000
}
</script>

<template>
  <n-date-picker v-model:value="date" :is-date-disabled="(ts: number) => ts < todayTs" placeholder="不可选过去日期" />
  <n-date-picker v-model:value="date" :shortcuts="shortcuts" placeholder="有快捷按钮" />
  <n-date-picker v-model:value="date" value-format="yyyy-MM-dd HH:mm:ss" type="datetime" placeholder="自定义格式" />
</template>
```

> ⚠️ **日期组件最容易踩的坑：**
> 1. `v-model:value` 绑定的值是**数字类型的时间戳**（如 `1716086400000`），不是字符串。需要显示字符串时用 `value-format` 或 dayjs 库。
> 2. `is-date-disabled` 的 `ts` 是每天 00:00:00 的时间戳，返回 `true` 表示禁用。
> 3. 日期范围选择器 vs 单个日期选择器：`v-model:value` 的类型不同（数组 vs 数字）。

> 📝 **本章回顾：** NDatePicker 支持 date/daterange/datetime/month/year 五种类型。value 是数字时间戳。限制日期用 is-date-disabled，快捷选项用 shortcuts。

---

## 第12章 文件上传组件全场景实战

> **📖 学习目标：** 学会使用 NUpload 上传文件，处理文件大小/类型限制、多文件上传、头像上传。

### 12.1 NUpload 基础拖拽上传

```vue
<script setup lang="ts">
import { NUpload, NIcon, useMessage } from 'naive-ui'
import { CloudUploadOutline } from '@vicons/ionicons5'
import { ref } from 'vue'
import type { UploadFileInfo, UploadCustomRequestOptions } from 'naive-ui'

const msg = useMessage()
const fileList = ref<UploadFileInfo[]>([])

// 自定义上传——模拟进度反馈
function customUpload({ file, onFinish, onError, onProgress }: UploadCustomRequestOptions) {
  let progress = 0
  const timer = setInterval(() => {
    progress += 20
    onProgress({ percent: progress })
    if (progress >= 100) {
      clearInterval(timer)
      onFinish()
      msg.success(`${file.name} 上传完成`)
    }
  }, 300)
}

// 上传前检查
function beforeUpload(data: { file: UploadFileInfo }) {
  const f = data.file.file
  if (!f) return false
  if (f.size > 5 * 1024 * 1024) { msg.error('文件不能超过 5MB'); return false }
  const allowed = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf']
  if (!allowed.includes(f.type)) { msg.error('仅支持 JPG/PNG/GIF/PDF'); return false }
  return true
}
</script>

<template>
  <n-upload
    v-model:file-list="fileList"
    :custom-request="customUpload"
    :before-upload="beforeUpload"
    multiple
    list-type="image"
    show-remove-button
  >
    <n-upload-dragger>
      <div style="padding: 40px 0; text-align: center">
        <n-icon size="48" :depth="3"><CloudUploadOutline /></n-icon>
        <p style="margin: 8px 0 4px">点击或拖拽文件到此区域上传</p>
        <p style="font-size: 12px; color: #999">支持 JPG/PNG/GIF/PDF，最大 5MB</p>
      </div>
    </n-upload-dragger>
  </n-upload>
</template>
```

### 12.2 头像上传（单文件+本地预览）

```vue
<script setup lang="ts">
import { NUpload, NAvatar, NIcon } from 'naive-ui'
import { PersonOutline } from '@vicons/ionicons5'
import { ref } from 'vue'
import type { UploadFileInfo } from 'naive-ui'

const avatarUrl = ref('')

function handleChange(data: { file: UploadFileInfo }) {
  const f = data.file.file
  if (!f) return
  const reader = new FileReader()
  reader.onload = (e) => { avatarUrl.value = e.target?.result as string }
  reader.readAsDataURL(f)
}
</script>

<template>
  <n-upload :max="1" accept="image/png,image/jpeg" list-type="image" show-remove-button @change="handleChange">
    <n-avatar v-if="avatarUrl" :src="avatarUrl" :size="100" round />
    <n-avatar v-else :size="100" round style="background: #eee; cursor: pointer">
      <template #icon><n-icon><PersonOutline /></n-icon></template>
    </n-avatar>
  </n-upload>
</template>
```

> ⚠️ **上传组件踩坑提醒：**
> 1. `beforeUpload` 的返回值是 `boolean`。返回 `false` 阻止上传，返回 `true` 继续。别忘了 return！
> 2. 如果你用了 `custom-request`，**`action` 属性就不生效了**——所有逻辑走 `custom-request`。
> 3. 头像上传的 `:max="1"` 表示**最多保留 1 个文件**。选了新的，旧的会自动移除。

> 📝 **本章回顾：** NUpload 通过 custom-request 自定义上传逻辑，beforeUpload 做前置检查（大小/类型）。头像上传场景用 max=1 + FileReader 实现本地预览。

---

## 第13章 Form 表单系统与高阶校验

> **📖 学习目标：** 掌握 NForm 的完整用法——数据绑定、校验规则、提交处理。

### 13.1 NForm 基础三要素

> 💡 一个完整的 NForm 由三个东西组成：
> 1. **`model`**（表单数据对象）——存所有字段的值
> 2. **`rules`**（校验规则）——告诉程序每个字段怎么校验
> 3. **NFormItem**（表单项）——每个输入字段，通过 `path` 关联到 `model` 中的属性

```vue
<script setup lang="ts">
import { NForm, NFormItem, NInput, NSelect, NButton, NSpace, useMessage } from 'naive-ui'
import { ref } from 'vue'
import type { FormInst, FormRules } from 'naive-ui'

const msg = useMessage()
const formRef = ref<FormInst | null>(null)

const formData = ref({
  username: '',
  password: '',
  email: '',
  role: null as string | null
})

const rules: FormRules = {
  username: [
    { required: true, message: '请输入用户名', trigger: 'blur' },
    { min: 3, max: 20, message: '用户名长度 3-20 个字符', trigger: 'blur' },
    { pattern: /^[a-zA-Z0-9_]+$/, message: '仅支持英文、数字和下划线', trigger: 'blur' }
  ],
  password: [
    { required: true, message: '请输入密码', trigger: 'blur' },
    { min: 6, message: '密码至少 6 位', trigger: 'blur' }
  ],
  email: [
    { required: true, message: '请输入邮箱', trigger: 'blur' },
    { type: 'email', message: '邮箱格式不正确', trigger: ['blur', 'change'] }
  ],
  role: [
    { required: true, message: '请选择角色', trigger: 'change' }
  ]
}

const roleOptions = [
  { label: '管理员', value: 'admin' },
  { label: '编辑', value: 'editor' },
  { label: '访客', value: 'guest' }
]

function handleSubmit(e: Event) {
  e.preventDefault()
  formRef.value?.validate((errors) => {
    if (!errors) {
      msg.success('校验通过！数据：' + JSON.stringify(formData.value))
    } else {
      msg.error('请检查表单中的错误')
    }
  })
}

function handleReset() {
  formRef.value?.restoreValidation()
  formData.value = { username: '', password: '', email: '', role: null }
}
</script>

<template>
  <n-form ref="formRef" :model="formData" :rules="rules" label-placement="left" label-width="80" label-align="right" style="max-width: 500px">
    <n-form-item label="用户名" path="username">
      <n-input v-model:value="formData.username" placeholder="请输入用户名（3-20位）" clearable />
    </n-form-item>
    <n-form-item label="密码" path="password">
      <n-input v-model:value="formData.password" type="password" placeholder="请输入密码（至少6位）" show-password-on="click" />
    </n-form-item>
    <n-form-item label="邮箱" path="email">
      <n-input v-model:value="formData.email" placeholder="请输入邮箱" clearable />
    </n-form-item>
    <n-form-item label="角色" path="role">
      <n-select v-model:value="formData.role" :options="roleOptions" placeholder="请选择角色" />
    </n-form-item>
    <n-form-item>
      <n-space>
        <n-button type="primary" @click="handleSubmit">提交</n-button>
        <n-button @click="handleReset">重置</n-button>
      </n-space>
    </n-form-item>
  </n-form>
</template>
```

### 13.2 异步校验——用户名是否已被注册

```vue
<script setup lang="ts">
const rules: FormRules = {
  username: [
    { required: true, message: '请输入用户名', trigger: 'blur' },
    {
      // async validator：校验函数返回 Promise
      validator: async (_rule, value: string) => {
        if (!value) return
        await new Promise(resolve => setTimeout(resolve, 1000))
        if (value.toLowerCase() === 'admin') {
          return new Error('用户名 "admin" 已被注册')
        }
      },
      trigger: 'blur'
    }
  ]
}
</script>
```

> 💡 **validator 的三条返回规则：**
> - 返回 `Promise.resolve()` 或不返回 → 校验通过
> - 返回 `new Error('xxx')` 或 `Promise.reject()` → 校验失败，显示 Error 的 message
> - 返回 `false` → 校验失败，显示默认错误信息

> ⚠️ **本章踩坑小结：**
> 1. `rules` 里每个字段的 `key`（如 `username`）必须和 `model` 的字段名**完全一致**，不一致校验不触发。
> 2. `trigger` 决定什么时候触发校验。`'blur'` = 失去焦点；`'change'` = 值变化 + 失去焦点。
> 3. `formRef.value?.validate()` 是**手动触发**全表单校验。它不会自动在提交时执行——你需要自己在 submit 函数里调用它。

> 📝 **本章回顾：** NForm 的三要素是 model、rules、NFormItem。rules 支持 required/min/max/pattern/email 等内置规则，也支持 async validator 自定义异步校验。提交时手动调用 validate()。

---

## 第14章 动态表单、联动表单、复杂表单实战

> **📖 学习目标：** 学会动态增减表单项、实现字段联动、处理条件必填。

### 14.1 动态增减表单项——类似简历中的"教育经历"

```vue
<script setup lang="ts">
import { NForm, NFormItemGi, NGrid, NInput, NButton, NSpace, NIcon, NCard, useMessage } from 'naive-ui'
import { AddCircleOutline, RemoveCircleOutline } from '@vicons/ionicons5'
import { ref } from 'vue'

const msg = useMessage()

interface Education {
  id: number
  school: string
  major: string
  startYear: string
  endYear: string
}

const formData = ref({ education: [] as Education[] })
let nextId = 1

function addEducation() {
  formData.value.education.push({
    id: nextId++, school: '', major: '', startYear: '', endYear: ''
  })
}

function removeEducation(index: number) {
  formData.value.education.splice(index, 1)
}
</script>

<template>
  <n-form>
    <n-space vertical :size="16">
      <n-space justify="space-between" align="center">
        <span style="font-weight: 600">教育经历</span>
        <n-button size="small" @click="addEducation">
          <template #icon><n-icon><AddCircleOutline /></n-icon></template>
          新增
        </n-button>
      </n-space>

      <n-card v-for="(item, index) in formData.education" :key="item.id" size="small" :title="`教育经历 #${index + 1}`">
        <n-grid :cols="2" :x-gap="12">
          <n-form-item-gi :label="'学校'" :path="`education[${index}].school`">
            <n-input v-model:value="item.school" placeholder="学校名称" />
          </n-form-item-gi>
          <n-form-item-gi :label="'专业'" :path="`education[${index}].major`">
            <n-input v-model:value="item.major" placeholder="专业" />
          </n-form-item-gi>
          <n-form-item-gi :label="'开始'" :path="`education[${index}].startYear`">
            <n-input v-model:value="item.startYear" placeholder="如：2020" />
          </n-form-item-gi>
          <n-form-item-gi :label="'结束'" :path="`education[${index}].endYear`">
            <n-input v-model:value="item.endYear" placeholder="如：2024" />
          </n-form-item-gi>
        </n-grid>
        <n-button size="tiny" type="error" quaternary @click="removeEducation(index)">
          <template #icon><n-icon><RemoveCircleOutline /></n-icon></template>
          删除此条
        </n-button>
      </n-card>
    </n-space>
  </n-form>
</template>
```

> ⚠️ **动态表单最容易踩的坑：**
> 1. `v-for` 的 `key` 必须用**不会变的唯一标识**（如自增 id），**禁止用 index**。因为删除中间一条后 index 会变，导致 Vue 渲染出 bug。
> 2. `path` 里的数组索引语法是 `education[0].school`，中间没有空格。

### 14.2 联动表单——选择了"有手机"才出现手机号输入框

```vue
<script setup lang="ts">
import { NForm, NFormItem, NInput, NRadio, NRadioGroup } from 'naive-ui'
import { ref, computed } from 'vue'
import type { FormRules } from 'naive-ui'

const formData = ref({ hasPhone: false, phone: '', email: '' })

// 动态校验规则
const rules = computed<FormRules>(() => ({
  phone: formData.value.hasPhone
    ? [{ required: true, message: '请输入手机号', trigger: 'blur' }]
    : [],
  email: [{ required: true, message: '请输入邮箱', trigger: 'blur' }]
}))
</script>

<template>
  <n-form :model="formData" :rules="rules">
    <n-form-item path="hasPhone">
      <n-radio-group v-model:value="formData.hasPhone">
        <n-radio :value="false">仅邮箱联系</n-radio>
        <n-radio :value="true">同时提供手机号</n-radio>
      </n-radio-group>
    </n-form-item>
    <n-form-item v-if="formData.hasPhone" label="手机号" path="phone">
      <n-input v-model:value="formData.phone" placeholder="请输入手机号" />
    </n-form-item>
    <n-form-item label="邮箱" path="email">
      <n-input v-model:value="formData.email" placeholder="请输入邮箱" />
    </n-form-item>
  </n-form>
</template>
```

> 📝 **本章回顾：** 动态表单用 `v-for` + 唯一 id 实现增删。联动表单用 `computed` 动态生成 rules + `v-if` 控制显示/隐藏。

---

# 第四篇章 布局与容器组件精讲

> **🎯 本篇你将学会：**
> - NGrid + NGi 栅格系统和响应式断点
> - NLayout 系列构建标准后台管理布局（侧边栏 + 头部 + 内容）
> - NDrawer / NTabs / NCollapse 三种容器组件的选择与使用
> - 多级菜单折叠、菜单搜索、面包屑与标签页联动

## 第15章 栅格布局系统与自适应布局

> **📖 学习目标：** 掌握 NGrid + NGi 的用法，理解响应式断点。

### 15.1 栅格基础——NGrid + NGi

> 💡 栅格系统就是把页面横向划分成若干"列"，Naive UI 默认一行 24 列（因为 24 可以被 1、2、3、4、6、8、12 整除，排列组合最多）。

```vue
<script setup lang="ts">
import { NGrid, NGi, NCard } from 'naive-ui'
</script>

<template>
  <n-grid :cols="3" :x-gap="12" :y-gap="12">
    <n-gi :span="2">
      <n-card title="跨 2 列" size="small">占 3 列中的 2 列</n-card>
    </n-gi>
    <n-gi :span="1">
      <n-card title="跨 1 列" size="small">占剩下的 1 列</n-card>
    </n-gi>
    <n-gi :span="3">
      <n-card title="跨 3 列" size="small">占满一整行</n-card>
    </n-gi>
  </n-grid>
</template>
```

### 15.2 响应式栅格

```vue
<template>
  <!--
    屏幕 < 400px → 2列；>= 400px → 3列；>= 600px → 4列；>= 900px → 6列
  -->
  <n-grid cols="2 400:3 600:4 900:6" :x-gap="12" :y-gap="12">
    <n-gi v-for="i in 12" :key="i">
      <n-card size="small" :title="`卡片 ${i}`">内容</n-card>
    </n-gi>
  </n-grid>
</template>
```

> 📝 **本章回顾：** NGrid 默认 24 列，span 决定跨列数。cols 和 span 都支持响应式断点语法。

---

## 第16章 全局页面布局（侧边栏、头部、内容、底部）

> **📖 学习目标：** 使用 NLayout 系列组件搭建一个标准后台管理界面，含多级菜单、面包屑、标签页联动。

### 16.1 NLayout 组件全家福

```
NLayout           → 最外层容器
  ├─ NLayoutHeader    → 顶部栏
  ├─ NLayout (has-sider)  → 主体区域
  │   ├─ NLayoutSider    → 侧边栏
  │   └─ NLayoutContent  → 内容区
  └─ NLayoutFooter    → 底部
```

### 16.2 完整标准后台布局（含多级菜单+面包屑+标签页联动）

```vue
<script setup lang="ts">
import { ref, computed, h } from 'vue'
import { useRouter, useRoute } from 'vue-router'
import {
  NLayout, NLayoutHeader, NLayoutSider, NLayoutContent,
  NMenu, NSpace, NIcon, NBreadcrumb, NBreadcrumbItem,
  NButton, NAvatar, NDropdown, NTabs, NTabPane
} from 'naive-ui'
import {
  MenuOutline, PersonOutline, SettingsOutline, LogOutOutline,
  SunnyOutline, MoonOutline, HomeOutline, PeopleOutline, CogOutline,
  DocumentTextOutline
} from '@vicons/ionicons5'
import type { MenuOption, DropdownOption } from 'naive-ui'

const router = useRouter()
const route = useRoute()

const collapsed = ref(false)
const isDark = ref(false)

// ===== 多级菜单配置 =====
const menuOptions: MenuOption[] = [
  {
    label: '仪表盘', key: '/dashboard',
    icon: () => h(NIcon, null, { default: () => h(HomeOutline) })
  },
  {
    label: '系统管理', key: '/system',
    icon: () => h(NIcon, null, { default: () => h(SettingsOutline) }),
    children: [
      { label: '用户管理', key: '/user' },
      { label: '角色管理', key: '/role' },
      { label: '权限管理', key: '/permission' }
    ]
  },
  {
    label: '内容管理', key: '/content',
    icon: () => h(NIcon, null, { default: () => h(DocumentTextOutline) }),
    children: [
      { label: '文章列表', key: '/article' },
      { label: '分类管理', key: '/category' }
    ]
  }
]

// ===== 菜单搜索 =====
const menuSearchText = ref('')

// 递归过滤菜单
function filterMenu(options: MenuOption[], query: string): MenuOption[] {
  if (!query) return options
  return options.reduce((acc, opt) => {
    const labelMatch = (opt.label as string).toLowerCase().includes(query.toLowerCase())
    const filteredChildren = opt.children ? filterMenu(opt.children, query) : []
    if (labelMatch || filteredChildren.length > 0) {
      acc.push({ ...opt, children: filteredChildren.length > 0 ? filteredChildren : opt.children })
    }
    return acc
  }, [] as MenuOption[])
}

const filteredMenuOptions = computed(() => filterMenu(menuOptions, menuSearchText.value))

// ===== 面包屑 =====
const breadcrumbItems = computed(() => {
  return route.matched.filter(r => r.meta?.title).map(r => r.meta.title as string)
})

// ===== 历史标签页（多页签联动） =====
const visitedTabs = ref<Array<{ name: string; title: string }>>([])

function handleMenuSelect(key: string) {
  router.push(key)
  // 添加到标签页列表（去重）
  const route = router.resolve(key)
  if (route.name && !visitedTabs.value.find(t => t.name === route.name)) {
    visitedTabs.value.push({ name: route.name as string, title: route.meta.title as string || key })
  }
}

function closeTab(tabName: string) {
  visitedTabs.value = visitedTabs.value.filter(t => t.name !== tabName)
}

// 用户下拉
const userOptions: DropdownOption[] = [
  { label: '个人信息', key: 'profile' },
  { label: '修改密码', key: 'password' },
  { type: 'divider' },
  { label: '退出登录', key: 'logout' }
]

function handleUserSelect(key: string) {
  if (key === 'logout') {
    localStorage.removeItem('token')
    router.push('/login')
  }
}
</script>

<template>
  <n-layout position="absolute" style="height: 100vh">
    <!-- 顶部导航 -->
    <n-layout-header bordered style="height: 56px; padding: 0 24px; display: flex; align-items: center; justify-content: space-between">
      <n-space align="center">
        <n-button text @click="collapsed = !collapsed">
          <n-icon size="20"><MenuOutline /></n-icon>
        </n-button>
        <span style="font-weight: 700; font-size: 18px; margin-left: 12px">Admin 后台</span>
      </n-space>
      <n-space align="center" :size="16">
        <n-button text @click="isDark = !isDark">
          <n-icon size="20">
            <SunnyOutline v-if="isDark" />
            <MoonOutline v-else />
          </n-icon>
        </n-button>
        <n-dropdown :options="userOptions" @select="handleUserSelect">
          <n-space align="center" style="cursor: pointer">
            <n-avatar round size="small" color="#18A058">A</n-avatar>
            <span>管理员</span>
          </n-space>
        </n-dropdown>
      </n-space>
    </n-layout-header>

    <n-layout has-sider position="absolute" style="top: 56px; bottom: 0">
      <!-- 侧边栏 -->
      <n-layout-sider bordered collapse-mode="width" :collapsed-width="64" :width="220" :collapsed="collapsed" show-trigger="bar">
        <!-- 菜单搜索框 -->
        <div style="padding: 8px 12px" v-if="!collapsed">
          <n-input v-model:value="menuSearchText" placeholder="搜索菜单..." size="small" clearable />
        </div>
        <n-menu
          :collapsed="collapsed"
          :collapsed-width="64"
          :collapsed-icon-size="22"
          :options="filteredMenuOptions"
          :value="route.path"
          @update:value="handleMenuSelect"
        />
      </n-layout-sider>

      <!-- 内容区 -->
      <n-layout-content :native-scrollbar="false" style="padding: 24px">
        <!-- 面包屑 -->
        <n-breadcrumb style="margin-bottom: 16px">
          <n-breadcrumb-item v-for="item in breadcrumbItems" :key="item">
            {{ item }}
          </n-breadcrumb-item>
        </n-breadcrumb>

        <!-- 多页签 -->
        <n-tabs type="card" closable @close="closeTab" style="margin-bottom: 16px">
          <n-tab-pane
            v-for="tab in visitedTabs"
            :key="tab.name"
            :name="tab.name"
            :tab="tab.title"
          />
        </n-tabs>

        <router-view />
      </n-layout-content>
    </n-layout>
  </n-layout>
</template>
```

> 💡 **多页签（历史标签页）** 是后台系统中非常实用的功能。用户每点击一个菜单，就在顶部标签页栏添加一个新标签，点击标签可以直接切换已打开过的页面，关闭标签则移除。这比纯面包屑的体验好很多。

> ⚠️ **布局高度问题：** 用 `position="absolute"` + `top`/`bottom` 让布局撑满屏幕。如果内容区域出现双滚动条，检查 NLayoutContent 是否设置了固定的 `overflow`。

> 📝 **本章回顾：** NLayout 系列是完整页面布局的骨架。多级菜单用 children 嵌套，菜单搜索用 computed 动态过滤，多页签联动提升用户体验。

---

## 第17章 抽屉、弹窗、标签页、折叠面板容器组件

> **📖 学习目标：** 在弹窗、抽屉、标签页、折叠面板之间选对正确的容器组件。

### 17.1 NDrawer——抽屉（从侧边滑出的面板）

> 💡 **什么时候用 Drawer 而不是 Modal？**
> - 表单内容少（1-3 个字段）→ Modal
> - 表单内容多、需要更多操作空间 → Drawer
> - 查看详情（不打断当前操作）→ Drawer

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { NDrawer, NDrawerContent, NButton, NForm, NFormItem, NInput, NSpace, useMessage } from 'naive-ui'

const msg = useMessage()
const showDrawer = ref(false)
const placement = ref<'left' | 'right' | 'top' | 'bottom'>('right')
const formData = ref({ name: '', email: '', desc: '' })

function handleSave() {
  msg.success('保存成功')
  showDrawer.value = false
}
</script>

<template>
  <n-space>
    <n-button @click="placement = 'right'; showDrawer = true" type="primary">右侧抽屉</n-button>
    <n-button @click="placement = 'left'; showDrawer = true">左侧抽屉</n-button>
    <n-button @click="placement = 'top'; showDrawer = true">顶部抽屉</n-button>
    <n-button @click="placement = 'bottom'; showDrawer = true">底部抽屉</n-button>
  </n-space>

  <n-drawer v-model:show="showDrawer" :width="500" :placement="placement" :mask-closable="true" :close-on-esc="true">
    <n-drawer-content title="新增用户" closable>
      <n-form :model="formData" label-placement="top">
        <n-form-item label="姓名"><n-input v-model:value="formData.name" /></n-form-item>
        <n-form-item label="邮箱"><n-input v-model:value="formData.email" /></n-form-item>
        <n-form-item label="描述"><n-input v-model:value="formData.desc" type="textarea" :rows="4" /></n-form-item>
      </n-form>
      <template #footer>
        <n-space justify="end">
          <n-button @click="showDrawer = false">取消</n-button>
          <n-button type="primary" @click="handleSave">保存</n-button>
        </n-space>
      </template>
    </n-drawer-content>
  </n-drawer>
</template>
```

### 17.2 NTabs——标签页切换

```vue
<template>
  <n-tabs v-model:value="activeTab" type="line" animated>
    <n-tab-pane name="basic" tab="基础信息">基础信息内容</n-tab-pane>
    <n-tab-pane name="detail" tab="详细信息">详细信息内容</n-tab-pane>
    <n-tab-pane name="logs" tab="操作日志">操作日志内容</n-tab-pane>
  </n-tabs>
</template>
```

### 17.3 NCollapse——折叠面板

```vue
<script setup lang="ts">
import { NCollapse, NCollapseItem } from 'naive-ui'
import { ref } from 'vue'

const activeNames = ref(['faq1'])
</script>

<template>
  <n-collapse v-model:value="activeNames">
    <n-collapse-item title="常见问题 1：怎么安装？" name="faq1">
      执行 <code>pnpm add naive-ui</code> 即可。
    </n-collapse-item>
    <n-collapse-item title="常见问题 2：怎么换主题？" name="faq2">
      使用 <code>NConfigProvider</code> 的 <code>theme-overrides</code>。
    </n-collapse-item>
    <n-collapse-item title="常见问题 3：支持 IE 吗？" name="faq3">
      不支持。Naive UI 只支持现代浏览器。
    </n-collapse-item>
  </n-collapse>
</template>
```

> ⚠️ **本章踩坑小结：**
> 1. NDrawer 用 `placement="top"` 或 `"bottom"` 时，`:width` 不生效，改用 `:height`。
> 2. NTabs 的 `animated` 默认是 `false`，设为 `true` 会有滑动切换动画——但内容复杂时可能会卡。
> 3. NCollapse 的 `v-model:value` 绑定的是展开项的 `name` 数组，不是布尔值。

> 📝 **本章回顾：** Drawer 是从侧边滑出的面板，适合大表单和详情展示；Tabs 是标签页切换，Collapse 是可折叠内容。三者各有适用场景。

---

# 第五篇章 数据展示高级组件

> **🎯 本篇你将学会：**
> - NDataTable 的完整用法：基础表格、排序、筛选、行内编辑、虚拟滚动
> - 表格导出 CSV/Excel、列拖拽排序、表头分组
> - NTree 和 NTreeSelect 的树形数据操作
> - NAvatar、NProgress、NRate 等辅助展示组件

## 第18章 高性能表格组件

> **📖 学习目标：** 掌握 NDataTable 的基本用法，学会排序/筛选/行内编辑/虚拟滚动/导出/列拖拽。

### 18.1 NDataTable 基础——五分钟搭一个表格

```vue
<script setup lang="ts">
import { NDataTable, NTag, NButton, NSpace, useMessage } from 'naive-ui'
import { h } from 'vue'
import type { DataTableColumns } from 'naive-ui'

const msg = useMessage()

interface User {
  id: number
  name: string
  age: number
  email: string
  status: 'active' | 'disabled'
}

const data: User[] = [
  { id: 1, name: '张三', age: 28, email: 'zhangsan@example.com', status: 'active' },
  { id: 2, name: '李四', age: 32, email: 'lisi@example.com', status: 'disabled' },
  { id: 3, name: '王五', age: 25, email: 'wangwu@example.com', status: 'active' },
  { id: 4, name: '赵六', age: 35, email: 'zhaoliu@example.com', status: 'active' },
  { id: 5, name: '孙七', age: 29, email: 'sunqi@example.com', status: 'disabled' }
]

const columns: DataTableColumns<User> = [
  { title: 'ID', key: 'id', width: 80, sorter: (a, b) => a.id - b.id },
  { title: '姓名', key: 'name', width: 120, filter: true },
  { title: '年龄', key: 'age', width: 80, sorter: (a, b) => a.age - b.age },
  { title: '邮箱', key: 'email', width: 220 },
  {
    title: '状态', key: 'status', width: 100,
    render(row: User) {
      return h(NTag, {
        type: row.status === 'active' ? 'success' : 'warning',
        size: 'small'
      }, { default: () => row.status === 'active' ? '启用' : '禁用' })
    }
  },
  {
    title: '操作', key: 'actions', width: 150,
    render(row: User) {
      return h(NSpace, { size: 'small' }, {
        default: () => [
          h(NButton, { size: 'small', tertiary: true, onClick: () => msg.info(`编辑: ${row.name}`) }, { default: () => '编辑' }),
          h(NButton, { size: 'small', tertiary: true, type: 'error', onClick: () => msg.warning(`删除: ${row.name}`) }, { default: () => '删除' })
        ]
      })
    }
  }
]
</script>

<template>
  <n-data-table :columns="columns" :data="data" :pagination="{ pageSize: 5 }" :bordered="true" striped />
</template>
```

> 💡 **h() 函数是什么？** `h` 是 Vue 的 `createVNode` 的别名。你在 template 里写 `<n-button>编辑</n-button>`，等价于在 `render` 函数里写 `h(NButton, {}, { default: () => '编辑' })`。因为列配置里的 `render` 不是写在 template 里的，所以必须用 `h()` 函数来创建组件。

### 18.2 表格行内编辑

```vue
<script setup lang="ts">
import { NDataTable, NInput, NSelect, NButton, NSpace, useMessage } from 'naive-ui'
import { h, ref } from 'vue'

const msg = useMessage()

interface EditableRow { id: number; name: string; age: number; role: string; editing?: boolean }
const data = ref<EditableRow[]>([
  { id: 1, name: '张三', age: 28, role: 'admin' },
  { id: 2, name: '李四', age: 32, role: 'editor' }
])

const cache = ref<Record<number, EditableRow>>({})

function startEdit(row: EditableRow) { cache.value[row.id] = { ...row }; row.editing = true }
function cancelEdit(row: EditableRow) { Object.assign(row, cache.value[row.id]); delete cache.value[row.id]; row.editing = false }
function saveEdit(row: EditableRow) { delete cache.value[row.id]; row.editing = false; msg.success(`已保存: ${row.name}`) }

const columns = [
  {
    title: '姓名', key: 'name', width: 120,
    render(row: EditableRow) {
      if (row.editing) return h(NInput, { value: row.name, 'onUpdate:value': (v: string) => row.name = v, size: 'small' })
      return row.name
    }
  },
  {
    title: '年龄', key: 'age', width: 80,
    render(row: EditableRow) {
      if (row.editing) return h(NInput, { value: String(row.age), 'onUpdate:value': (v: string) => row.age = Number(v), size: 'small' })
      return String(row.age)
    }
  },
  {
    title: '角色', key: 'role', width: 120,
    render(row: EditableRow) {
      if (row.editing) return h(NSelect, { value: row.role, 'onUpdate:value': (v: string) => row.role = v, options: [{ label: '管理员', value: 'admin' }, { label: '编辑', value: 'editor' }], size: 'small' })
      return row.role
    }
  },
  {
    title: '操作', key: 'actions', width: 150,
    render(row: EditableRow) {
      if (row.editing) return h(NSpace, { size: 'small' }, { default: () => [
        h(NButton, { size: 'small', type: 'primary', onClick: () => saveEdit(row) }, { default: () => '保存' }),
        h(NButton, { size: 'small', onClick: () => cancelEdit(row) }, { default: () => '取消' })
      ]})
      return h(NButton, { size: 'small', tertiary: true, onClick: () => startEdit(row) }, { default: () => '编辑' })
    }
  }
]
</script>

<template>
  <n-data-table :columns="columns" :data="data" />
</template>
```

### 18.3 虚拟滚动——10000 行也不卡

```vue
<template>
  <n-data-table
    :columns="columns"
    :data="bigData"
    :max-height="500"         <!-- 必须设固定高度 -->
    :virtual-scroll="true"
    bordered striped
  />
</template>
```

> ⚠️ **虚拟滚动三要素：** `max-height` + `virtual-scroll` + 每行高度一致。缺任何一个都会导致异常。

### 18.4 导出 CSV / Excel

> 💡 前端导出不需要后端配合。用纯 JS 就能把表格数据导出为 CSV 文件，用户可以直接用 Excel 打开。

```ts
// src/utils/exportCsv.ts
/**
 * 将二维数组数据导出为 CSV 文件下载
 * @param filename 文件名（不含扩展名）
 * @param headers 表头数组
 * @param rows 数据行（二维数组）
 */
export function exportCsv(filename: string, headers: string[], rows: any[][]) {
  // 拼接 CSV 内容：表头 + 数据行
  const csvContent = [
    headers.join(','),
    ...rows.map(row => row.map(cell => `"${String(cell ?? '').replace(/"/g, '""')}"`).join(','))
  ].join('\n')

  // 添加 BOM 头，确保 Excel 正确识别中文
  const blob = new Blob(['\uFEFF' + csvContent], { type: 'text/csv;charset=utf-8;' })
  const url = URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url
  a.download = `${filename}.csv`
  a.click()
  URL.revokeObjectURL(url)
}
```

```vue
<!-- 在表格页面中使用 -->
<script setup lang="ts">
import { NButton } from 'naive-ui'
import { exportCsv } from '@/utils/exportCsv'

const headers = ['ID', '姓名', '年龄', '邮箱', '状态']
const rows = data.map(u => [u.id, u.name, u.age, u.email, u.status])

function handleExport() {
  exportCsv('用户列表', headers, rows)
}
</script>

<template>
  <n-button @click="handleExport">导出 CSV</n-button>
</template>
```

### 18.5 列拖拽排序

```vue
<script setup lang="ts">
import { NDataTable } from 'naive-ui'
import { ref } from 'vue'
import type { DataTableColumns } from 'naive-ui'

// 列顺序由 columns 数组的顺序决定
// 要实现拖拽，将 columns 用 ref 管理，拖拽时交换数组元素
const columns = ref<DataTableColumns<any>>([
  { title: 'ID', key: 'id', width: 80, resizable: true },
  { title: '姓名', key: 'name', width: 120, resizable: true },
  { title: '邮箱', key: 'email', width: 200, resizable: true }
  // resizable: true 表示列宽可拖拽调整
])
</script>
```

> 💡 Naive UI 内置了列宽拖拽（`resizable`），列顺序可通过操作 columns 数组实现。

> ⚠️ **本章踩坑小结：**
> 1. 列配置里的 `key` 必须和 data 中字段名**完全一致**，否则那列显示空白。
> 2. `render` 函数里用的组件必须已在文件顶部 import。
> 3. 虚拟滚动必须同时满足 `max-height` + `virtual-scroll` + 固定行高三个条件。
> 4. 导出 CSV 时记得加 BOM 头（`\uFEFF`），否则 Excel 打开中文乱码。

> 📝 **本章回顾：** NDataTable 是最复杂的组件之一。columns + data 是核心，render 用 h() 函数，虚拟滚动解决大数据量问题，导出用纯 JS 即可。

---

## 第19章 树形组件与树形下拉组件

> **📖 学习目标：** 掌握 NTree 和 NTreeSelect 的用法。

### 19.1 NTree——树形组件

```vue
<script setup lang="ts">
import { NTree, NSpace, NText } from 'naive-ui'
import { ref } from 'vue'
import type { TreeOption } from 'naive-ui'

const checkedKeys = ref<string[]>([])
const expandedKeys = ref<string[]>(['frontend'])

const treeData: TreeOption[] = [
  {
    label: '前端技术', key: 'frontend', children: [
      { label: 'Vue.js', key: 'vue' },
      { label: 'React', key: 'react' },
      { label: '构建工具', key: 'build', children: [
        { label: 'Vite', key: 'vite' },
        { label: 'Webpack', key: 'webpack' }
      ]}
    ]
  },
  { label: '后端技术', key: 'backend', children: [
    { label: 'Node.js', key: 'node' },
    { label: 'Go', key: 'go' }
  ]}
]
</script>

<template>
  <n-space vertical>
    <n-tree
      :data="treeData"
      :checked-keys="checkedKeys"
      :expanded-keys="expandedKeys"
      selectable checkable cascade check-strategy="child"
      @update:checked-keys="checkedKeys = $event"
    />
    <n-text depth="3">已选中: {{ checkedKeys.join(', ') || '无' }}</n-text>
  </n-space>
</template>
```

> ⚠️ **树形组件的 key 必须唯一！** 每个节点的 `key` 在整个树中不能重复。即使不同树枝下的两个节点有相同的 key，也会导致勾选/展开状态混乱。

### 19.2 NTreeSelect——树形下拉

```vue
<template>
  <n-tree-select v-model:value="selected" :options="treeSelectOptions" placeholder="请选择部门" filterable clearable />
</template>
```

> 📝 **本章回顾：** NTree 用于树形数据展示和选择，NTreeSelect 是带下拉的树形选择器。key 的全局唯一性是最关键的注意点。

---

## 第20章 列表、头像、进度条、数值统计、评分组件

> **📖 学习目标：** 掌握几个高频的数据展示组件。

### 20.1 NAvatar + NBadge——头像和角标

```vue
<template>
  <n-space align="center" :size="16">
    <n-avatar :size="48" src="https://api.dicebear.com/7.x/initials/svg?seed=admin" />
    <n-avatar round :size="48" color="#18A058">张</n-avatar>
    <n-badge dot type="success">
      <n-avatar round :size="48" color="#2080F0">李</n-avatar>
    </n-badge>
  </n-space>
</template>
```

### 20.2 NProgress——进度条

```vue
<template>
  <n-space vertical>
    <n-progress type="line" :percentage="65" />
    <n-progress type="line" :percentage="100" status="success" />
    <n-progress type="circle" :percentage="75" />
    <n-progress type="line" :percentage="65" :indicator-placement="'inside'" :height="20" />
  </n-space>
</template>
```

### 20.3 NRate——评分

```vue
<template>
  <n-space vertical>
    <n-rate v-model:value="rate" :count="5" clearable />
    <n-text v-if="rateText" depth="3">你的评分：{{ rateText }}</n-text>
  </n-space>
</template>
```

> 📝 **本章回顾：** NAvatar 支持图片和文字头像，NProgress 支持线形/环形/仪表盘，NRate 是星级评分组件。

---

# 第六篇章 全局交互与反馈组件

> **🎯 本篇你将学会：**
> - useMessage / useDialog / useNotification 三种全局反馈 API 的使用
> - 消息队列管理与路由切换自动关闭
> - NSpin 加载遮罩、NWatermark 水印、NPopconfirm 气泡确认框
> - 分页组件的高阶封装与业务适配

## 第21章 消息提示、弹窗确认、通知弹窗全局 API

> **📖 学习目标：** 掌握 useMessage、useDialog、useNotification 的调用方式及消息队列管理。

### 21.1 useMessage——顶部弹出的消息条

```vue
<script setup lang="ts">
import { useMessage, NButton, NSpace } from 'naive-ui'

const message = useMessage()

function showMessages() {
  message.success('操作成功！')
  message.info('这是一条提示')
  message.warning('请注意')
  message.error('操作失败')
}

function showLoadingMessage() {
  const m = message.loading('处理中...', { duration: 0 })
  setTimeout(() => { m.type = 'success'; m.content = '处理完成！' }, 3000)
}
</script>

<template>
  <n-space>
    <n-button @click="showMessages">显示各类消息</n-button>
    <n-button @click="showLoadingMessage">加载消息（3s后变成功）</n-button>
  </n-space>
</template>
```

> ⚠️ **useMessage 最大的坑：必须在 setup 里调用！** 
> 如果你在普通函数里（比如在 axios 拦截器里）调用 `useMessage()`，会报错：
> `"Cannot read properties of null (reading 'useDialog')"`
> 
> **解决办法：** 在 setup 里调用 `useMessage()`，把返回的 `message` 对象通过参数传给函数，或者用 Pinia store 存起来。

### 21.2 消息队列管理 + 路由切换自动关闭

> 💡 实际开发中，你可能在短时间内触发多条消息（例如批量操作），而路由切换时残留的旧消息不应该继续显示。

```ts
// src/composables/useMessageQueue.ts
import { useMessage } from 'naive-ui'
import { onBeforeUnmount } from 'vue'
import type { MessageApi, MessageReactive } from 'naive-ui'

/**
 * 消息队列管理——支持批量消息和自动清理
 */
export function useMessageQueue() {
  const msg = useMessage()
  const activeMessages = new Set<MessageReactive>()

  // 创建消息并跟踪
  function show(type: 'success' | 'info' | 'warning' | 'error', content: string) {
    const m = msg[type](content, {
      duration: 3000,
      onAfterLeave: () => activeMessages.delete(m)  // 消失后从集合移除
    })
    activeMessages.add(m)
    return m
  }

  // 清除所有活动消息（路由切换时调用）
  function clearAll() {
    activeMessages.forEach(m => m.destroy())
    activeMessages.clear()
  }

  // 组件卸载时自动清除
  onBeforeUnmount(() => clearAll())

  return { show, clearAll }
}
```

```vue
<!-- 在页面组件中使用 -->
<script setup lang="ts">
import { useMessageQueue } from '@/composables/useMessageQueue'
import { onBeforeRouteLeave } from 'vue-router'

const { show, clearAll } = useMessageQueue()

// 路由离开前清除所有消息
onBeforeRouteLeave(() => { clearAll(); return true })
</script>
```

### 21.3 useDialog——弹窗确认框

```vue
<script setup lang="ts">
import { useDialog, NButton, NSpace, useMessage } from 'naive-ui'

const dialog = useDialog()
const msg = useMessage()

function showDeleteConfirm() {
  dialog.warning({
    title: '确认删除',
    content: '删除后数据不可恢复，确定继续？',
    positiveText: '确认删除',
    negativeText: '取消',
    onPositiveClick: () => msg.success('已删除'),
    onNegativeClick: () => msg.info('已取消')
  })
}
</script>
```

### 21.4 useNotification——右侧弹出的通知

```vue
<script setup lang="ts">
import { useNotification, NButton } from 'naive-ui'

const notification = useNotification()

function showNotification() {
  notification.success({
    title: '操作成功',
    content: '文件已成功上传至服务器',
    meta: '刚刚',
    duration: 5000
  })
}
</script>
```

> 💡 **消息、弹窗、通知，我该用哪个？**
> - **Message（顶部消息条）：** 最轻量，操作结果即时反馈
> - **Dialog（弹窗确认框）：** 需要用户确认才继续
> - **Notification（右侧通知）：** 重要但非阻塞的通知

> 📝 **本章回顾：** useMessage 最轻量（操作反馈），useDialog 需确认（删除等），useNotification 非阻塞通知。三者都必须在 setup 内调用。消息队列管理可避免路由切换后的残留消息。

---

## 第22章 加载遮罩、水印、气泡确认框

### 22.1 NSpin——加载遮罩

```vue
<template>
  <n-switch v-model:value="loading" /> 切换加载
  <n-spin :show="loading" description="数据加载中...">
    <n-card title="内容区域" style="max-width: 400px">
      加载中时这个区域会被遮罩覆盖
    </n-card>
  </n-spin>
</template>
```

### 22.2 NWatermark——水印

```vue
<template>
  <n-watermark content="机密文件" :font-size="16" :rotate="-22">
    <div style="height: 300px; padding: 20px; border: 1px solid #e8e8e8">
      <h3>受保护的内容</h3>
      <p>截图也会带上水印文字。</p>
    </div>
  </n-watermark>
</template>
```

### 22.3 NPopconfirm——气泡确认框

```vue
<template>
  <n-popconfirm @positive-click="() => msg.success('已删除')">
    <template #trigger><n-button type="error">删除</n-button></template>
    确认要永久删除这条记录吗？
  </n-popconfirm>
</template>
```

> 📝 **本章回顾：** NSpin 用于加载遮罩，NWatermark 用于安全保护，NPopconfirm 用于轻量确认（比 Dialog 更轻）。

---

## 第23章 分页组件高阶封装与业务适配

### 23.1 NPagination 基础

```vue
<template>
  <n-pagination
    :page="currentPage"
    :page-size="10"
    :item-count="200"
    show-size-picker
    show-quick-jumper
    @update:page="currentPage = $event"
  />
</template>
```

### 23.2 通用分页 Hooks

```ts
// src/composables/usePagination.ts
import { reactive, computed } from 'vue'

export function usePagination(defaultPageSize = 10) {
  const pagination = reactive({
    page: 1,
    pageSize: defaultPageSize,
    itemCount: 0,
    showSizePicker: true,
    pageSizes: [10, 20, 30, 50],
    showQuickJumper: true,
    onChange: (page: number) => { pagination.page = page },
    onUpdatePageSize: (pageSize: number) => {
      pagination.pageSize = pageSize
      pagination.page = 1  // 关键：切换每页条数时回到第1页
    }
  })

  const totalPages = computed(() => Math.ceil(pagination.itemCount / pagination.pageSize))

  function setTotal(n: number) { pagination.itemCount = n }
  function resetPage() { pagination.page = 1 }

  return { pagination, totalPages, setTotal, resetPage }
}
```

> ⚠️ **分页最容易踩的坑：** 切换每页条数后，`page` 不会自动回到 1——你需要自己在 `onUpdatePageSize` 里设。搜索/筛选后也需要调用 `resetPage()`。

> 📝 **本章回顾：** 分页组件通过 onChange 和 onUpdatePageSize 控制。封装 usePagination hooks 可复用分页逻辑。搜索/筛选后别忘了回第1页。

---

# 第七篇章 主题定制与样式深度改造（Naive UI 核心特色）

> **🎯 本篇你将学会：**
> - Naive UI 主题系统的 CSS 变量底层原理
> - 浅色主题自定义和暗黑模式切换
> - 主题编辑器使用
> - **新增！** CSS 深度定制技巧（:deep() 穿透、CSS Module、Tailwind 共存、自定义动画、毛玻璃、打印样式）
> - **新增！** 设计系统构建（品牌色→Design Token、多套主题切换、间距/阴影体系）

## 第24章 Naive UI 主题系统底层原理

### 24.1 一句话说清楚主题系统

> Naive UI 的所有颜色、圆角、字号等视觉参数都存储在 **CSS 变量（CSS Variables）** 中。修改变量 = 改变外观。

```
CSS 变量长这样：             --n-primary-color: #18A058;
组件源码里是这样用的：        background-color: var(--n-primary-color);
你想换主题色？把值改了就行：  --n-primary-color: #ff0000;
```

### 24.2 主题作用域层级

```
NConfigProvider（最外层全局主题）
  └── NConfigProvider（里层，可以局部覆盖）
      └── 单个组件 theme-overrides（最细粒度）
```

> 💡 这个层级意味着：你可以全局设一个默认主题，然后在某个页面用里层的 NConfigProvider 覆盖为"红色主题"，不影响其他页面。

> 📝 **本章回顾：** 主题系统基于 CSS 变量，通过 NConfigProvider 实现层级作用域控制。

---

## 第25章 浅色主题自定义与全局样式修改

```vue
<script setup lang="ts">
import { NConfigProvider, NButton, NCard } from 'naive-ui'
import type { GlobalThemeOverrides } from 'naive-ui'

const myTheme: GlobalThemeOverrides = {
  common: {
    primaryColor: '#18A058',
    primaryColorHover: '#36AD6A',
    borderRadius: '6px',
    fontSize: '14px',
    textColor1: '#1F2937',
    textColor2: '#6B7280',
    textColor3: '#9CA3AF',
    borderColor: '#E5E7EB'
  },
  Button: { borderRadius: '6px', heightMedium: '36px' },
  Card: { borderRadius: '8px', paddingMedium: '24px' },
  Input: {
    borderRadius: '6px',
    border: '1px solid #D1D5DB',
    borderFocus: '1px solid #18A058',
    boxShadowFocus: '0 0 0 2px rgba(24,160,88,0.2)'
  }
} as const
</script>

<template>
  <n-config-provider :theme-overrides="myTheme">
    <n-button type="primary">绿色按钮</n-button>
    <n-card title="自定义主题">这个卡片用了 8px 圆角和 24px 内边距</n-card>
  </n-config-provider>
</template>
```

> 📝 **本章回顾：** theme-overrides 对象分 common（全局）和组件级（Button/Card 等）两种粒度。

---

## 第26章 暗黑模式开发与明暗主题无缝切换

```vue
<script setup lang="ts">
import { NConfigProvider, darkTheme } from 'naive-ui'
import { ref, computed } from 'vue'

const isDark = ref(false)
const currentTheme = computed(() => isDark.value ? darkTheme : null)

const darkOverrides = {
  common: {
    bodyColor: '#101014',
    cardColor: '#1E1E24',
    textColor1: '#E5E7EB',
    textColor2: '#D1D5DB',
    textColor3: '#9CA3AF',
    borderColor: '#2D2D36',
    primaryColor: '#63E2B7'
  }
}
</script>

<template>
  <n-config-provider :theme="currentTheme" :theme-overrides="isDark ? darkOverrides : undefined">
    <n-switch v-model:value="isDark">
      <template #checked>🌙 暗黑</template>
      <template #unchecked>☀️ 浅色</template>
    </n-switch>
  </n-config-provider>
</template>
```

> 💡 **暗黑模式持久化：** 把 `isDark` 存到 `localStorage`，下次打开时读回。参考 Pinia 主题 Store：`localStorage.getItem('theme') === 'dark'`。

### 26.1 Pinia 主题 Store

```ts
// src/stores/theme.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useThemeStore = defineStore('theme', () => {
  const isDark = ref(localStorage.getItem('theme') === 'dark')

  function toggleTheme() {
    isDark.value = !isDark.value
    localStorage.setItem('theme', isDark.value ? 'dark' : 'light')
  }

  return { isDark, toggleTheme }
})
```

> 📝 **本章回顾：** darkTheme 是 Naive UI 内置的暗黑主题对象。配合 localStorage 和 Pinia 可实现持久化的主题偏好。暗黑模式下需要对文字颜色、边框等做专属覆盖。

---

## 第27章 官方主题编辑器零基础使用教程

> 💡 Naive UI 提供了一个**可视化主题编辑器**：
> **地址：** https://www.naiveui.com/zh-CN/os-theme

### 使用步骤：

1. 访问上述地址
2. 左侧选择组件（Button、Card、Input…）
3. 右侧调整颜色/圆角/字号，**实时预览**
4. 调好后点击「导出」
5. 把导出的 JSON 对象复制到项目的 `theme-overrides` 里

> ⚠️ 编辑器和实际写代码用的变量名**完全一致**，你在编辑器里改了什么，复制出来就是这段代码。

> 📝 **本章回顾：** 主题编辑器是零代码定制主题的最快方式。导出 JSON → 复制到项目 → 完成。

---

## 第28章 局部主题覆盖、单组件独立样式定制

### 28.1 单个组件覆盖（theme-overrides 属性）

```vue
<template>
  <n-button type="primary" :theme-overrides="{ borderRadius: '20px', color: '#8B5CF6', colorHover: '#A78BFA' }">
    紫色圆角按钮（只影响我）
  </n-button>
  <n-button type="primary">普通按钮</n-button>
</template>
```

### 28.2 嵌套 NConfigProvider 局部覆盖

```vue
<template>
  <n-config-provider :theme-overrides="{ common: { primaryColor: '#2080F0' } }">
    <n-button type="primary">蓝色按钮</n-button>
    <n-config-provider :theme-overrides="{ common: { primaryColor: '#D03050' } }">
      <n-button type="primary">红色按钮（仅此层）</n-button>
    </n-config-provider>
  </n-config-provider>
</template>
```

### 28.3 CSS 深度定制——从覆盖到重构（本章核心新增）

#### 28.3.1 :deep() 穿透 scoped 的完整选择器优先级链

```vue
<style scoped>
/*
  问题：scoped 样式无法穿透到 Naive UI 组件内部
  原因：Vue 给当前组件加了一个 data-v-xxxx 属性，但 Naive UI 组件内部没有这个属性
  解决：用 :deep() 穿透
*/

/* ❌ 无效——scoped 不会穿透到子组件 */
.n-button.n-button--primary-type { background: red; }

/* ✅ 一条规则穿透 */
:deep(.n-button.n-button--primary-type) { background: red; }

/* ✅ 多级穿透——当需要穿透多层子组件时 */
:deep(.n-card) :deep(.n-card-header) { background: #f5f5f5; }

/* ✅ 使用 css 选择器组合提高优先级 */
:deep(.n-button.n-button--primary-type:not(.n-button--disabled)) {
  background: linear-gradient(135deg, #667eea, #764ba2);
  border: none;
  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
}
</style>
```

> 💡 **什么时候用 :deep() 什么时候用 theme-overrides？**
> - `theme-overrides`：能覆盖的变量，优先用它（稳定、类型安全）
> - `:deep()`：theme-overrides 覆盖不了的样式（渐变背景、阴影、动画等），作为最后手段

#### 28.3.2 自定义动画与过渡效果

```vue
<style scoped>
/* ===== 按钮点击涟漪效果 ===== */
:deep(.n-button.n-button--primary-type) {
  position: relative;
  overflow: hidden;
  transition: all 0.3s ease;
}

:deep(.n-button.n-button--primary-type:hover) {
  transform: translateY(-2px);
  box-shadow: 0 6px 20px rgba(24, 160, 88, 0.3);
}

:deep(.n-button.n-button--primary-type:active) {
  transform: translateY(0);
}

/* ===== 卡片入场动画 ===== */
.fade-enter-active {
  animation: cardEnter 0.4s ease-out;
}

@keyframes cardEnter {
  from { opacity: 0; transform: translateY(20px); }
  to   { opacity: 1; transform: translateY(0); }
}

/* ===== 弹窗入场动画覆盖 ===== */
:deep(.n-modal) {
  animation: modalSlideIn 0.3s ease-out;
}

@keyframes modalSlideIn {
  from { opacity: 0; transform: scale(0.95) translateY(-10px); }
  to   { opacity: 1; transform: scale(1) translateY(0); }
}
</style>
```

#### 28.3.3 毛玻璃卡片（Glassmorphism）

> 💡 毛玻璃是近年来非常流行的设计风格——半透明背景 + 模糊滤镜 + 细边框。

```vue
<template>
  <!-- 毛玻璃版本卡片 -->
  <n-card
    class="glass-card"
    title="毛玻璃卡片"
    :bordered="false"
  >
    <p>背景会被模糊处理，形成毛玻璃效果。</p>
    <p>这个效果在暗色背景下尤其好看。</p>
  </n-card>
</template>

<style scoped>
.glass-card {
  /* 半透明白色背景 */
  background: rgba(255, 255, 255, 0.15) !important;
  /* 背景模糊——毛玻璃核心 */
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  /* 细边框增强层次感 */
  border: 1px solid rgba(255, 255, 255, 0.3) !important;
  border-radius: 16px;
}

/* 暗黑模式下的毛玻璃适配 */
:root .dark .glass-card {
  background: rgba(30, 30, 40, 0.6) !important;
  border: 1px solid rgba(255, 255, 255, 0.1) !important;
}
</style>
```

#### 28.3.4 自定义滚动条样式

```vue
<style scoped>
/* 自定义滚动条——全局生效 */
::-webkit-scrollbar {
  width: 6px;
  height: 6px;
}

::-webkit-scrollbar-track {
  background: transparent;
}

::-webkit-scrollbar-thumb {
  background: rgba(0, 0, 0, 0.15);
  border-radius: 3px;
}

::-webkit-scrollbar-thumb:hover {
  background: rgba(0, 0, 0, 0.25);
}

/* 暗黑模式滚动条 */
.dark ::-webkit-scrollbar-thumb {
  background: rgba(255, 255, 255, 0.15);
}

.dark ::-webkit-scrollbar-thumb:hover {
  background: rgba(255, 255, 255, 0.25);
}
</style>
```

#### 28.3.5 CSS Module 与 Naive UI 的配合

```vue
<template>
  <div :class="$style.container">
    <n-button type="primary" :class="$style.customBtn">CSS Module 按钮</n-button>
  </div>
</template>

<style module>
.container {
  padding: 24px;
}

/* CSS Module 自动生成唯一类名，配合 :global 穿透到 Naive UI */
.customBtn:global(.n-button--primary-type) {
  /* 这里的样式可以覆盖 Naive UI 内部 */
  border-radius: 12px;
}
</style>
```

#### 28.3.6 Tailwind CSS 与 Naive UI 的共存方案

```bash
# 安装 Tailwind CSS
pnpm add -D tailwindcss @tailwindcss/vite
```

```ts
// vite.config.ts —— Tailwind 与 Naive UI 共存
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [vue(), tailwindcss()]
})
```

```vue
<!-- Tailwind 和 Naive UI 和谐共存 -->
<template>
  <div class="p-6 bg-gray-50 dark:bg-gray-900 min-h-screen">
    <!-- 用 Tailwind 做外层布局，Naive UI 做交互组件 -->
    <n-card title="Dashboard" class="shadow-lg">
      <n-button type="primary" class="mt-4">
        提交
      </n-button>
    </n-card>
  </div>
</template>
```

> 💡 **Tailwind + Naive UI 最佳实践：**
> - 外层布局用 Tailwind（间距、背景、响应式）
> - 交互组件用 Naive UI（按钮、表格、弹窗）
> - Naive UI 的样式不会被 Tailwind 的 reset 影响（因为 Naive UI 用了 CSS 变量 + scoped）

#### 28.3.7 打印样式适配

```vue
<style scoped>
/* 打印时隐藏不需要的元素 */
@media print {
  /* 隐藏侧边栏和头部 */
  .sidebar,
  .header,
  .n-layout-sider,
  .n-layout-header {
    display: none !important;
  }

  /* 内容区满宽 */
  .n-layout-content {
    padding: 0 !important;
    margin: 0 !important;
  }

  /* 表格边框打印 */
  .n-data-table {
    border: 1px solid #000 !important;
  }

  /* 按钮不打印（除非特别需要） */
  .n-button { display: none !important; }

  /* 弹窗和遮罩不打印 */
  .n-modal,
  .n-modal-mask { display: none !important; }
}
</style>
```

### 28.4 设计系统构建——品牌色体系与 Design Token（本章核心新增）

> 💡 设计系统（Design System）不是大厂的专利。即使你一个人开发，建立一套简单的 Design Token 体系，也能让主题维护成本降低 80%。

#### 28.4.1 从品牌 VI 到 Naive UI 主题变量的完整映射

```ts
// src/theme/tokens.ts —— Design Token 定义
/**
 * 设计系统的核心：一个 JSON 对象，定义所有视觉参数
 * 品牌色、间距、阴影、字号全在这里
 */
export const designTokens = {
  // 品牌色（从 VI 手册提取）
  brand: {
    primary: '#4F46E5',       // Indigo-600（主品牌色）
    primaryLight: '#818CF8',  // Indigo-400
    primaryDark: '#3730A3',   // Indigo-800
    secondary: '#10B981',     // Emerald-500（辅助色）
    danger: '#EF4444',        // Red-500
    warning: '#F59E0B',       // Amber-500
    info: '#3B82F6'           // Blue-500
  },

  // 间距系统（基于 4px 基准）
  spacing: {
    xs: 4, sm: 8, md: 16, lg: 24, xl: 32, xxl: 48
  },

  // 阴影层级
  shadow: {
    sm: '0 1px 2px rgba(0,0,0,0.05)',
    md: '0 4px 6px rgba(0,0,0,0.07)',
    lg: '0 10px 25px rgba(0,0,0,0.1)',
    xl: '0 20px 50px rgba(0,0,0,0.15)'
  },

  // 字阶体系
  font: {
    xs: '12px', sm: '13px', base: '14px', md: '16px', lg: '20px', xl: '24px', xxl: '32px'
  },

  // 圆角
  radius: {
    sm: '4px', md: '6px', lg: '8px', xl: '12px', full: '9999px'
  }
}

// ===== 将 Design Token 转化为 Naive UI 可用的 theme-overrides =====
import type { GlobalThemeOverrides } from 'naive-ui'

export function tokensToNTheme(tokens: typeof designTokens, isDark = false): GlobalThemeOverrides {
  const { brand, shadow, font, radius } = tokens
  return {
    common: {
      primaryColor: brand.primary,
      primaryColorHover: brand.primaryLight,
      primaryColorPressed: brand.primaryDark,
      infoColor: brand.info,
      successColor: brand.secondary,
      warningColor: brand.warning,
      errorColor: brand.danger,
      borderRadius: radius.md,
      fontSize: font.base,
      fontSizeSmall: font.xs,
      fontSizeMedium: font.md,
      fontSizeLarge: font.lg,
      // 暗黑模式下的特殊值
      ...(isDark ? {
        bodyColor: '#0F111A',
        cardColor: '#1A1C29',
        textColor1: '#E5E7EB',
        textColor2: '#D1D5DB',
        textColor3: '#9CA3AF',
        borderColor: '#2D3042'
      } : {})
    },
    Card: {
      borderRadius: radius.lg,
      paddingMedium: '24px',
      boxShadow: shadow.sm
    }
  }
}
```

#### 28.4.2 多套主题无缝切换

```ts
// src/theme/themes.ts
import { tokensToNTheme, designTokens } from './tokens'

// 品牌 A（默认 Indigo 主题）
export const themeA = tokensToNTheme(designTokens, false)
export const themeADark = tokensToNTheme({
  ...designTokens,
  brand: { ...designTokens.brand, primary: '#818CF8', primaryLight: '#A5B4FC', primaryDark: '#6366F1' }
}, true)

// 品牌 B（绿色主题——不同客户用不同配色）
const greenTokens = { ...designTokens, brand: { ...designTokens.brand, primary: '#059669', primaryLight: '#34D399', primaryDark: '#047857' } }
export const themeB = tokensToNTheme(greenTokens, false)

// 品牌 C（橙色主题）
const orangeTokens = { ...designTokens, brand: { ...designTokens.brand, primary: '#EA580C', primaryLight: '#FB923C', primaryDark: '#C2410C' } }
export const themeC = tokensToNTheme(orangeTokens, false)
```

```vue
<!-- 品牌主题切换组件 -->
<script setup lang="ts">
import { NConfigProvider, NSelect } from 'naive-ui'
import { ref, computed } from 'vue'
import { themeA, themeB, themeC } from '@/theme/themes'

const currentBrand = ref<'A' | 'B' | 'C'>('A')
const themeMap = { A: themeA, B: themeB, C: themeC }
const currentTheme = computed(() => themeMap[currentBrand.value])
</script>

<template>
  <n-config-provider :theme-overrides="currentTheme">
    <n-select v-model:value="currentBrand" :options="[
      { label: '品牌 A (Indigo)', value: 'A' },
      { label: '品牌 B (Green)', value: 'B' },
      { label: '品牌 C (Orange)', value: 'C' }
    ]" />
  </n-config-provider>
</template>
```

> ⚠️ **CSS 覆盖的风险：** Naive UI 的 CSS 类名虽然稳定，但大版本升级时仍可能变化。优先用 `theme-overrides`，CSS 覆盖（`:deep()`）作为**最后手段**。

> 📝 **本章回顾：** 局部覆盖可用组件级 theme-overrides 或嵌套 NConfigProvider。CSS 深度定制用 :deep()、自定义动画、毛玻璃等。Design Token 体系使主题维护更系统化，多品牌切换只需换一套 Token 对象。

---

# 第八篇章 工程化配置与性能优化

> **🎯 本篇你将学会：**
> - Vite 自动按需引入配置和分包策略
> - TypeScript 类型系统全覆盖
> - 大数据场景性能优化（虚拟滚动、shallowRef）
> - 项目规范、组件封装、工具函数抽离

## 第29章 自动按需引入与打包体积优化

```ts
// 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'
import { resolve } from 'path'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({ imports: ['vue', 'vue-router', 'pinia'], dts: 'src/auto-imports.d.ts' }),
    Components({ resolvers: [NaiveUiResolver()], dts: 'src/components.d.ts' })
  ],
  resolve: { alias: { '@': resolve(__dirname, 'src') } },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'naive': ['naive-ui'],
          'vue-vendor': ['vue', 'vue-router', 'pinia'],
          'icons': ['@vicons/ionicons5']
        }
      }
    }
  }
})
```

> 💡 **分包的作用：** 浏览器可以缓存大文件。用户第二次打开时，`naive.js` 不会被重新下载（内容没变），只下载业务代码——加载速度提升。

> 📝 **本章回顾：** 自动按需引入用 unplugin 插件，分包策略用 manualChunks 把大库拆出去。

---

## 第30章 TypeScript 类型系统全覆盖配置

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "preserve",
    "paths": { "@/*": ["./src/*"] },
    "types": ["naive-ui/volar"]
  }
}
```

### 所有可用的类型导入

```ts
// 实例类型
import type { InputInst, ButtonInst, DataTableInst, FormInst, SelectInst, UploadInst } from 'naive-ui'
// 配置类型
import type { GlobalThemeOverrides, FormRules } from 'naive-ui'
// 数据类型
import type { DataTableColumns, SelectOption, TreeOption, MenuOption, UploadFileInfo } from 'naive-ui'
```

> 📝 **本章回顾：** strict: true 开启严格类型检查，types: ["naive-ui/volar"] 启用 Volar 类型增强。

---

## 第31章 大数据场景性能优化方案

### 31.1 三条最重要的优化原则

1. **虚拟滚动**：超过 100 行的表格，开 `virtual-scroll`。
2. **shallowRef**：大数据量不用深层响应，用 `shallowRef` 代替 `ref`。
3. **computed 预先过滤**：不要在模板里直接写 `.filter()`。

```ts
// ❌ ref：对数组中每个对象都做响应式处理（慢）
const bigList = ref([...])

// ✅ shallowRef：只监听数组整体的替换（快）
const bigList = shallowRef([...])
// 更新时替换整个数组
bigList.value = newData
```

> 📝 **本章回顾：** 虚拟滚动（表格 > 100 行）+ shallowRef（大数据列表）+ computed（提前过滤）是性能优化的三把斧。

---

## 第32章 项目规范、组件封装、全局工具抽离

### 32.1 推荐目录结构

```
src/
├── api/               # axios 实例 + 业务模块
├── components/        # 通用业务组件
├── composables/       # usePagination.ts, useForm.ts
├── layouts/           # 布局组件
├── router/            # 路由
├── stores/            # Pinia
├── theme/             # 主题 Token
├── types/             # 全局类型
├── utils/             # format.ts, validate.ts, exportCsv.ts
└── views/             # 页面
```

### 32.2 统一导入 Naive UI

```ts
// src/utils/naive.ts
export { NButton, NInput, NSelect, NDataTable, NForm, NFormItem } from 'naive-ui'
export type { DataTableColumns, FormRules, FormInst } from 'naive-ui'
export { useMessage, useDialog, useNotification } from 'naive-ui'
```

> 📝 **本章回顾：** 清晰的项目结构 + 统一导入入口 + 通用工具函数是工程化的基础。

---

# 第九篇章 企业级完整项目实战

> **🎯 本篇你将学会：**
> - 从零搭建后台管理系统项目骨架
> - 布局 + 路由权限 + 暗黑模式 + Pinia 状态管理
> - 通用列表页（搜索/筛选/分页/批量操作/删除/编辑）
> - 弹窗表单新增/编辑业务
> - 文件上传、图片预览、水印封装

## 第33章 后台管理系统项目骨架搭建

```bash
pnpm create vue@latest admin-pro -- --typescript
cd admin-pro
pnpm add naive-ui @vicons/ionicons5 vfonts
pnpm add vue-router pinia axios dayjs
pnpm add -D unplugin-auto-import unplugin-vue-components @types/node
```

### 33.1 axios 封装

```ts
// src/api/request.ts
import axios from 'axios'
import type { AxiosInstance, AxiosResponse, InternalAxiosRequestConfig } from 'axios'

const service: AxiosInstance = axios.create({
  baseURL: import.meta.env.VITE_API_BASE || '/api',
  timeout: 15000
})

service.interceptors.request.use((config: InternalAxiosRequestConfig) => {
  const token = localStorage.getItem('token')
  if (token && config.headers) config.headers.Authorization = `Bearer ${token}`
  return config
})

service.interceptors.response.use(
  (res: AxiosResponse) => {
    if (res.data.code !== 0) return Promise.reject(new Error(res.data.message))
    return res.data.data
  },
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('token')
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)

export const get = <T>(url: string, params?: any) => service.get<any, T>(url, { params })
export const post = <T>(url: string, data?: any) => service.post<any, T>(url, data)
export const put = <T>(url: string, data?: any) => service.put<any, T>(url, data)
export const del = <T>(url: string) => service.delete<any, T>(url)
```

> 📝 **本章回顾：** 项目骨架 = 脚手架创建 + 依赖安装 + axios 封装 + 路由配置。axios 拦截器是统一处理 token 和错误的关键。

---

## 第34章 布局系统 + 路由权限 + 暗黑模式整合

> 💡 完整实现见第 16 章和第 26 章。三个核心点：
> - NLayout 系列构建骨架
> - Pinia 管理暗黑模式
> - 路由守卫处理登录和权限

---

## 第35章 通用列表页、搜索筛选、分页、删除、编辑实战

### 35.1 列表页完整流程（含批量操作）

> 核心流程：
> ```
> 页面进入 → fetchData()
>   → 搜索 → resetPage() → fetchData()
>   → 分页 → onChange → fetchData()
>   → 删除 → Popconfirm → API → fetchData()
>   → 批量删除 → checkedKeys → confirm → API → fetchData()
>   → 编辑 → router.push('/user/edit/:id')
> ```

```vue
<script setup lang="ts">
import { ref, onMounted, h } from 'vue'
import { useRouter } from 'vue-router'
import {
  NDataTable, NButton, NSpace, NTag, NPopconfirm, NInput, NSelect,
  useMessage, useDialog
} from 'naive-ui'
import type { DataTableColumns, DataTableRowKey } from 'naive-ui'

const router = useRouter()
const message = useMessage()
const dialog = useDialog()

interface User { id: number; name: string; email: string; status: 'active' | 'disabled'; role: string }

const tableData = ref<User[]>([])
const loading = ref(false)
const checkedRowKeys = ref<DataTableRowKey[]>([])

// 搜索条件
const searchForm = ref({ name: '', status: null as string | null })

// 分页
const page = ref(1)
const pageSize = ref(10)
const total = ref(0)

async function fetchData() {
  loading.value = true
  await new Promise(r => setTimeout(r, 300))
  tableData.value = Array.from({ length: pageSize.value }, (_, i) => ({
    id: (page.value - 1) * pageSize.value + i + 1,
    name: `用户${(page.value - 1) * pageSize.value + i + 1}`,
    email: `user${i}@example.com`,
    status: i % 3 === 0 ? 'disabled' : 'active',
    role: ['管理员', '编辑', '访客'][i % 3]
  }))
  total.value = 156
  loading.value = false
}

function handleSearch() { page.value = 1; fetchData() }
function handleReset() { searchForm.value = { name: '', status: null }; handleSearch() }
function handleDelete(id: number) { message.success(`已删除: ${id}`); fetchData() }

// ===== 批量删除 =====
function handleBatchDelete() {
  if (checkedRowKeys.value.length === 0) {
    message.warning('请选择要删除的项')
    return
  }
  dialog.warning({
    title: '批量删除',
    content: `确定删除已选的 ${checkedRowKeys.value.length} 条记录吗？`,
    positiveText: '确认删除',
    negativeText: '取消',
    onPositiveClick: () => {
      message.success(`已批量删除 ${checkedRowKeys.value.length} 条`)
      checkedRowKeys.value = []
      fetchData()
    }
  })
}

const columns: DataTableColumns<User> = [
  { type: 'selection' },  // 复选框列
  { title: 'ID', key: 'id', width: 80, sorter: (a, b) => a.id - b.id },
  { title: '姓名', key: 'name', width: 120 },
  { title: '邮箱', key: 'email', width: 200 },
  {
    title: '状态', key: 'status', width: 100,
    render(row) { return h(NTag, { type: row.status === 'active' ? 'success' : 'warning', size: 'small' }, { default: () => row.status === 'active' ? '启用' : '禁用' }) }
  },
  { title: '角色', key: 'role', width: 100 },
  {
    title: '操作', key: 'actions', width: 180,
    render(row) { return h(NSpace, { size: 'small' }, { default: () => [
      h(NButton, { size: 'small', tertiary: true, onClick: () => router.push(`/user/edit/${row.id}`) }, { default: () => '编辑' }),
      h(NPopconfirm, { onPositiveClick: () => handleDelete(row.id) }, {
        default: () => '确认删除？',
        trigger: () => h(NButton, { size: 'small', tertiary: true, type: 'error' }, { default: () => '删除' })
      })
    ]})}
  }
]

onMounted(() => fetchData())
</script>

<template>
  <div>
    <!-- 搜索 -->
    <n-card style="margin-bottom: 16px">
      <n-space align="center" wrap>
        <n-input v-model:value="searchForm.name" placeholder="搜索用户名" clearable style="width: 200px" />
        <n-select v-model:value="searchForm.status" :options="[{label:'全部',value:null},{label:'启用',value:'active'},{label:'禁用',value:'disabled'}]" style="width: 150px" clearable />
        <n-button type="primary" @click="handleSearch">搜索</n-button>
        <n-button @click="handleReset">重置</n-button>
      </n-space>
    </n-card>

    <!-- 操作栏 -->
    <n-space style="margin-bottom: 16px">
      <n-button type="primary" @click="router.push('/user/edit')">新增用户</n-button>
      <n-button type="error" @click="handleBatchDelete" :disabled="checkedRowKeys.length === 0">
        批量删除 {{ checkedRowKeys.length ? `(${checkedRowKeys.length})` : '' }}
      </n-button>
    </n-space>

    <!-- 表格 -->
    <n-data-table
      :columns="columns"
      :data="tableData"
      :loading="loading"
      :pagination="{ page, pageSize, itemCount: total, onChange: (p: number) => { page = p; fetchData() }, onUpdatePageSize: (s: number) => { pageSize = s; page = 1; fetchData() } }"
      :row-key="(row: User) => row.id"
      :checked-row-keys="checkedRowKeys"
      @update:checked-row-keys="checkedRowKeys = $event"
      bordered
    />
  </div>
</template>
```

> ⚠️ **列表页最易犯的错：** 搜索后忘记把分页重置为第 1 页。你如果停留在第 5 页搜索，后端返回的数据可能只有 1 页，表格就显示空白了。

> 📝 **本章回顾：** 列表页 = 搜索 + 操作栏 + 表格 + 分页。批量操作的核心是 checkedRowKeys + type: 'selection'。搜索后必须重置到第 1 页。

---

## 第36章 弹窗表单新增编辑业务场景落地

> 核心流程：
> - 新增：打开空表单弹窗 → 填写 → POST API → 刷新列表
> - 编辑：打开弹窗 → GET API 加载旧数据 → 修改 → PUT API → 刷新列表

> ⚠️ **编辑弹窗的坑：** 关闭弹窗后旧的表单数据可能残留——每次打开弹窗前重置 formData。

> 📝 **本章回顾：** 新增/编辑用同一个弹窗，通过路由参数 :id? 区分。打开弹窗前必须重置数据。

---

## 第37章 文件上传、图片预览、水印业务封装

> 见第 12 章和第 22 章。上传用 customRequest + beforeUpload，预览用 NImage lazy，水印用 NWatermark。

> 📝 **本章回顾：** 上传封装的要点是 customRequest（自定义请求）和 beforeUpload（前置检查）。水印通过 NWatermark 组件包裹内容区域实现。

---

# 第十篇章 疑难问题排查与实战踩坑手册

> **🎯 本篇你将学会：** 快速定位和解决 Naive UI 开发中最常见的错误和 bug。每个问题都附带排查思路。

## 第38章 环境安装与引入报错解决方案

| 错误现象 | 排查思路 | 解决办法 |
|---------|---------|---------|
| `Cannot find module 'naive-ui'` | 检查 node_modules 里有没有 naive-ui 目录 | `pnpm add naive-ui` |
| `[Vue warn]: Failed to resolve component: n-button` | 检查 script 里有没有 import，或 app.use 有没有调用 | import { NButton } from 'naive-ui' |
| `useDialog is not defined` | 是不是在 setup 外面调用了？比如在独立的 .ts 文件里 | 在 `<script setup>` 里调用，把返回值传出去 |
| Vite 启动报 `Error: Cannot find module` | `node -v` 检查 Node 版本 | Node.js >= 16 |
| 改了 `vite.config.ts` 后不生效 | Vite 不会热更新配置文件 | 重启 dev server（Ctrl+C → pnpm dev） |

---

## 第39章 样式失效、主题不生效、组件渲染异常解决

### 症状一：scoped 样式盖不住
> **排查思路：** 打开浏览器 DevTools，检查目标元素的 class 有没有被 Vue 的 data-v-xxx 属性限制。
> **解决：** 用 `:deep()` 穿透。

### 症状二：主题色改了但某些组件没变
> **排查思路：** 检查你要覆盖的 CSS 变量名是否拼写正确。该组件可能用的是自己的独立变量。
> **解决：** 查附录 B 确认变量名。

### 症状三：弹窗弹不出来 / 层级错乱
> **排查思路：** F12 检查 z-index，看是否有全局样式污染。
> **解决：** 检查全局 CSS 中是否有 `* { z-index: ... }` 之类的污染。

---

## 第40章 TypeScript 类型报错全量修复方案

```ts
// 报错1: 类型 "string" 不能赋给类型 "ButtonType"
// ❌ const btnType = 'primary'
// ✅ const btnType = 'primary' as const 或 import type { ButtonProps } from 'naive-ui'

// 报错2: DataTableColumns 参数类型错误
// ❌ const columns: DataTableColumns = [...]
// ✅ const columns: DataTableColumns<User> = [...]

// 报错3: ref 绑定实例类型报错
// ❌ const formRef = ref(null)
// ✅ const formRef = ref<FormInst | null>(null)
```

---

## 第41章 常见业务场景 bug 与兼容问题处理

### 表格相关
- **分页切换后位置没重置**：`tableRef.value?.scrollTo({ top: 0 })`
- **固定列后内容错位**：设 `width` + `minWidth`

### 表单相关
- **动态表单项校验不触发**：检查 path 拼接（`items[0].name`）
- **提交后校验没清**：`formRef.value?.restoreValidation()`

### 兼容性
| 浏览器 | 最低版本 | 备注 |
|--------|---------|------|
| Chrome | 64+ | ✅ 完全支持 |
| Firefox | 79+ | ✅ 完全支持 |
| Safari | 12.1+ | ✅ 完全支持 |
| IE | - | ❌ 不支持 |

> 📝 **本章回顾：** 排查问题遵循"检查环境 → 检查配置 → 检查代码 → 查文档"的顺序。TypeScript 报错多数是因为类型没标注或泛型没传。

---

# 第十一篇章 综合实战：天气查询工具完整项目

> **🎯 本篇你将学会：**
> - 如何从零分析一个前端项目的需求和技术选型
> - 调用免费 API（Open-Meteo）实现城市搜索、当前天气、7天预报
> - 用 Chart.js 画逐小时温度曲线图
> - 构建完整的错误处理、加载状态和空状态
> - 暗黑模式下天气卡片的自适应主题
> - 部署上线（Vercel 免费）

## 第42章 项目分析——从需求到 API 选型

### 42.1 我们要做什么？

一个**天气查询 Web 应用**，用户可以：
1. 输入城市名称搜索 → 显示候选城市列表
2. 选择城市后 → 显示当前天气（温度、湿度、风速、天气图标）
3. 下方展示 7 天天气预报（最高/最低温、天气、日出日落）
4. 一个逐小时的温度曲线图
5. 支持暗黑模式切换

### 42.2 API 选型：为什么用 Open-Meteo？

| 对比维度 | Open-Meteo | OpenWeatherMap | 和风天气 |
|---------|-----------|---------------|---------|
| 是否需要 API Key | ❌ 不需要 | ✅ 需要注册 | ✅ 需要注册 |
| 免费额度 | 无限制（非商业） | 60次/分钟 | 1000次/天 |
| 数据质量 | 基于 NOAA/DWD/ECMWF | 混合源 | 中国数据好 |
| 接口数量 | 覆盖全球 | 覆盖全球 | 主要覆盖中国 |
| 中文支持 | 城市名需英文 | 支持中文 | 支持中文 |

> 💡 选 Open-Meteo 的最大理由：**零门槛**——不需要注册、不需要 API Key、不需要绑信用卡，直接发 HTTP 请求就能用。非常适合教学和练手。

### 42.3 Open-Meteo API 详解

#### API 1：Geocoding（城市名 → 经纬度）

```
GET https://geocoding-api.open-meteo.com/v1/search?name={城市名}&count=5&language=zh
```

返回示例：
```json
{
  "results": [
    {
      "id": 1816670,
      "name": "北京",
      "latitude": 39.9042,
      "longitude": 116.4074,
      "country": "中国",
      "admin1": "北京市"
    }
  ]
}
```

#### API 2：Weather Forecast（经纬度 → 天气数据）

```
GET https://api.open-meteo.com/v1/forecast
  ?latitude=39.9042
  &longitude=116.4074
  &current=temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m
  &daily=weather_code,temperature_2m_max,temperature_2m_min,sunrise,sunset,precipitation_sum
  &hourly=temperature_2m
  &timezone=Asia/Shanghai
  &forecast_days=7
```

#### WMO 天气码映射表

```ts
// src/weather/weatherCodes.ts
// WMO Weather Interpretation Codes → 天气描述 + 图标
export const weatherCodeMap: Record<number, { desc: string; icon: string }> = {
  0:  { desc: '☀️ 晴朗', icon: '☀️' },
  1:  { desc: '🌤️ 大部晴朗', icon: '🌤️' },
  2:  { desc: '⛅ 多云', icon: '⛅' },
  3:  { desc: '☁️ 阴天', icon: '☁️' },
  45: { desc: '🌫️ 雾', icon: '🌫️' },
  48: { desc: '🌫️ 雾凇', icon: '🌫️' },
  51: { desc: '🌧️ 小毛毛雨', icon: '🌧️' },
  53: { desc: '🌧️ 毛毛雨', icon: '🌧️' },
  55: { desc: '🌧️ 大毛毛雨', icon: '🌧️' },
  61: { desc: '🌧️ 小雨', icon: '🌧️' },
  63: { desc: '🌧️ 中雨', icon: '🌧️' },
  65: { desc: '🌧️ 大雨', icon: '🌧️' },
  71: { desc: '❄️ 小雪', icon: '❄️' },
  73: { desc: '❄️ 中雪', icon: '❄️' },
  75: { desc: '❄️ 大雪', icon: '❄️' },
  80: { desc: '🌦️ 小阵雨', icon: '🌦️' },
  81: { desc: '🌦️ 中阵雨', icon: '🌦️' },
  82: { desc: '🌦️ 大阵雨', icon: '🌦️' },
  85: { desc: '❄️ 小阵雪', icon: '❄️' },
  86: { desc: '❄️ 大阵雪', icon: '❄️' },
  95: { desc: '⛈️ 雷暴', icon: '⛈️' },
  96: { desc: '⛈️ 雷暴+小冰雹', icon: '⛈️' },
  99: { desc: '⛈️ 雷暴+大冰雹', icon: '⛈️' }
}

export function getWeatherDesc(code: number): string {
  return weatherCodeMap[code]?.desc ?? `未知(${code})`
}

export function getWeatherIcon(code: number): string {
  return weatherCodeMap[code]?.icon ?? '❓'
}
```

### 42.4 技术选型

| 技术 | 用途 | 为什么选它 |
|------|------|----------|
| Vue 3 + TypeScript | 框架 | 全书技术栈 |
| Naive UI 2.x | UI 组件 | 本书主题 |
| Chart.js | 温度曲线图 | 轻量（60KB），零依赖，API 简单 |
| dayjs | 日期格式化 | dayjs 比 moment 小 97% |
| fetch (原生) | HTTP 请求 | 零依赖，演示 fetch 封装 |

> 📝 **本章回顾：** 天气项目用 Open-Meteo 免费 API（无需 Key），通过 Geocoding API 搜城市 → Forecast API 获取天气数据。WMO 天气码需要映射为中文描述和图标。

---

## 第43章 天气应用完整编码实现

### 43.1 项目初始化

```bash
pnpm create vue@latest weather-app -- --typescript
cd weather-app
pnpm add naive-ui @vicons/ionicons5 vfonts chart.js dayjs
pnpm dev
```

### 43.2 API 层——fetch 封装

```ts
// src/api/weather.ts

const GEOCODING_BASE = 'https://geocoding-api.open-meteo.com/v1/search'
const FORECAST_BASE = 'https://api.open-meteo.com/v1/forecast'

/**
 * 通用的 fetch 封装——带超时和错误处理
 * 对比 axios：fetch 是浏览器原生 API，零依赖但需要手动处理一些细节
 */
async function fetchJSON<T>(url: string, timeout = 10000): Promise<T> {
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(), timeout)

  try {
    const res = await fetch(url, { signal: controller.signal })
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`)
    return await res.json()
  } catch (err: any) {
    if (err.name === 'AbortError') throw new Error('请求超时，请检查网络')
    throw err
  } finally {
    clearTimeout(timer)
  }
}

/** 城市搜索——返回候选城市列表 */
export interface CityResult {
  id: number
  name: string
  latitude: number
  longitude: number
  country: string
  admin1?: string  // 省份/州
}

export async function searchCities(query: string): Promise<CityResult[]> {
  if (!query.trim()) return []
  const url = `${GEOCODING_BASE}?name=${encodeURIComponent(query)}&count=8&language=zh`
  const data = await fetchJSON<{ results?: any[] }>(url)
  return (data.results || []).map((r: any) => ({
    id: r.id,
    name: r.name,
    latitude: r.latitude,
    longitude: r.longitude,
    country: r.country || '',
    admin1: r.admin1 || ''
  }))
}

/** 天气数据——当前 + 逐日 + 逐小时 */
export interface WeatherData {
  city: string
  country: string
  current: {
    temperature: number       // °C
    humidity: number          // %
    windSpeed: number         // km/h
    weatherCode: number
    time: string
  }
  daily: Array<{
    date: string
    weatherCode: number
    tempMax: number
    tempMin: number
    sunrise: string
    sunset: string
    precipitation: number     // mm
  }>
  hourly: Array<{
    time: string
    temperature: number
  }>
}

export async function fetchWeather(lat: number, lon: number, city: string, country: string): Promise<WeatherData> {
  const params = new URLSearchParams({
    latitude: String(lat),
    longitude: String(lon),
    current: 'temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m',
    daily: 'weather_code,temperature_2m_max,temperature_2m_min,sunrise,sunset,precipitation_sum',
    hourly: 'temperature_2m',
    timezone: 'auto',
    forecast_days: '7'
  })
  const url = `${FORECAST_BASE}?${params.toString()}`
  const data = await fetchJSON<any>(url)

  return {
    city,
    country,
    current: {
      temperature: data.current.temperature_2m,
      humidity: data.current.relative_humidity_2m,
      windSpeed: data.current.wind_speed_10m,
      weatherCode: data.current.weather_code,
      time: data.current.time
    },
    daily: data.daily.time.map((t: string, i: number) => ({
      date: t,
      weatherCode: data.daily.weather_code[i],
      tempMax: data.daily.temperature_2m_max[i],
      tempMin: data.daily.temperature_2m_min[i],
      sunrise: data.daily.sunrise[i],
      sunset: data.daily.sunset[i],
      precipitation: data.daily.precipitation_sum[i]
    })),
    hourly: data.hourly.time.map((t: string, i: number) => ({
      time: t,
      temperature: data.hourly.temperature_2m[i]
    }))
  }
}
```

### 43.3 天气码映射

```ts
// src/weather/weatherCodes.ts (已在上方 42.3 展示)
```

### 43.4 全局主题——天空蓝渐变

```ts
// src/theme/skyTheme.ts
import type { GlobalThemeOverrides } from 'naive-ui'

export const skyThemeOverrides: GlobalThemeOverrides = {
  common: {
    primaryColor: '#3B82F6',          // 天空蓝
    primaryColorHover: '#60A5FA',
    primaryColorPressed: '#2563EB',
    borderRadius: '12px',
    fontSize: '15px',
    fontFamily: '-apple-system, BlinkMacSystemFont, sans-serif'
  },
  Card: {
    borderRadius: '16px',
    paddingMedium: '24px',
    boxShadow: '0 4px 20px rgba(59, 130, 246, 0.1)'
  },
  Button: {
    borderRadius: '10px',
    heightMedium: '40px'
  },
  Input: {
    borderRadius: '10px',
    borderFocus: '1px solid #3B82F6',
    boxShadowFocus: '0 0 0 3px rgba(59, 130, 246, 0.15)'
  }
}

export const skyDarkOverrides: GlobalThemeOverrides = {
  common: {
    primaryColor: '#60A5FA',
    bodyColor: '#0F172A',
    cardColor: '#1E293B',
    textColor1: '#F1F5F9',
    textColor2: '#CBD5E1',
    textColor3: '#64748B',
    borderColor: '#334155'
  }
}
```

### 43.5 主页面组件——App.vue

```vue
<!-- src/App.vue -->
<script setup lang="ts">
import { NConfigProvider, darkTheme } from 'naive-ui'
import { ref } from 'vue'
import WeatherSearch from './components/WeatherSearch.vue'
import CurrentWeather from './components/CurrentWeather.vue'
import DailyForecast from './components/DailyForecast.vue'
import HourlyChart from './components/HourlyChart.vue'
import ThemeToggle from './components/ThemeToggle.vue'
import { skyThemeOverrides, skyDarkOverrides } from './theme/skyTheme'
import type { WeatherData } from './api/weather'

const isDark = ref(false)
const weather = ref<WeatherData | null>(null)
const loading = ref(false)
const error = ref('')
</script>

<template>
  <n-config-provider
    :theme="isDark ? darkTheme : null"
    :theme-overrides="isDark ? skyDarkOverrides : skyThemeOverrides"
  >
    <!-- 页面背景渐变（天空色） -->
    <div
      class="app-bg"
      :class="{ dark: isDark }"
    >
      <div class="app-container">
        <!-- 头部 -->
        <div class="app-header">
          <h1>🌤️ 天气查询</h1>
          <theme-toggle v-model:dark="isDark" />
        </div>

        <!-- 搜索 -->
        <weather-search
          v-model:loading="loading"
          v-model:error="error"
          @select="weather = $event"
        />

        <!-- 错误、加载、空、有数据——四态处理 -->
        <n-spin :show="loading" description="正在获取天气数据...">
          <template v-if="error">
            <n-result status="error" :title="error" description="请检查城市名是否正确，或稍后重试" />
          </template>

          <template v-else-if="!weather">
            <n-empty description="搜索一个城市来查看天气" style="margin-top: 60px" />
          </template>

          <template v-else>
            <current-weather :data="weather" />
            <daily-forecast :data="weather" style="margin-top: 16px" />
            <hourly-chart :data="weather" style="margin-top: 16px" />
          </template>
        </n-spin>
      </div>
    </div>
  </n-config-provider>
</template>

<style>
* { margin: 0; padding: 0; box-sizing: border-box; }

.app-bg {
  min-height: 100vh;
  padding: 20px;
  /* 天空蓝渐变背景 */
  background: linear-gradient(135deg, #e0f2fe 0%, #bae6fd 50%, #7dd3fc 100%);
  transition: background 0.5s ease;
}

.app-bg.dark {
  background: linear-gradient(135deg, #0f172a 0%, #1e293b 50%, #334155 100%);
}

.app-container {
  max-width: 720px;
  margin: 0 auto;
}

.app-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 24px;
}

.app-header h1 {
  font-size: 28px;
  font-weight: 700;
  color: #1e3a5f;
}

.dark .app-header h1 { color: #f1f5f9; }
</style>
```

### 43.6 城市搜索组件

```vue
<!-- src/components/WeatherSearch.vue -->
<script setup lang="ts">
import { NInput, NSelect, NSpace, NButton, NIcon, useMessage } from 'naive-ui'
import { SearchOutline, TimeOutline } from '@vicons/ionicons5'
import { ref } from 'vue'
import { searchCities, fetchWeather } from '../api/weather'
import type { CityResult, WeatherData } from '../api/weather'

const msg = useMessage()
const query = ref('')
const cities = ref<CityResult[]>([])
const selectedCity = ref<number | null>(null)
const searching = ref(false)

const loading = defineModel<boolean>('loading', { default: false })
const error = defineModel<string>('error', { default: '' })

const emit = defineEmits<{
  select: [data: WeatherData]
}>()

// 城市搜索（防抖 300ms）
let searchTimer: ReturnType<typeof setTimeout>
function handleSearch(value: string) {
  query.value = value
  clearTimeout(searchTimer)
  if (!value.trim()) { cities.value = []; return }

  searchTimer = setTimeout(async () => {
    searching.value = true
    try {
      cities.value = await searchCities(value)
    } catch (e: any) {
      msg.error('搜索失败：' + e.message)
    } finally {
      searching.value = false
    }
  }, 300)
}

// 选中城市 → 获取天气
async function handleSelect(value: number) {
  const city = cities.value.find(c => c.id === value)
  if (!city) return

  loading.value = true
  error.value = ''

  try {
    const data = await fetchWeather(city.latitude, city.longitude, city.name, city.country)
    emit('select', data)

    // 保存到搜索历史
    saveHistory({ id: city.id, name: city.name, country: city.country, lat: city.latitude, lon: city.longitude })
  } catch (e: any) {
    error.value = e.message || '获取天气失败'
  } finally {
    loading.value = false
  }
}

// ===== 搜索历史（localStorage） =====
interface HistoryItem { id: number; name: string; country: string; lat: number; lon: number }
const history = ref<HistoryItem[]>(JSON.parse(localStorage.getItem('weatherHistory') || '[]'))

function saveHistory(item: HistoryItem) {
  history.value = [item, ...history.value.filter(h => h.id !== item.id)].slice(0, 5)
  localStorage.setItem('weatherHistory', JSON.stringify(history.value))
}

async function selectHistory(item: HistoryItem) {
  loading.value = true
  error.value = ''
  try {
    const data = await fetchWeather(item.lat, item.lon, item.name, item.country)
    emit('select', data)
  } catch (e: any) {
    error.value = e.message || '获取天气失败'
  } finally { loading.value = false }
}

// 城市选项（label 显示"城市名, 国家"）
const cityOptions = computed(() => cities.value.map(c => ({
  label: `${c.name}${c.admin1 ? ', ' + c.admin1 : ''}, ${c.country}`,
  value: c.id
})))
</script>

<template>
  <div>
    <n-space vertical :size="12">
      <!-- 搜索输入 -->
      <n-input
        v-model:value="query"
        placeholder="输入城市名搜索（例如：Beijing, Tokyo, London）"
        size="large"
        clearable
        :loading="searching"
        @input="handleSearch"
      >
        <template #prefix>
          <n-icon><SearchOutline /></n-icon>
        </template>
      </n-input>

      <!-- 候选城市下拉 -->
      <n-select
        v-if="cityOptions.length > 0"
        v-model:value="selectedCity"
        :options="cityOptions"
        placeholder="选择一个城市"
        size="large"
        filterable
        @update:value="handleSelect"
      />

      <!-- 搜索历史 -->
      <div v-if="history.length > 0 && !cityOptions.length" style="margin-top: 8px">
        <n-space align="center" :size="6">
          <n-icon :depth="3"><TimeOutline /></n-icon>
          <span style="font-size: 13px; color: #888">最近搜索：</span>
          <n-button
            v-for="h in history"
            :key="h.id"
            size="tiny"
            quaternary
            @click="selectHistory(h)"
          >
            {{ h.name }}, {{ h.country }}
          </n-button>
        </n-space>
      </div>
    </n-space>
  </div>
</template>
```

### 43.7 当前天气卡片

```vue
<!-- src/components/CurrentWeather.vue -->
<script setup lang="ts">
import { NCard, NGrid, NGi, NText } from 'naive-ui'
import type { WeatherData } from '../api/weather'
import { getWeatherDesc, getWeatherIcon } from '../weather/weatherCodes'

const props = defineProps<{ data: WeatherData }>()
const w = computed(() => props.data)
</script>

<template>
  <n-card :bordered="false" style="text-align: center">
    <div style="font-size: 72px; margin-bottom: 8px">
      {{ getWeatherIcon(w.current.weatherCode) }}
    </div>
    <div style="font-size: 48px; font-weight: 700; color: inherit">
      {{ w.current.temperature }}°C
    </div>
    <n-text depth="2">{{ getWeatherDesc(w.current.weatherCode) }}</n-text>
    <div style="font-size: 14px; color: #888; margin-top: 4px">
      {{ w.city }}, {{ w.country }}
    </div>

    <!-- 详细数据 -->
    <n-grid :cols="3" style="margin-top: 20px">
      <n-gi>
        <div style="font-size: 13px; color: #999">💧 湿度</div>
        <div style="font-weight: 600">{{ w.current.humidity }}%</div>
      </n-gi>
      <n-gi>
        <div style="font-size: 13px; color: #999">💨 风速</div>
        <div style="font-weight: 600">{{ w.current.windSpeed }} km/h</div>
      </n-gi>
      <n-gi>
        <div style="font-size: 13px; color: #999">🕐 更新</div>
        <div style="font-weight: 600">{{ w.current.time?.slice(11, 16) }}</div>
      </n-gi>
    </n-grid>
  </n-card>
</template>
```

### 43.8 7天预报组件

```vue
<!-- src/components/DailyForecast.vue -->
<script setup lang="ts">
import { NCard, NDataTable } from 'naive-ui'
import { h, computed } from 'vue'
import type { DataTableColumns } from 'naive-ui'
import type { WeatherData } from '../api/weather'
import { getWeatherIcon, getWeatherDesc } from '../weather/weatherCodes'
import dayjs from 'dayjs'

const props = defineProps<{ data: WeatherData }>()

interface DailyRow {
  day: string
  icon: string
  desc: string
  tempMax: number
  tempMin: number
  precip: number
  sunrise: string
}

const rows = computed<DailyRow[]>(() =>
  props.data.daily.map(d => ({
    day: dayjs(d.date).format('MM/DD ddd'),
    icon: getWeatherIcon(d.weatherCode),
    desc: getWeatherDesc(d.weatherCode),
    tempMax: d.tempMax,
    tempMin: d.tempMin,
    precip: d.precipitation,
    sunrise: d.sunrise?.slice(11, 16) || ''
  }))
)

const columns: DataTableColumns<DailyRow> = [
  { title: '日期', key: 'day', width: 100 },
  {
    title: '天气', key: 'icon', width: 100,
    render(row) { return `${row.icon} ${row.desc}` }
  },
  {
    title: '最高/最低', key: 'temp', width: 120,
    render(row) { return h('span', [h('span', { style: 'font-weight:600' }, `${row.tempMax}°`), ' / ', h('span', { style: 'color:#888' }, `${row.tempMin}°`)]) }
  },
  { title: '降水', key: 'precip', width: 80, render(row) { return `${row.precip} mm` } },
  { title: '日出', key: 'sunrise', width: 80 }
]
</script>

<template>
  <n-card title="📅 7 天预报" :bordered="false">
    <n-data-table :columns="columns" :data="rows" :bordered="false" :single-line="false" />
  </n-card>
</template>
```

### 43.9 逐小时温度曲线图（Chart.js）

```bash
pnpm add chart.js
```

```vue
<!-- src/components/HourlyChart.vue -->
<script setup lang="ts">
import { NCard } from 'naive-ui'
import { onMounted, ref, watch, computed } from 'vue'
import { Chart, registerables } from 'chart.js'
import type { WeatherData } from '../api/weather'
import dayjs from 'dayjs'

Chart.register(...registerables)

const props = defineProps<{ data: WeatherData }>()

const canvasRef = ref<HTMLCanvasElement | null>(null)
let chartInstance: Chart | null = null

// 取未来 24 小时的数据
const hourly24 = computed(() => props.data.hourly.slice(0, 24))

function renderChart() {
  if (!canvasRef.value) return
  // 销毁旧图表
  if (chartInstance) { chartInstance.destroy(); chartInstance = null }

  const labels = hourly24.value.map(h => dayjs(h.time).format('HH:mm'))
  const temps = hourly24.value.map(h => h.temperature)

  chartInstance = new Chart(canvasRef.value, {
    type: 'line',
    data: {
      labels,
      datasets: [{
        label: '温度 (°C)',
        data: temps,
        borderColor: '#3B82F6',
        backgroundColor: 'rgba(59, 130, 246, 0.1)',
        fill: true,
        tension: 0.4,             // 曲线平滑度
        pointRadius: 3,
        pointHoverRadius: 6
      }]
    },
    options: {
      responsive: true,
      plugins: {
        legend: { display: true, position: 'top' as const }
      },
      scales: {
        y: {
          ticks: { callback: (v) => `${v}°C` }
        }
      }
    }
  })
}

onMounted(() => renderChart())
watch(() => props.data, () => renderChart(), { deep: true })
</script>

<template>
  <n-card title="📈 24 小时温度趋势" :bordered="false">
    <canvas ref="canvasRef" height="200"></canvas>
  </n-card>
</template>
```

### 43.10 主题切换组件

```vue
<!-- src/components/ThemeToggle.vue -->
<script setup lang="ts">
import { NButton, NIcon } from 'naive-ui'
import { SunnyOutline, MoonOutline } from '@vicons/ionicons5'

const dark = defineModel<boolean>('dark', { default: false })
</script>

<template>
  <n-button text @click="dark = !dark" style="font-size: 24px">
    <n-icon size="28">
      <SunnyOutline v-if="dark" />
      <MoonOutline v-else />
    </n-icon>
  </n-button>
</template>
```

> 📝 **本章回顾：** 天气应用的完整代码包括：API 层（fetch 封装 + Open-Meteo 接口）、主题层（天空蓝渐变）、搜索组件（远程搜索 + 历史记录）、当前天气卡片、7天预报表格、Chart.js 温度曲线图、暗黑模式切换。四态处理（加载/错误/空/数据）让体验更完整。

---

## 第44章 天气应用工程化收尾

### 44.1 环境变量配置

```env
# .env
VITE_GEOCODING_API=https://geocoding-api.open-meteo.com/v1/search
VITE_FORECAST_API=https://api.open-meteo.com/v1/forecast
```

```ts
// src/api/weather.ts —— 改用环境变量
const GEOCODING_BASE = import.meta.env.VITE_GEOCODING_API
const FORECAST_BASE = import.meta.env.VITE_FORECAST_API
```

### 44.2 移动端响应式适配

```vue
<style>
/* 在小屏幕上调整卡片间距和字号 */
@media (max-width: 640px) {
  .app-container { padding: 0 8px; }
  .app-header h1 { font-size: 22px; }

  /* 当前天气温度缩小 */
  .temp-large { font-size: 36px; }

  /* 表格横向滚动 */
  .daily-table :deep(.n-data-table) { overflow-x: auto; }
}
</style>
```

### 44.3 Vercel 免费部署

```bash
# 安装 Vercel CLI
pnpm i -g vercel

# 部署
vercel

# 按提示操作：
# ? Set up and deploy? → Y
# ? Which scope? → 选你的账号
# ? Link to existing project? → N
# ? Project name? → weather-app
# ? Directory? → ./
# ? Override settings? → N
```

部署后你会得到一个 `https://weather-app-xxx.vercel.app` 的链接，全世界都能访问。

> 💡 Vercel 对个人项目完全免费，支持自动 HTTPS、自定义域名、Git 自动部署。

### 44.4 项目目录结构总结

```
weather-app/
├── src/
│   ├── api/
│   │   └── weather.ts         # API 层（fetch 封装 + 接口函数）
│   ├── weather/
│   │   └── weatherCodes.ts    # WMO 天气码映射
│   ├── theme/
│   │   └── skyTheme.ts        # 天空蓝主题配置
│   ├── components/
│   │   ├── WeatherSearch.vue  # 城市搜索（远程 + 历史记录）
│   │   ├── CurrentWeather.vue # 当前天气卡片
│   │   ├── DailyForecast.vue  # 7天预报表格
│   │   ├── HourlyChart.vue    # 温度曲线图（Chart.js）
│   │   └── ThemeToggle.vue    # 暗黑模式切换按钮
│   ├── App.vue                # 主页面（四态处理）
│   └── main.ts
├── .env
└── package.json
```

> 📝 **本章回顾：** 环境变量管理 API 地址、响应式适配移动端、Vercel 一键部署。完整项目约 10 个文件，代码量不到 500 行，但涵盖了真实项目中的所有关键环节。

---

# 第十篇章（续）疑难问题排查与实战踩坑手册

> （第38-41章已在前面呈现，此处为扩展补充）

### 天气项目常见 Bug

| 问题 | 原因 | 解决 |
|------|------|------|
| 搜索城市返回空 | 城市名需要英文（如 Beijing 而不是 北京） | 使用英文名搜索，或在 geocoding API 加 `language=zh` |
| 温度图表不显示 | Chart.js 未注册组件 | `Chart.register(...registerables)` |
| fetch 请求超时 | 网络不稳定或 API 服务波动 | 使用 AbortController 设置超时，显示友好错误 |
| 暗黑模式下图表颜色看不清 | Chart.js 不跟随 Naive UI 主题 | 在主题切换时重新渲染图表，更新颜色配置 |

---

# 附录

## 附录A Naive UI 全组件清单与功能对照表

### 通用
NButton、NButtonGroup、NSpace、NText、NTag、NBadge、NIcon

### 布局
NLayout、NLayoutHeader、NLayoutContent、NLayoutSider、NLayoutFooter、NGrid、NGi、NCard

### 导航
NMenu、NTabs/NTabPane、NBreadcrumb/NBreadcrumbItem、NDropdown、NPageHeader

### 数据录入
NInput、NInputNumber、NSelect、NCascader、NDatePicker、NTimePicker、NRadio/NRadioGroup、NCheckbox/NCheckboxGroup、NSwitch、NSlider、NUpload、NTransfer、NColorPicker、NRate

### 数据展示
NDataTable、NTree、NTreeSelect、NList/NListItem、NThing、NDescriptions/NDescriptionsItem、NAvatar、NImage、NProgress、NNumberAnimation、NStatistic、NCalendar

### 反馈
NModal、NDrawer/NDrawerContent、NPopover、NPopconfirm、NTooltip、NSpin、NWatermark、NResult、NEmpty、NSkeleton
API：useMessage、useDialog、useNotification、useLoadingBar

### 其他
NConfigProvider、NScrollbar、NBackTop、NCode、NCountdown、NEllipsis

---

## 附录B 全局主题变量完整版手册

```ts
// Common（全局公用变量）
primaryColor        // 主色
infoColor           // 信息色
successColor          // 成功色
warningColor          // 警告色
errorColor            // 错误色
// 每种颜色都有 Hover/Pressed/Suppl 变体

textColor1 / textColor2 / textColor3   // 文字深浅三级
bodyColor / cardColor / modalColor     // 背景三级
borderColor / borderRadius / fontFamily / fontSize / boxShadow
```

### 组件变量命名规则
`组件名` + `变量名`（首字母大写）
例如 `Button.borderRadius`、`Input.borderFocus`、`Card.paddingMedium`

---

## 附录C 项目通用工具函数封装源码

```ts
// ===== src/utils/format.ts =====
import dayjs from 'dayjs'

export function formatDate(date: number | string | Date, format = 'YYYY-MM-DD HH:mm:ss') {
  if (!date) return ''
  return dayjs(date).format(format)
}

export function formatMoney(cents: number) {
  return (cents / 100).toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ',')
}

export function formatFileSize(bytes: number): string {
  if (bytes === 0) return '0 B'
  const units = ['B', 'KB', 'MB', 'GB']
  const i = Math.floor(Math.log(bytes) / Math.log(1024))
  return (bytes / Math.pow(1024, i)).toFixed(2) + ' ' + units[i]
}

// 日期处理增强工具集
export function getRelativeTime(date: string | Date): string {
  const now = dayjs()
  const target = dayjs(date)
  const diffMin = now.diff(target, 'minute')
  if (diffMin < 1) return '刚刚'
  if (diffMin < 60) return `${diffMin} 分钟前`
  const diffHour = now.diff(target, 'hour')
  if (diffHour < 24) return `${diffHour} 小时前`
  const diffDay = now.diff(target, 'day')
  if (diffDay < 30) return `${diffDay} 天前`
  return formatDate(date)
}

export function getWeekday(date: string | Date): string {
  const map = ['周日', '周一', '周二', '周三', '周四', '周五', '周六']
  return map[dayjs(date).day()]
}

// ===== src/utils/validate.ts =====
export function isValidPhone(v: string) { return /^1[3-9]\d{9}$/.test(v) }
export function isValidEmail(v: string) { return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) }
export function isValidIDCard(v: string) { return /^[1-9]\d{5}(19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$/.test(v) }

// ===== src/utils/exportCsv.ts =====
export function exportCsv(filename: string, headers: string[], rows: any[][]) {
  const csv = [
    headers.join(','),
    ...rows.map(row => row.map(c => `"${String(c ?? '').replace(/"/g, '""')}"`).join(','))
  ].join('\n')
  const blob = new Blob(['\uFEFF' + csv], { type: 'text/csv;charset=utf-8;' })
  const url = URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url; a.download = `${filename}.csv`; a.click()
  URL.revokeObjectURL(url)
}

// ===== src/utils/index.ts =====
export function debounce<T extends (...args: any[]) => any>(fn: T, delay: number) {
  let timer: ReturnType<typeof setTimeout>
  return (...args: Parameters<T>) => { clearTimeout(timer); timer = setTimeout(() => fn(...args), delay) }
}

export function throttle<T extends (...args: any[]) => any>(fn: T, delay: number) {
  let last = 0
  return (...args: Parameters<T>) => { const now = Date.now(); if (now - last >= delay) { last = now; fn(...args) } }
}

export function uid() { return Date.now().toString(36) + Math.random().toString(36).slice(2) }

export function deepClone<T>(obj: T): T { return JSON.parse(JSON.stringify(obj)) }
```

---

## 附录D 官方资源与学习渠道汇总

| 资源 | 地址 |
|------|------|
| 📖 官方文档 | https://www.naiveui.com |
| 📦 GitHub | https://github.com/tusen-ai/naive-ui |
| 🎨 主题编辑器 | https://www.naiveui.com/zh-CN/os-theme |
| 🔣 IonIcons 图标 | https://ionic.io/ionicons |
| 💬 Discord | https://discord.gg/Pqv7Mev5xT |
| 🌤️ Open-Meteo API | https://open-meteo.com |
| 📊 Chart.js 文档 | https://www.chartjs.org |

### 推荐学习路线（0→1）

1. **第1-8章**（入门）：理解组件库，搭环境，基础组件
2. **第9-14章**（进阶）：表单是核心——输入框、选择器、校验
3. **第15-20章**（深入）：表格、树、布局——后台 80% 的代码
4. **第21-23章**（交互）：消息、弹窗、通知——用户反馈
5. **第24-28章**（亮点）：主题定制 + CSS 深度定制——Naive UI 看家本领
6. **第29-32章**（工程化）：上线前优化
7. **第33-37章**（实战）：后台管理系统，从头到尾
8. **第38-41章**（排错）：遇到 bug 回来查
9. **第42-44章**（扩展）：天气查询工具——前端项目的完整闭环

---

## 附录E 天气应用完整源码清单

```
weather-app/
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
├── .env                              # 环境变量
└── src/
    ├── main.ts                       # 入口文件
    ├── App.vue                       # 主页面（四态处理 + 主题）
    ├── api/
    │   └── weather.ts                # fetch 封装 + Open-Meteo 接口
    ├── weather/
    │   └── weatherCodes.ts           # WMO 天气码 → 中文/图标的映射表
    ├── theme/
    │   └── skyTheme.ts               # 天空蓝主题（浅色 + 暗黑）
    └── components/
        ├── WeatherSearch.vue         # 城市搜索（远程 + 历史记录）
        ├── CurrentWeather.vue        # 当前天气卡片
        ├── DailyForecast.vue         # 7天预报表格
        ├── HourlyChart.vue           # 24小时温度曲线图（Chart.js）
        └── ThemeToggle.vue           # 暗黑模式切换按钮
```

> 💡 整个天气项目仅 **10 个文件、约 400 行业务代码**，但涵盖了：
> - 远程 API 调用（fetch + AbortController）
> - 搜索防抖（debounce 300ms）
> - 搜索历史（localStorage）
> - 主题系统（天空蓝渐变 + 暗黑适配）
> - 四态处理（加载/错误/空/数据）
> - 数据可视化（Chart.js 折线图）
> - 响应式布局（移动端适配）
> - 一键部署（Vercel）

---

> 🎉 **恭喜你读完了整本书！**
>
> 从零基础到能独立搭建后台管理系统 + 天气查询工具，你已经完成了从"新手"到"Naive UI 熟练工"的转变。
> 剩下的就是：多写、多练、多踩坑。踩完的每一坑都会让你变得更强大。
>
> **编码愉快！🚀**