djangoadmin/djangoadmin-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化更新

Browse Source
This commit is contained in:
gitadmin
2026-09-13 23:01:19 +08:00
parent 0c67b3e8b5
commit 23bd737b82
88 changed files with 2214 additions and 2503 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DjangoAdmin_Flask_NaiveVue/zh/volume4/frontend/components.md
+41 -33
View File
@@ -1,7 +1,7 @@
# 公共组件库
:::tip 说明
项目提供丰富的公共组件，位于 `ui/src/components/` 目录，基于 ElementPlus 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。组件通过 `src/plugins/` 中的 `setupCustomComponents` 全局注册，任何页面直接使用，无需单独 import。
项目提供丰富的公共组件，位于 `ui/src/components/` 目录，基于 NaiveUI 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。组件通过 `src/plugins/` 中的 `setupCustomComponents` 全局注册，任何页面直接使用，无需单独 import。
:::
## 组件总览
@@ -17,7 +17,7 @@
| CropperImage | `components/Cropper/` | 图片裁剪（圆形/矩形、实时预览） |
| QrCode | `components/Qrcode/` | 二维码生成（canvas/img、内嵌 logo） |
| ChinaArea | `components/ChinaArea/` | 省市区级联（懒加载、二/三级联动） |
| Icon | `components/icon/` | 图标（支持 ElementPlus 图标 + SVG 图标） |
| Icon | `components/icon/` | 图标（支持 SVG 图标 + @vicons 图标库） |
| BasicSelect | `components/Select/` | 增强下拉（远程请求、本地缓存） |
| CountTo | `components/CountTo/` | 数字动画（前缀/后缀、千分位、缓动曲线） |
| Password | `components/Password/` | 密码强度（强度指示器、重复确认、复杂度校验） |
@@ -38,7 +38,7 @@
## BasicTable 表格
表格组件是使用频率最高的组件，基于 `el-table` + `el-pagination` 封装，详见 [BasicTable 表格](/zh/volume4/frontend/table) 章节。
表格组件是使用频率最高的组件，基于 NaiveUI 的 `n-data-table` 封装，详见 [BasicTable 表格](/zh/volume4/frontend/table) 章节。
### Props
@@ -77,12 +77,12 @@
| 属性 | 类型 | 说明 |
|------|------|------|
| `label` | `string` | 列标题 |
| `prop` | `string` | 字段名 |
| `title` | `string` | 列标题 |
| `key` | `string` | 字段名 |
| `width` | `number` | 列宽 |
| `align` | `string` | 对齐方式 |
| `type` | `string` | 类型：`index` / `selection` |
| `render` | `Function` | 自定义渲染函数 `(column, row, index) => VNode` |
| `type` | `string` | 类型：`selection` / `index` |
| `render` | `Function` | 自定义渲染函数 `(record) => VNode` |
| `isSlot` | `boolean` | 是否使用插槽 |
| `ellipsis` | `boolean` | 超出省略（tooltip） |
| `auth` | `string[]` | 权限编码，控制列是否显示 |
@@ -94,7 +94,7 @@
|------|------|------|
| `fetch-success` | `(data, result)` | 数据请求成功 |
| `fetch-error` | `(error)` | 数据请求失败 |
| `selection-change` | `(rows)` | 多选变化 |
| `update:checked-row-keys` | `(keys)` | 多选变化 |
| `columns-change` | `(columns)` | 列设置变化 |
| `checked-row-change` | `(rowKeys)` | 选中行变化 |
@@ -104,7 +104,7 @@
|------|------|
| `tableTitle` | 表格标题左侧区域（常放添加按钮） |
| `toolbar` | 工具栏右侧区域 |
| `{prop}` | 列名对应插槽，自定义列渲染 |
| `{key}` | 列名对应插槽，自定义列渲染 |
### Expose 方法
@@ -129,18 +129,21 @@
<template>
<BasicTable :columns="columns" :request="loadDataTable" ref="tableRef">
<template #tableTitle>
<el-button v-perm="['sys:level:add']" type="primary" @click="handleAdd">
<el-icon><Plus /></el-icon>新增
</el-button>
<n-button v-perm="['sys:level:add']" type="primary" @click="handleAdd">
<template #icon><n-icon><PlusOutlined /></n-icon></template>
新增
</n-button>
</template>
</BasicTable>
</template>
<script setup lang="ts">
import { PlusOutlined } from '@vicons/antd';
const columns = [
{ label: '名称', prop: 'name', width: 200 },
{ label: '状态', prop: 'status', width: 100 },
{ label: '创建时间', prop: 'createTime', width: 180 },
{ title: '名称', key: 'name', width: 200 },
{ title: '状态', key: 'status', width: 100 },
{ title: '创建时间', key: 'createTime', width: 180 },
];
const actionColumn = {
@@ -228,13 +231,13 @@ async function loadDataTable({ page, pageSize }) {
|------|------|------|
| `field` | `string` | 字段名（必填） |
| `label` | `string` | 标签文字 |
| `component` | `ComponentType` | 渲染组件：`Input` / `Select` / `DatePicker` 等 |
| `component` | `ComponentType` | 渲染组件：`NInput` / `NSelect` / `NDatePicker` 等 |
| `componentProps` | `object` | 组件属性 |
| `defaultValue` | `any` | 默认值 |
| `rules` | `object \| object[]` | 字段校验规则 |
| `slot` | `string` | 自定义插槽名 |
| `hidden` | `boolean \| Function` | 是否隐藏 |
| `colProps` | `ColProps` | 栅格配置 |
| `gridProps` | `GridProps` | 栅格配置 |
| `labelMessage` | `string` | 标签提示信息 |
| `suffix` | `string` | 后缀文字 |
@@ -270,13 +273,13 @@ const [registerForm] = useForm({
{
field: 'name',
label: '名称',
component: 'Input',
component: 'NInput',
componentProps: { placeholder: '请输入名称' },
},
{
field: 'status',
label: '状态',
component: 'Select',
component: 'NSelect',
componentProps: {
options: [
{ label: '启用', value: 1 },
@@ -287,7 +290,7 @@ const [registerForm] = useForm({
{
field: 'dateRange',
label: '日期范围',
component: 'DatePicker',
component: 'NDatePicker',
componentProps: { type: 'daterange' },
},
],
@@ -299,7 +302,7 @@ const [registerForm] = useForm({
## BasicModal 弹窗
弹窗组件基于 `el-dialog` 封装，支持拖拽、自定义按钮，详见 [Modal 弹窗](/zh/volume4/frontend/modal) 章节。
弹窗组件基于 NaiveUI 的 `n-modal` 封装，支持拖拽、自定义按钮，详见 [Modal 弹窗](/zh/volume4/frontend/modal) 章节。
### Props
@@ -318,7 +321,8 @@ const [registerForm] = useForm({
| 事件 | 说明 |
|------|------|
| `ok` | 点击确认 |
| `on-ok` | 点击确认 |
| `on-close` | 点击关闭 |
| `register` | 弹窗注册回调 |
### Expose 方法
@@ -333,9 +337,9 @@ const [registerForm] = useForm({
```vue
<template>
<BasicModal title="编辑用户" :width="600" @register="registerModal" @ok="handleSubmit">
<basicModal title="编辑用户" :width="600" @register="registerModal" @on-ok="handleSubmit">
<BasicForm @register="registerForm" />
</BasicModal>
</basicModal>
</template>
<script setup lang="ts">
@@ -356,7 +360,7 @@ function handleEdit(record) {
## BasicUpload 上传
文件/图片上传组件，基于 `el-upload` 封装，支持卡片/列表模式、数量限制、图片预览。
文件/图片上传组件，基于 NaiveUI 的 `n-upload` 封装，支持卡片/列表模式、数量限制、图片预览。
### Props
@@ -698,10 +702,10 @@ async function getDeptOptions() {
<BasicTable :columns="columns" :request="loadData" />
<template #leftFooter>
<el-button @click="handleCancel">取消</el-button>
<n-button @click="handleCancel">取消</n-button>
</template>
<template #rightFooter>
<el-button type="primary" @click="handleSubmit">提交</el-button>
<n-button type="primary" @click="handleSubmit">提交</n-button>
</template>
</PageWrapper>
</template>
@@ -724,7 +728,7 @@ async function getDeptOptions() {
```vue
<template>
<Authority :value="['sys:user:add']">
<el-button type="primary">新增用户</el-button>
<n-button type="primary">新增用户</n-button>
</Authority>
</template>
```
@@ -732,7 +736,7 @@ async function getDeptOptions() {
:::tip v-perm 指令
除了 `Authority` 组件，项目还提供 `v-perm` 指令，功能相同但更简洁：
```vue
<el-button v-perm="['sys:user:add']">新增用户</el-button>
<n-button v-perm="['sys:user:add']">新增用户</n-button>
```
:::
@@ -740,7 +744,7 @@ async function getDeptOptions() {
## Icon 图标
统一图标组件，支持 ElementPlus 图标和 SVG 图标。
统一图标组件，支持 SVG 图标和 @vicons 图标库。
### Props
@@ -754,11 +758,15 @@ async function getDeptOptions() {
```vue
<template>
<!-- ElementPlus 图标 -->
<Icon name="el-icon-Plus" size="18px" />
<!-- SVG 图标 -->
<Icon name="svg-icon-user" />
<!-- @vicons 图标 -->
<n-icon size="18"><PlusOutlined /></n-icon>
</template>
<script setup>
import { PlusOutlined } from '@vicons/antd';
</script>
```
---
@@ -836,4 +844,4 @@ setupCustomComponents(app); // 注册所有自定义组件
## 总结
公共组件库基于 ElementPlus 二次封装，核心三件套 BasicTable（表格）、BasicForm（表单）、BasicModal（弹窗）覆盖列表页标准场景。辅以 Upload、Editor、Cropper 等业务组件，以及 Authority、v-perm 权限体系。通过全局注册，任何页面直接使用，无需单独 import。优先使用公共组件，避免重复开发。
公共组件库基于 NaiveUI 二次封装，核心三件套 BasicTable（表格）、BasicForm（表单）、BasicModal（弹窗）覆盖列表页标准场景。辅以 Upload、Editor、Cropper 等业务组件，以及 Authority、v-perm 权限体系。通过全局注册，任何页面直接使用，无需单独 import。优先使用公共组件，避免重复开发。