naive-ui-skills

Naive UI 技能库

一个全面的 Naive UI 框架技能库，旨在帮助 AI Agent 有效理解和使用 Naive UI 组件。

何时调用

在以下情况下调用此技能：

• 用户需要实现任何 Naive UI 组件
• 用户询问 Naive UI 配置或设置
• 用户想要自定义主题或使用暗色模式
• 用户需要国际化（i18n）支持
• 用户询问设计规范（颜色、边框、字体排印）
• 用户遇到 Naive UI 组件相关问题

技能库概览

此库包含 107 个技能，分为以下类别：

类别	数量	描述	路径模式
组件技能	95	单个组件文档	./components/n-{name}/SKILL.md
设计规范	5	边框、颜色、布局、字体排印、概览	./naive-ui-design-{name}/SKILL.md
基础技能	6	快速入门、主题设置、i18n、暗色模式、SSR、组件	./naive-ui-{name}/SKILL.md

如何查找技能

1. 组件技能（95 个技能）

所有组件技能均遵循 n-{component-name} 命名规范，位于 components/ 目录中。

路径模式：

./components/n-{component-name}/SKILL.md

示例：

• 按钮：./components/n-button/SKILL.md
• 表单：./components/n-form/SKILL.md
• 数据表格：./components/n-data-table/SKILL.md
• 对话框：./components/n-dialog/SKILL.md

2. 设计规范技能（5 个技能）

设计技能提供有关 Naive UI 设计系统的指导。

技能名称	路径	描述
边框	./naive-ui-design-border/SKILL.md	边框样式、圆角、阴影
颜色	./naive-ui-design-color/SKILL.md	调色板与颜色语义
布局	./naive-ui-design-layout/SKILL.md	网格系统与布局
字体排印	./naive-ui-design-typography/SKILL.md	字体规范
概览	./naive-ui-design-overview/SKILL.md	设计系统概览

3. 基础技能（6 个技能）

基础技能涵盖核心设置与配置。

技能名称	路径	描述
快速入门	./naive-ui-quickstart/SKILL.md	安装与设置
主题设置	./naive-ui-theming/SKILL.md	主题自定义
i18n	./naive-ui-i18n/SKILL.md	国际化
暗色模式	./naive-ui-dark-mode/SKILL.md	暗色模式实现
SSR	./naive-ui-ssr/SKILL.md	服务端渲染
组件	./naive-ui-components/SKILL.md	组件概览索引

技能调用指南

步骤 1：识别用户意图

分析用户的请求，确定所需的技能类别：

用户请求模式	技能类别	示例技能
“创建按钮/表单/表格……”	组件	n-button、n-form、n-data-table
“如何设置 Naive UI”	基础	naive-ui-quickstart
“自定义主题颜色”	基础	naive-ui-theming
“添加多语言支持”	基础	naive-ui-i18n
“实现暗色模式”	基础	naive-ui-dark-mode
“有哪些可用颜色？”	设计	naive-ui-design-color
“网格如何运作？”	设计	naive-ui-design-layout

步骤 2：查找技能文件

使用上述路径模式查找相应的技能文件：

# For component skills
./components/n-{component-name}/SKILL.md

# For design skills
./naive-ui-design-{name}/SKILL.md

# For foundation skills
./naive-ui-{name}/SKILL.md

步骤 3：阅读并应用技能内容

每个技能文件都包含：

• 何时调用：使用该技能的具体条件
• 功能：组件能力与选项
• API 参考：属性、事件、插槽、暴露项
• 用法示例：常见模式的代码片段
• 最佳实践：推荐的实现指南

组件技能索引

常用组件（15）

组件	技能路径	描述
头像	./components/n-avatar/SKILL.md	用户头像
按钮	./components/n-button/SKILL.md	提供多种类型和状态的按钮
卡片	./components/n-card/SKILL.md	卡片容器
轮播	./components/n-carousel/SKILL.md	图片轮播
折叠面板	./components/n-collapse/SKILL.md	可折叠面板
分割线	./components/n-divider/SKILL.md	分隔线
下拉菜单	./components/n-dropdown/SKILL.md	下拉菜单
省略文本	./components/n-ellipsis/SKILL.md	文本省略
悬浮按钮	./components/n-float-button/SKILL.md	悬浮按钮
渐变文本	./components/n-gradient-text/SKILL.md	渐变文本效果
图标	./components/n-icon/SKILL.md	图标包装组件
页面标题	./components/n-page-header/SKILL.md	页面标题
标签	./components/n-tag/SKILL.md	标签和标记
排版	./components/n-typography/SKILL.md	排版组件
水印	./components/n-watermark/SKILL.md	水印

数据输入组件（21）

组件	技能路径	描述
自动补全	./components/n-auto-complete/SKILL.md	提供建议的输入框
级联选择器	./components/n-cascader/SKILL.md	级联选择
复选框	./components/n-checkbox/SKILL.md	复选框
颜色选择器	./components/n-color-picker/SKILL.md	颜色选择器
日期选择器	./components/n-date-picker/SKILL.md	日期选择器
动态输入框	./components/n-dynamic-input/SKILL.md	动态输入字段
动态标签	./components/n-dynamic-tags/SKILL.md	动态标签输入
表单	./components/n-form/SKILL.md	表单管理
输入框	./components/n-input/SKILL.md	文本输入
数字输入框	./components/n-input-number/SKILL.md	数字输入
OTP 输入框	./components/n-input-otp/SKILL.md	OTP 输入
提及输入框	./components/n-mention/SKILL.md	提及输入
单选按钮	./components/n-radio/SKILL.md	单选按钮
评分	./components/n-rate/SKILL.md	星级评分
选择器	./components/n-select/SKILL.md	下拉选择
滑块	./components/n-slider/SKILL.md	滑块输入
开关	./components/n-switch/SKILL.md	切换开关
时间选择器	./components/n-time-picker/SKILL.md	时间选择器
穿梭框	./components/n-transfer/SKILL.md	穿梭面板
树形选择器	./components/n-tree-select/SKILL.md	树形选择
上传	./components/n-upload/SKILL.md	文件上传

数据展示组件（21）

组件	技能路径	描述
日历	./components/n-calendar/SKILL.md	日历视图
代码	./components/n-code/SKILL.md	代码展示
倒计时	./components/n-countdown/SKILL.md	倒计时计时器
数据表格	./components/n-data-table/SKILL.md	高级数据表格
描述	./components/n-descriptions/SKILL.md	描述列表
空状态	./components/n-empty/SKILL.md	空状态
方程式	./components/n-equation/SKILL.md	数学方程式
热力图	./components/n-heatmap/SKILL.md	热力图可视化
高亮	./components/n-highlight/SKILL.md	代码高亮
图片	./components/n-image/SKILL.md	带预览的图片
无限滚动	./components/n-infinite-scroll/SKILL.md	无限滚动
列表	./components/n-list/SKILL.md	列表容器
日志	./components/n-log/SKILL.md	日志展示
数字动画	./components/n-number-animation/SKILL.md	动态数字
QR 码	./components/n-qr-code/SKILL.md	QR 码生成器
统计	./components/n-statistic/SKILL.md	统计数据展示
表格	./components/n-table/SKILL.md	基础表格
事项	./components/n-thing/SKILL.md	事项容器
时间	./components/n-time/SKILL.md	时间展示
时间线	./components/n-timeline/SKILL.md	时间线展示
树	./components/n-tree/SKILL.md	树视图

导航组件（9）

组件	技能路径	描述
固钉	./components/n-affix/SKILL.md	粘性定位
锚点	./components/n-anchor/SKILL.md	锚点导航
回到顶部	./components/n-back-top/SKILL.md	回到顶部按钮
面包屑	./components/n-breadcrumb/SKILL.md	面包屑导航
加载条	./components/n-loading-bar/SKILL.md	加载条
菜单	./components/n-menu/SKILL.md	导航菜单
分页	./components/n-pagination/SKILL.md	分页
步骤条	./components/n-steps/SKILL.md	步骤指南
标签页	./components/n-tabs/SKILL.md	标签页

反馈组件（16）

组件	技能路径	描述
警告	./components/n-alert/SKILL.md	警告消息
徽标	./components/n-badge/SKILL.md	徽章和标记
对话框	./components/n-dialog/SKILL.md	模态对话框
抽屉	./components/n-drawer/SKILL.md	抽屉面板
跑马灯	./components/n-marquee/SKILL.md	跑马灯动画
消息	./components/n-message/SKILL.md	Toast 消息
模态框	./components/n-modal/SKILL.md	模态容器
通知	./components/n-notification/SKILL.md	通知
气泡确认框	./components/n-popconfirm/SKILL.md	气泡确认框
气泡卡片	./components/n-popover/SKILL.md	气泡卡片
气泡选择器	./components/n-popselect/SKILL.md	气泡选择器
进度条	./components/n-progress/SKILL.md	进度条
结果页	./components/n-result/SKILL.md	结果页面
骨架屏	./components/n-skeleton/SKILL.md	加载骨架屏
加载动画	./components/n-spin/SKILL.md	加载旋转器
工具提示	./components/n-tooltip/SKILL.md	工具提示

布局组件（6）

组件	技能路径	描述
弹性布局	./components/n-flex/SKILL.md	弹性容器
网格	./components/n-grid/SKILL.md	网格系统
布局	./components/n-layout/SKILL.md	布局容器
旧版网格	./components/n-legacy-grid/SKILL.md	旧版网格
间距	./components/n-space/SKILL.md	间距
分割	./components/n-split/SKILL.md	分割面板

配置组件（3 个）

组件	技能路径	描述
配置提供器	./components/n-config-provider/SKILL.md	全局配置
元素	./components/n-element/SKILL.md	元素包装器
全局样式	./components/n-global-style/SKILL.md	全局样式

工具组件（4 个）

组件	技能路径	描述
折叠过渡	./components/n-collapse-transition/SKILL.md	折叠动画
离散 API	./components/n-discrete/SKILL.md	离散 API
滚动条	./components/n-scrollbar/SKILL.md	自定义滚动条
虚拟列表	./components/n-virtual-list/SKILL.md	虚拟滚动列表

使用示例

示例 1：用户询问按钮实现方式

用户请求：“如何创建带加载状态的主要按钮？”

Agent 操作：

1. 识别意图：组件技能 - 按钮
2. 定位技能：./components/n-button/SKILL.md
3. 阅读技能内容
4. 提供包含 API 参考和代码示例的答复

答复：

<template>
  <n-button type="primary" :loading="loading" @click="handleClick">
    {{ loading ? 'Loading...' : 'Submit' }}
  </n-button>
</template>

<script setup>
import { ref } from 'vue'

const loading = ref(false)

const handleClick = async () => {
  loading.value = true
  try {
    await submitData()
  } finally {
    loading.value = false
  }
}
</script>

示例 2：用户询问表单验证

用户请求：“如何创建带验证的表单？”

Agent 操作：

1. 识别意图：组件技能 - 表单
2. 定位技能：./components/n-form/SKILL.md
3. 阅读技能内容
4. 提供包含验证示例的答复

答复：

<template>
  <n-form ref="formRef" :model="form" :rules="rules">
    <n-form-item label="Name" path="name">
      <n-input v-model:value="form.name" />
    </n-form-item>
    <n-form-item>
      <n-button type="primary" @click="submitForm">Submit</n-button>
    </n-form-item>
  </n-form>
</template>

<script setup>
import { ref, reactive } from 'vue'

const formRef = ref()
const form = reactive({
  name: ''
})

const rules = {
  name: [
    { required: true, message: 'Please input name', trigger: 'blur' }
  ]
}

const submitForm = async () => {
  await formRef.value?.validate()
  // Submit logic
}
</script>

示例 3：用户询问主题自定义

用户请求：“如何自定义 Naive UI 主题颜色？”

Agent 操作：

1. 识别意图：基础技能 - 主题设置
2. 定位技能：./naive-ui-theming/SKILL.md
3. 阅读技能内容
4. 提供包含主题覆盖示例的答复

答复：

<template>
  <n-config-provider :theme-overrides="themeOverrides">
    <App />
  </n-config-provider>
</template>

<script setup>
const themeOverrides = {
  common: {
    primaryColor: '#18a058',
    primaryColorHover: '#36ad6a',
    primaryColorPressed: '#0c7a43'
  },
  Button: {
    textColor: '#18a058'
  }
}
</script>

示例 4：用户询问深色模式

用户请求：“如何在 Naive UI 中实现深色模式？”

Agent 操作：

1. 识别意图：基础技能 - 深色模式
2. 定位技能：./naive-ui-dark-mode/SKILL.md
3. 阅读技能内容
4. 提供包含实现示例的答复

答复：

<template>
  <n-config-provider :theme="isDark ? darkTheme : null">
    <App />
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme } from 'naive-ui'

const isDark = ref(false)
</script>

配置要求

先决条件

使用此技能库前，请确保：

1. 已安装 Vue 3.0+
2. 已安装 Naive UI 2.44+
3. 开发环境中使用 Node.js 18+

安装

npm install naive-ui
# or
pnpm add naive-ui

TypeScript 支持

Naive UI 使用 TypeScript 编写，开箱即提供完整的类型定义。

输入参数

调用技能时，请考虑以下参数：

参数	类型	描述	必填
component	string	组件名称（例如，“button”、“form”）	是
feature	string	所需的特定功能（例如，“validation”、“loading”）	否
context	object	附加上下文（框架、TypeScript 用法）	否

输出格式

每项技能均提供：

1. API 参考：完整的属性、事件、插槽和暴露项
2. 代码示例：可运行的代码片段
3. 最佳实践：推荐的实现模式
4. 常见问题：故障排除建议
5. 组件交互：如何与其他组件搭配使用

重要说明

1. 技能优先级

当多个技能都可能适用时，请按以下顺序优先选择：

1. 特定组件技能（最具体）
2. 基础技能（配置）
3. 设计规范技能（指南）

2. 交叉引用

许多技能会引用相关技能。请务必查看：

• 同一类别中的相关组件
• 用于配置的基础技能
• 用于样式指南的设计技能

3. 版本兼容性

此技能库基于 Naive UI 2.44+。较早版本可能不支持某些功能。

4. 命名约定

• 组件技能使用 n-{name} 格式（与 Vue 组件标签一致）
• 基础技能使用 naive-ui-{name} 格式
• 设计技能使用 naive-ui-design-{name} 格式

5. 文件结构

naive-ui-skills/
├── SKILL.md                          # This file (main entry)
├── README.md                         # English documentation
├── README_CN.md                      # Chinese documentation
├── AGENTS.md                         # Agents documentation
├── LICENSE                           # MIT License
├── components/                       # 95 component skills
│   ├── n-button/
│   │   └── SKILL.md
│   ├── n-form/
│   │   └── SKILL.md
│   └── ...
├── naive-ui-quickstart/              # Foundation skills
├── naive-ui-theming/
├── naive-ui-i18n/
├── naive-ui-dark-mode/
├── naive-ui-ssr/
├── naive-ui-components/
├── naive-ui-design-border/           # Design skills
├── naive-ui-design-color/
├── naive-ui-design-layout/
├── naive-ui-design-typography/
└── naive-ui-design-overview/

Agent 最佳实践

1. 当用户提及 Naive UI 时，始终从此文件开始
2. 根据用户意图找到具体的技能
3. 阅读完整的技能文件后再回复
4. 提供技能文档中的代码示例
5. 酌情引用相关技能
6. 纳入技能内容中的最佳实践
7. 如果与用户的上下文相关，请提及常见问题

相关资源

• Naive UI 文档
• Vue 3 文档
• Naive UI GitHub