dydx-naive-ui-for-vue

DYDX Native UI for Vue

默认文档语言为中文。For English, see README.en.md.

基于 Naive UI 的 Vue 3 业务组件库，提供表单、表格、弹窗表单、富文本、上传、图标选择、验证码输入以及响应式配置能力。

特性

• Schema 驱动表单，支持 custom、slot、dynamic-group
• 基于 Tiptap 的富文本组件，支持 HTML / JSON、完整工具栏、图片/视频/附件上传，以及 DOCX / Excel 导入
• 高级表格封装，支持工具栏、列设置、持久化、操作列、移动端卡片
• 表单弹窗 / 抽屉，适合新增、编辑、详情等 CRUD 场景
• 自定义上传封装，支持 string / string[] / object[] 三种值模型，并提供大文件分片上传组件
• 验证码输入组件，集成 OTP 输入与发送倒计时
• 全局响应式配置，可统一控制表单、弹窗、抽屉、表格在移动端 / 平板下的行为
• TypeScript 全量类型导出，支持 unplugin-vue-components Resolver

包含内容

组件

组合式函数与工具

安装

环境要求

• Node.js >= 16
• Vue >= 3.3
• Naive UI >= 2.34

安装依赖

pnpm add dydx-naive-ui-for-vue naive-ui vue

本地开发

pnpm install
pnpm dev

构建与检查

pnpm run check
pnpm run build:lib

快速开始

全量注册

import { createApp } from 'vue'
import App from './App.vue'
import DydxNativeUI from 'dydx-naive-ui-for-vue'
import 'dydx-naive-ui-for-vue/style.css'

const app = createApp(App)
app.use(DydxNativeUI)
app.mount('#app')

按需引入

import {
  DydxNaiveForm,
  DydxNaiveTable,
  DydxFormModal,
  DydxFormDrawer,
  DydxRichText,
  DydxUpload,
  DydxLargeUpload,
  DydxIconSelect,
  DydxVerificationCode,
  DydxFilePreview,
  useResponsive,
  setupResponsive,
  DydxNaiveUIResolver
} from 'dydx-naive-ui-for-vue'

import 'dydx-naive-ui-for-vue/style.css'

自动按需引入

import { defineConfig } from 'vite'
import Components from 'unplugin-vue-components/vite'
import { DydxNaiveUIResolver } from 'dydx-naive-ui-for-vue'

export default defineConfig({
  plugins: [
    Components({
      resolvers: [DydxNaiveUIResolver()]
    })
  ]
})

DydxNaiveUIResolver() 只处理 Dydx 前缀的 PascalCase 组件名。

仓库约定

• 源码仓库以组件源码、类型、文档和构建配置为主
• npm 包用于分发构建产物
• 公开仓库默认不提交本地私有发布脚本

参与贡献

• 提交问题或需求建议前，建议先搜索现有 Issues
• 贡献代码前，请先阅读 CONTRIBUTING.md
• 安全问题请参考 SECURITY.md 私下反馈
• 行为约定请参考 CODE_OF_CONDUCT.md

关键设计说明

表格不是 request 风格 API

DydxNaiveTable 没有内置 request / fetchData 之类的请求式接口。正确用法是：

1. 外层自己请求数据
2. 将结果回填给 data
3. 将分页状态回填给 pagination
4. 在 page-change、update:pagination、onRefresh 等时机重新触发请求

上传走 customUpload

DydxUpload 的真实上传入口是 customUpload(file, onProgress)，组件内部统一走 NUpload 的 custom-request。Naive UI 原生的 action、headers、data 等参数可以透传，但不应当被视为该封装组件的主上传流程。

大文件上传走适配器

DydxLargeUpload 负责分片、断点跳过、单文件分片并发、文件任务并发、暂停、继续和重试；真实请求由 chunkUploadAdapter 提供。组件不会内置 fetch、axios 或任何具体后端协议。

上传支持全局默认配置

图片上传、附件上传和大文件上传分别支持全局配置默认上传方法与基础校验项。单个组件 props 或 FormSchema.props 会覆盖全局配置。

import {
  setFileUploadConfig,
  setImageUploadConfig,
  setLargeUploadConfig
} from 'dydx-naive-ui-for-vue'

setImageUploadConfig({
  customUpload: uploadImage,
  urlKey: 'imageUrl',
  nameKey: 'imageName',
  valueType: 'objectArray'
})

setFileUploadConfig({
  customUpload: uploadFile,
  urlKey: 'fileUrl',
  nameKey: 'fileName',
  valueType: 'objectArray'
})

setLargeUploadConfig({
  chunkUploadAdapter: largeUploadAdapter,
  concurrency: 3,
  taskConcurrency: 2
})

富文本支持全局默认配置

DydxRichText 支持通过 setRichTextConfig() 设置全局默认的值模型、占位文案、默认格式、双格式刷、组件高度、新插入图片默认保存宽度、工具栏开关、图片 / 视频 / 附件上传方法、媒体额外 attrs 白名单与写入前 formatter，并允许在组件 props 或 FormSchema.props 中单独覆盖。默认格式不会反复覆盖用户的工具栏选择：组件加载后会把字体、字号、字色等行内格式设置为默认输入状态，只影响后续手动输入；初始化已有内容不会被重绘或改写。图片默认保存宽度为 50%，会写入新插入图片的 width attrs，保存为 HTML / JSON 后在其他页面回显也保持该宽度；不压缩上传文件，已有宽度和历史内容不会被重写；传 100% 可恢复旧插入宽度，传 none 可取消自动写入 width。行高、首行缩进、对齐和标题等块级格式只会自动落到空编辑器或当前空段落上；只有“刷默认格式”命令会把默认格式显式应用到当前选区。默认工具栏会显示正文行高、格式刷和全屏；正文行高只修改段落/标题的 line-height，未显式设置时使用“默认行高（1.5）”，普通段落默认不再保留上下 margin，不影响表格尺寸面板里的单元格行高。“刷默认格式”默认隐藏，可通过 formatPainter.showDefaultFormatButton: true 启用，也可通过 disabledMenus: ['lineHeight', 'defaultFormat', 'formatPainter', 'fullscreen'] 禁用。全屏为页面内全屏，不调用浏览器 Fullscreen API；进入全屏时锁定背后页面滚动，退出或组件卸载时恢复进入全屏前的页面滚动样式；再次点击按钮或按 Esc 可退出。移动端内置工具栏会保留撤销、重做、加粗、斜体、图片、更多和全屏，其他工具进入底部抽屉；平板和 PC 端继续展示完整工具栏。格式刷复制源格式后，完成选择目标文本并松开鼠标会自动应用并退出格式刷；高亮状态下再次点击格式刷图标可取消。默认工具栏会显示字数统计，图片 / 视频 / 附件数量可通过 showImageCount、showVideoCount、showAttachmentCount 按实例开启。

import { setRichTextConfig } from 'dydx-naive-ui-for-vue'

setRichTextConfig({
  defaultValueFormat: 'html',
  defaultFormat: {
    fontFamily: '"Microsoft YaHei", sans-serif',
    fontSize: '16px',
    lineHeight: 1.8,
    textColor: '#1f2937'
  },
  formatPainter: {
    enabledKeys: ['fontFamily', 'fontSize', 'lineHeight', 'textColor'],
    showDefaultFormatButton: true,
    showFormatPainterButton: true
  },
  height: '520px',
  imageMaxWidth: '50%',
  mediaExtraAttrs: ['assetId', 'sourceType'],
  mediaUploadOptions: {
    image: {
      multiple: true,
      maxUploadCount: 9
    },
    video: {
      multiple: true,
      maxUploadCount: 3
    },
    attachment: {
      multiple: true,
      maxUploadCount: 9
    }
  },
  customImageUpload: async (file, onProgress) => {
    onProgress(100)
    return URL.createObjectURL(file)
  },
  customVideoUpload: async (file, onProgress) => {
    onProgress(100)
    return {
      url: URL.createObjectURL(file),
      width: 640,
      height: 360
    }
  },
  customAttachmentUpload: async (file, onProgress) => {
    onProgress(100)
    return {
      url: `/uploads/${file.name}`,
      name: file.name,
      size: file.size,
      mime: file.type
    }
  }
})

富文本当前公开导出还包括：

• 组件：DydxRichText
• 配置方法：setRichTextConfig / getRichTextConfig / resetRichTextConfig / defineRichTextMediaAttrsFormatters
• 选项数据：RICH_TEXT_FONT_FAMILY_OPTIONS / RICH_TEXT_FONT_SIZE_OPTIONS / RICH_TEXT_LINE_HEIGHT_OPTIONS，每项同时提供 key 和 value，可直接复用到富文本工具栏与表单下拉；正文行高默认项为 默认行高（1.5），显式选项为 1.6 / 1.75 / 1.85 / 2
• 类型：DydxRichTextProps、DydxRichTextExpose、RichTextConfig、RichTextDefaultFormat、RichTextFormatKey、RichTextFormatPainterConfig、RichTextValueFormat、RichTextMenuKey、RichTextContentStats、RichTextToolbarStatKey、RichTextToolbarStatsVisibility、RichTextToolbarStatItem、RichTextImageAttrs、RichTextVideoAttrs、RichTextAttachmentAttrs、RichTextMediaUploadOptions、RichTextMediaUploadOptionsMap、RichTextMediaAttrsFormatters、RichTextLinkAttrs、RichTextResources、RichTextOption

除了组件内的图片 / 视频 / 附件上传外，富文本还支持 Office 内容导入：

• importOfficeHtml(html, options?) 处理粘贴进来的 Office HTML
• importDocxFile(file) / importDocxFiles(files) / openDocxDialog() 导入 .docx 文件
• openExcelDialog() / insertExcelFiles(files) 导入 .xls / .xlsx / .xlsm / .xlsb 文件

其中 source: 'excel' 的 importOfficeHtml() 会尽量保留表格宽度、行高、单元格样式和对齐信息。

文件预览

DydxFilePreview 提供通用文件预览能力，支持图片、普通视频、FLV/HLS 流、docx / xls / xlsx / csv / pptx / pdf / ofd，弹窗与内联双模式；重型渲染库全部按需动态加载。文件预览当前公开导出包括：

• 组件：DydxFilePreview
• 配置方法：setFilePreviewConfig / getFilePreviewConfig / resetFilePreviewConfig
• 工具函数：inferFilePreviewType / normalizePreviewSource / resolveDownloadFilename
• 类型：FilePreviewType、FilePreviewSource、DydxFilePreviewProps、DydxFilePreviewEmits、DydxFilePreviewExpose、FilePreviewConfig、InferFilePreviewTypeOptions、NormalizedPreviewSource、ResolveDownloadFilenameOptions

远程跨域地址是否能够直接下载由浏览器同源策略及服务端 Content-Disposition 响应头决定；浏览器忽略 download 属性时，组件会在新窗口打开资源，不会替换当前业务页面。

<template>
  <n-button @click="visible = true">预览文件</n-button>
  <DydxFilePreview
    v-model:visible="visible"
    src="https://example.com/合同.pdf"
    filename="合同.pdf"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const visible = ref(false)
</script>

响应式默认不启用

responsiveConfig.enabled 的全局初始值为 false。只有调用 setupResponsive() 后才会开始按移动端 / 平板配置覆盖表单、弹窗、抽屉和表格行为。富文本高度不走响应式配置，统一通过 height 或 setRichTextConfig({ height }) 控制。

import { setupResponsive, setDeviceConfig } from 'dydx-naive-ui-for-vue'

setupResponsive({ enabled: true })

setDeviceConfig('mobile', {
  modal: { width: '96%' },
  table: {
    size: 'small',
    actionColumnWidth: 96,
    actionColumnMaxVisible: 1
  }
})

运行时设备态与配置类型不同

• 配置层 DeviceType 只包含 mobile | tablet
• 运行时 device / useResponsive() 可能返回 pc
• 在组件外、SSR 或特殊入口场景下，如果需要提前拿到设备态，请手动调用 initResponsiveListener()

常见场景

表单

<script setup lang="ts">
import { ref } from 'vue'
import type { FormSchema } from 'dydx-naive-ui-for-vue'

const model = ref({ name: '', status: '' })

const schemas: FormSchema<typeof model.value>[] = [
  {
    type: 'input',
    name: 'name',
    label: '名称',
    required: true
  },
  {
    type: 'select',
    name: 'status',
    label: '状态',
    props: {
      options: [
        { label: '启用', value: '1' },
        { label: '禁用', value: '0' }
      ]
    }
  }
]
</script>

<template>
  <DydxNaiveForm v-model:model="model" :schemas="schemas" />
</template>

富文本

<script setup lang="ts">
import { ref } from 'vue'

const content = ref('<p>欢迎使用富文本组件</p>')
</script>

<template>
  <DydxRichText v-model="content" />
</template>

如果在表单里使用富文本，FormSchema 可直接写：

{
  type: 'rich-text',
  name: 'content',
  label: '正文',
  props: {
    valueFormat: 'html',
    disabledMenus: ['video'],
    attachmentOptions: {
      accept: ['.pdf', '.docx']
    }
  }
}

如需在提交表单时同步资源清单，可在 props.extractResources 中接收 { images, videos, attachments, links } 分组对象；其中 links 只包含普通文本超链接，不重复包含附件下载链接。

表格

<script setup lang="ts">
import { ref } from 'vue'
import type { DydxTableColumn, TablePagination } from 'dydx-naive-ui-for-vue'

interface UserRow {
  id: number
  name: string
  status: number
}

const data = ref<UserRow[]>([])
const pagination = ref<TablePagination>({
  page: 1,
  pageSize: 10,
  total: 0
})

// 分页默认读取 total 并显示“共 X 条”；可通过 pagination.prefix 覆盖或隐藏文案。

const columns: DydxTableColumn<UserRow>[] = [
  { key: 'name', title: '姓名', width: 140 },
  {
    key: 'status',
    title: '状态',
    columnType: 'tag',
    tagOptions: [
      { label: '启用', value: 1, type: 'success' },
      { label: '禁用', value: 0, type: 'warning' }
    ]
  }
]
</script>

<template>
  <DydxNaiveTable
    :data="data"
    :columns="columns"
    row-key="id"
    remote
    v-model:pagination="pagination"
  />
</template>

开发

pnpm dev
pnpm check
pnpm build

相关文档

• NaiveForm
• RichText
• NaiveTable
• FormModal
• NaiveUpload
• VerificationCode
• Composables

致谢

本项目建立在许多优秀的开源项目之上，尤其感谢以下生态与维护者：

• Vue
• Naive UI
• Tiptap
• unplugin-vue-components
• vue-draggable-plus
• SheetJS
• JSZip
• Ionicons / @vicons

更详细的依赖声明与许可证说明请参考 ACKNOWLEDGEMENTS.md。

许可证

MIT