naive-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Naive UI Practices

Naive UI 实践指南

Usage guide for Naive UI and Vue 3 applications. Contains 33 rules across 8 categories, prioritized by impact to guide automated refactoring, component creation, and troubleshooting.

这是一份针对Naive UI与Vue 3应用的使用指南，包含8个分类下的33条规则，按影响优先级排序，可指导自动化重构、组件创建及问题排查。

When to Apply

适用场景

Reference these guidelines when:

Writing new Vue 3 components using Naive UI
Implementing forms and data validation
Handling large datasets with virtual scrolling (DataTable, Tree, Select)
Customizing application themes and dark mode
Troubleshooting Naive UI usage issues and styling conflicts

在以下场景可参考本指南：

使用Naive UI编写新的Vue 3组件时
实现表单与数据验证时
使用虚拟滚动处理大型数据集时（DataTable、Tree、Select）
自定义应用主题与深色模式时
排查Naive UI使用问题与样式冲突时

Rule Categories by Priority

按优先级划分的规则分类


core-
component-
component-
component-
component-
component-
core-
core-

Priority	Category	Impact	Prefix
1	Core Configuration	CRITICAL	`core-`
2	Form & Data Input	CRITICAL	`component-`
3	Complex Data Display	HIGH	`component-`
4	Feedback & Overlay	HIGH	`component-`
5	Layout & Navigation	MEDIUM	`component-`
6	Basic Data Display	MEDIUM	`component-`
7	Advanced Customization	LOW-MEDIUM	`core-`
8	Ecosystem & Troubleshooting	LOW	`core-`


core-
component-
component-
component-
component-
component-
core-
core-

优先级	分类	影响程度	前缀
1	核心配置	关键	`core-`
2	表单与数据输入	关键	`component-`
3	复杂数据展示	高	`component-`
4	反馈与浮层	高	`component-`
5	布局与导航	中	`component-`
6	基础数据展示	中	`component-`
7	高级定制	低-中	`core-`
8	生态与问题排查	低	`core-`

Quick Reference

快速参考

1. Core Configuration (CRITICAL)

1. 核心配置（关键）

```
core-setup
```
- Auto-import setup, global config, providers
```
core-theme
```
- Theme overrides, dark mode, CSS variables, useThemeVars
```
core-import-on-demand
```
- Import on demand and tree shaking
```
core-nuxtjs
```
- Nuxt.js integration best practices
```
core-ssr
```
- Server-Side Rendering guidelines
```
core-style-conflict
```
- Potential style conflict resolution

```
core-setup
```
- 自动导入setup、全局配置、提供者
```
core-theme
```
- 主题覆盖、深色模式、CSS变量、useThemeVars
```
core-import-on-demand
```
- 按需导入与摇树优化
```
core-nuxtjs
```
- Nuxt.js集成最佳实践
```
core-ssr
```
- 服务端渲染指南
```
core-style-conflict
```
- 潜在样式冲突解决方案

2. Form & Data Input (CRITICAL)

2. 表单与数据输入（关键）

```
component-form-validation
```
- Validation rules, dynamic forms, array fields
```
component-form
```
- Layout, validation, dynamic fields, nested forms
```
component-input
```
- Formatted input, precision, validation triggers
```
component-select
```
- Filterable, multiple, tags, async search, custom render
```
component-datepicker
```
- Date ranges, shortcuts, formatting, timezone
```
component-upload
```
- Custom request, file handling, drag drop

```
component-form-validation
```
- 验证规则、动态表单、数组字段
```
component-form
```
- 布局、验证、动态字段、嵌套表单
```
component-input
```
- 格式化输入、精度控制、验证触发
```
component-select
```
- 可筛选、多选、标签、异步搜索、自定义渲染
```
component-datepicker
```
- 日期范围、快捷选项、格式化、时区
```
component-upload
```
- 自定义请求、文件处理、拖拽上传

3. Complex Data Display (HIGH)

3. 复杂数据展示（高）

```
component-datatable
```
- Virtual scroll, remote data, sorting, filtering, fixed columns
```
component-tree
```
- Async loading, checkable, controlled state, large dataset handling
```
component-virtual-list
```
- Virtual scrolling patterns

```
component-datatable
```
- 虚拟滚动、远程数据、排序、筛选、固定列
```
component-tree
```
- 异步加载、可勾选、受控状态、大型数据集处理
```
component-virtual-list
```
- 虚拟滚动模式

4. Feedback & Overlay (HIGH)

4. 反馈与浮层（高）

```
component-modal
```
- Form modals, draggable, focus management, async close
```
component-feedback
```
- Programmatic API, global methods (Message, Notification)
```
component-feedback-alert
```
- Alert, Skeleton, Spin, LoadingBar, Popconfirm

```
component-modal
```
- 表单模态框、可拖拽、焦点管理、异步关闭
```
component-feedback
```
- 程序化API、全局方法（Message、Notification）
```
component-feedback-alert
```
- 警告框、骨架屏、加载动画、进度条、确认弹窗

5. Layout & Navigation (MEDIUM)

5. 布局与导航（中）

```
component-layout
```
- Layout, Grid, Flex, Space, Card, Divider
```
component-menu
```
- Menu, Dropdown, Breadcrumb, Tabs
```
component-navigation-steps
```
- Steps, Timeline, Pagination, Anchor, BackTop

```
component-layout
```
- 布局、网格、弹性布局、间距、卡片、分割线
```
component-menu
```
- 菜单、下拉菜单、面包屑、标签页
```
component-navigation-steps
```
- 步骤条、时间线、分页、锚点、返回顶部

6. Basic Data Display (MEDIUM)

6. 基础数据展示（中）

```
component-data-display
```
- Image, List, Descriptions, Calendar, Time, Countdown
```
component-display
```
- Badge, Tag, Avatar, Progress, Statistic, Result, Empty
```
component-button
```
- Button variants, loading, icons
```
component-selection
```
- Radio, Checkbox, Switch, Slider, Rate, ColorPicker

```
component-data-display
```
- 图片、列表、描述、日历、时间、倒计时
```
component-display
```
- 徽章、标签、头像、进度条、统计、结果页、空状态
```
component-button
```
- 按钮变体、加载状态、图标
```
component-selection
```
- 单选框、复选框、开关、滑块、评分、颜色选择器

7. Advanced Customization (LOW-MEDIUM)

7. 高级定制（低-中）

```
core-customize-theme
```
- Customizing theme extensively
```
core-fonts
```
- Configuring fonts
```
core-i18n
```
- Internationalization
```
core-controlled-uncontrolled
```
- Controlled manner & uncontrolled manner

```
core-customize-theme
```
- 深度定制主题
```
core-fonts
```
- 字体配置
```
core-i18n
```
- 国际化
```
core-controlled-uncontrolled
```
- 受控与非受控模式

8. Ecosystem & Troubleshooting (LOW)

8. 生态与问题排查（低）

```
core-troubleshooting
```
- Common issues and quick fixes
```
core-installation
```
- Installation guidelines
```
core-jsx
```
- JSX & TSX usage
```
core-umd
```
- Using UMD build
```
core-usage-sfc
```
- Usage in SFC
```
core-vite-ssge
```
- Vite SSG/SSE integration
```
core-vitepress
```
- Vitepress integration
```
core-experimental-features
```
- Experimental features

```
core-troubleshooting
```
- 常见问题与快速修复
```
core-installation
```
- 安装指南
```
core-jsx
```
- JSX与TSX使用方法
```
core-umd
```
- UMD构建版本使用
```
core-usage-sfc
```
- 单文件组件（SFC）中使用
```
core-vite-ssge
```
- Vite SSG/SSE集成
```
core-vitepress
```
- Vitepress集成
```
core-experimental-features
```
- 实验性功能

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

references/core-setup.md
references/component-datatable.md

Each rule file contains:

Specific implementation details
Code examples for Vue 3 setup script
Warning notes and prerequisites
Relevant TypeScript interfaces

阅读单个规则文件获取详细说明与代码示例：

references/core-setup.md
references/component-datatable.md

每个规则文件包含：

具体实现细节
Vue 3 setup脚本的代码示例
注意事项与前置要求
相关TypeScript接口

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有展开规则的完整指南，请参考：

AGENTS.md