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 18:12:07 +08:00
parent 7f758cc6e9
commit d7a081e8b7
92 changed files with 2429 additions and 1117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DjangoAdmin_Django_AntdVue/zh/course.md
+3 -3
View File
@@ -95,7 +95,7 @@ DJANGO_DEMO=False
# ==================== 数据库配置 ====================
DATABASE_ENGINE=django.db.backends.mysql
DATABASE_NAME=djangoadmin.django.elevue
DATABASE_NAME=djangoadmin.django.antdvue
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
@@ -109,13 +109,13 @@ REDIS_PASSWORD=your_redis_password
REDIS_DB=0
# ==================== 文件配置 ====================
DJANGO_FILE_URL=http://file.django.elevue
DJANGO_FILE_URL=http://file.django.antdvue
```
:::danger 重要提示
`DATABASE_NAME` 需要提前在 MySQL 中创建对应的数据库：
```sql
CREATE DATABASE `djangoadmin.django.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE DATABASE `djangoadmin.django.antdvue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```
:::
DjangoAdmin_Django_AntdVue/zh/introduction.md
+2 -2
View File
@@ -56,8 +56,8 @@
+ 软件作者：@小蚂蚁云团队
+ 软件协议：Apache-2.0
+ 官网网址：[https://www.djangoadmin.cn](https://www.djangoadmin.cn)
+ 文档网址：[http://docs.django.elevue.djangoadmin.cn](http://docs.django.elevue.djangoadmin.cn)
+ 演示地址：[http://manage.django.elevue.djangoadmin.cn](http://manage.django.elevue.djangoadmin.cn)
+ 文档网址：[http://docs.django.antdvue.djangoadmin.cn](http://docs.django.antdvue.djangoadmin.cn)
+ 演示地址：[http://manage.django.antdvue.djangoadmin.cn](http://manage.django.antdvue.djangoadmin.cn)
## 软件版本
DjangoAdmin_Django_AntdVue/zh/volume1/backend.md
+5 -5
View File
@@ -142,7 +142,7 @@ vim .env
# ============================================================
# 基础配置
# ============================================================
DJANGO_NAME=Django+EleVue旗舰版
DJANGO_NAME=Django+AntDesign旗舰版
DJANGO_VERSION=v3.0.0
DJANGO_DEBUG=True
DJANGO_DEMO=False # 默认值为True（演示模式），开发时请设为False
@@ -151,7 +151,7 @@ DJANGO_DEMO=False # 默认值为True（演示模式），开
# 数据库配置（根据实际情况修改）
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.elevue'
DATABASE_NAME='djangoadmin.django.antdvue'
DATABASE_HOST="127.0.0.1"
DATABASE_PORT=3306
DATABASE_USER="root"
@@ -185,7 +185,7 @@ REDIS_DB=0
```sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.django.elevue`
CREATE DATABASE `djangoadmin.django.antdvue`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;
```
@@ -210,7 +210,7 @@ python manage.py migrate
```bash
# 使用 mysql 命令行导入
mysql -uroot -p djangoadmin.django.elevue < document/mysql/djangoadmin.django.elevue.sql
mysql -uroot -p djangoadmin.django.antdvue < document/mysql/djangoadmin.django.antdvue.sql
```
:::tip 种子数据说明
@@ -321,7 +321,7 @@ lsof -i :8000
```
1. MySQL 服务是否已启动
2. .env 中的 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD 是否正确
3. 数据库 djangoadmin.django.elevue 是否已创建
3. 数据库 djangoadmin.django.antdvue 是否已创建
4. 防火墙是否放行了数据库端口
```
DjangoAdmin_Django_AntdVue/zh/volume1/database.md
+10 -10
View File
@@ -17,7 +17,7 @@
```sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.django.elevue`
CREATE DATABASE `djangoadmin.django.antdvue`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;
@@ -26,7 +26,7 @@ SHOW DATABASES;
```
:::tip 温馨提示
数据库名称需要与 `.env` 文件中的 `DATABASE_NAME` 配置一致，默认为 `djangoadmin.django.elevue`。
数据库名称需要与 `.env` 文件中的 `DATABASE_NAME` 配置一致，默认为 `djangoadmin.django.antdvue`。
:::
## 第二步：配置数据库连接
@@ -38,7 +38,7 @@ SHOW DATABASES;
# 数据库配置
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql" # 数据库引擎
DATABASE_NAME='djangoadmin.django.elevue' # 数据库名称
DATABASE_NAME='djangoadmin.django.antdvue' # 数据库名称
DATABASE_HOST="127.0.0.1" # 数据库地址
DATABASE_PORT=3306 # 数据库端口
DATABASE_USER="root" # 数据库用户名
@@ -105,7 +105,7 @@ python manage.py migrate application.user 0001
```bash
# 使用 mysql 命令行导入
mysql -uroot -p djangoadmin.django.elevue < document/mysql/djangoadmin.django.elevue.sql
mysql -uroot -p djangoadmin.django.antdvue < document/mysql/djangoadmin.django.antdvue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件
```
@@ -223,20 +223,20 @@ python generator.py --config config.json
```bash
# 备份数据库
mysqldump -uroot -p djangoadmin.django.elevue > backup.sql
mysqldump -uroot -p djangoadmin.django.antdvue > backup.sql
# 恢复数据库
mysql -uroot -p djangoadmin.django.elevue < backup.sql
mysql -uroot -p djangoadmin.django.antdvue < backup.sql
```
+ PostgreSQL 备份
```bash
# 备份数据库
pg_dump -U postgres djangoadmin.django.elevue > backup.sql
pg_dump -U postgres djangoadmin.django.antdvue > backup.sql
# 恢复数据库
psql -U postgres djangoadmin.django.elevue < backup.sql
psql -U postgres djangoadmin.django.antdvue < backup.sql
```
+ SQLite 备份
@@ -254,10 +254,10 @@ cp db_backup.sqlite3 db.sqlite3
数据库初始化的核心步骤：
```
1. 创建数据库：CREATE DATABASE `djangoadmin.django.elevue`
1. 创建数据库：CREATE DATABASE `djangoadmin.django.antdvue`
2. 配置 .env：设置 DATABASE_ENGINE、DATABASE_NAME 等连接信息
3. 执行迁移：python manage.py makemigrations && python manage.py migrate
4. 导入初始数据：mysql ... < document/mysql/djangoadmin.django.elevue.sql
4. 导入初始数据：mysql ... < document/mysql/djangoadmin.django.antdvue.sql
```
后续的模型变更通过 Django 迁移系统管理（`makemigrations` + `migrate`），确保数据库结构与代码保持同步。如需使用代码生成器创建新模块，生成器会自动处理数据库迁移。
DjangoAdmin_Django_AntdVue/zh/volume1/docker.md
+12 -12
View File
@@ -56,7 +56,7 @@ cp .env.example .env
# 说明：连接 Docker 容器中运行的 MySQL 数据库
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.elevue'
DATABASE_NAME='djangoadmin.django.antdvue'
DATABASE_HOST=127.0.0.1 # 数据库主机地址（本地容器）
DATABASE_PORT=3306 # 数据库端口（MySQL 默认 3306）
DATABASE_USER=root # 数据库用户名
@@ -80,7 +80,7 @@ REDIS_DB=0 # Redis 数据库索引
```yaml
# +======================================================================
# | 模块: Docker Compose 配置
# | 说明: Django+EleVue 应用服务容器编排
# | 说明: Django+AntDesign 应用服务容器编排
# +======================================================================
version: '3.7'
# ============================================================
@@ -90,11 +90,11 @@ services:
# ------------------------------------------------------------
# 后端服务
# ------------------------------------------------------------
django_elevue:
django_antdvue:
# 构建镜像名称
image: django_elevue
image: django_antdvue
# 容器运行时名称
container_name: django_elevue
container_name: django_antdvue
# 镜像构建配置
build:
context: ./ # 构建上下文路径（项目根目录）
@@ -168,7 +168,7 @@ docker compose up -d
[+] Building 45.2s (12/12) FINISHED
[+] Running 2/2
✔ Network djangoadmin_default Created
✔ Container django_elevue Started
✔ Container django_antdvue Started
```
:::tip 访问服务
@@ -202,7 +202,7 @@ docker compose logs -f
docker compose logs --tail 100
# 查看指定服务日志
docker compose logs -f django_elevue
docker compose logs -f django_antdvue
```
+ 停止与重启
@@ -232,10 +232,10 @@ docker compose up --build
```bash
# 进入运行中的容器终端
docker compose exec django_elevue bash
docker compose exec django_antdvue bash
# 在容器内执行 Django 命令
docker compose exec django_elevue python manage.py shell
docker compose exec django_antdvue python manage.py shell
```
## 环境变量注入
@@ -244,10 +244,10 @@ Docker 模式下，环境变量通过 `env_file` 从 `.env` 文件注入到容
```bash
# 使用 --env-file 指定环境变量文件
docker run --env-file .env django_elevue
docker run --env-file .env django_antdvue
# 通过 -e 参数覆盖单个变量
docker run -e DJANGO_DEBUG=False django_elevue
docker run -e DJANGO_DEBUG=False django_antdvue
```
:::tip 温馨提示
@@ -302,7 +302,7 @@ ports:
```bash
# 查看容器日志排查原因
docker compose logs django_elevue
docker compose logs django_antdvue
```
常见原因：数据库连接失败、Redis 连接失败、数据库未创建。
DjangoAdmin_Django_AntdVue/zh/volume1/env-vars.md
+6 -6
View File
@@ -12,12 +12,12 @@
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| `DJANGO_NAME` | `Django+EleVue旗舰版` | 应用名称，用于界面显示和系统标识 |
| `DJANGO_NAME` | `Django+AntDesign旗舰版` | 应用名称，用于界面显示和系统标识 |
| `DJANGO_VERSION` | `v3.0.0` | 应用版本号 |
| `DJANGO_DEBUG` | `True` | 是否开启调试模式。`True` 时输出详细错误堆栈，生产环境务必设为 `False` |
| `DJANGO_DEMO` | `True` | 是否开启演示模式。`True` 时所有写操作（add/update/delete/status）返回"演示环境，暂无操作权限"。**开发调试时请设为 `False`** |
| `DJANGO_UPLOAD_DIR` | `项目根目录/public/uploads` | 文件上传存储路径 |
| `DJANGO_FILE_URL` | `http://file.django.elevue` | 文件访问域名，用于拼接上传文件的访问 URL |
| `DJANGO_FILE_URL` | `http://file.django.antdvue` | 文件访问域名，用于拼接上传文件的访问 URL |
:::tip 安全提示
1. 生产环境务必设置 `DJANGO_DEBUG=False`，调试模式会输出详细的错误堆栈信息，可能泄漏内部实现细节。
@@ -29,7 +29,7 @@
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| `DATABASE_ENGINE` | `django.db.backends.mysql` | 数据库引擎。支持：`mysql`、`postgresql`、`sqlite3`、`oracle`、`mssql` |
| `DATABASE_NAME` | `djangoadmin.django.elevue` | 数据库名称。SQLite 时作为数据库文件路径 |
| `DATABASE_NAME` | `djangoadmin.django.antdvue` | 数据库名称。SQLite 时作为数据库文件路径 |
| `DATABASE_HOST` | `127.0.0.1` | 数据库地址 |
| `DATABASE_PORT` | `3306` | 数据库端口 |
| `DATABASE_USER` | `root` | 数据库账号 |
@@ -142,7 +142,7 @@ Redis 用于存储验证码、JWT 令牌黑名单等功能，是项目正常运
# ============================================================
# 应用配置
# ============================================================
DJANGO_NAME=Django+EleVue旗舰版
DJANGO_NAME=Django+AntDesign旗舰版
DJANGO_VERSION=v3.0.0
DJANGO_DEBUG=True
DJANGO_DEMO=False # 代码默认True（演示模式），开发环境设为False以启用写操作
@@ -153,7 +153,7 @@ DJANGO_FILE_URL='http://file.django.antdvue'
# 数据库配置
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.elevue'
DATABASE_NAME='djangoadmin.django.antdvue'
DATABASE_HOST="127.0.0.1"
DATABASE_PORT=3306
DATABASE_USER="root"
@@ -200,7 +200,7 @@ extends/extends_dotenv.py
│ 3. 调用 load_dotenv(env_path) 注入环境变量
▼
config/env.py
│ os.getenv('DJANGO_NAME', 'Django+EleVue旗舰版')
│ os.getenv('DJANGO_NAME', 'Django+AntDesign旗舰版')
│ os.getenv('DATABASE_HOST', '127.0.0.1')
│ ...（所有配置项）
▼
DjangoAdmin_Django_AntdVue/zh/volume1/environment.md
+1 -1
View File
@@ -127,7 +127,7 @@ mysql>
```sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.django.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE DATABASE `djangoadmin.django.antdvue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
-- 查看数据库
SHOW DATABASES;
DjangoAdmin_Django_AntdVue/zh/volume1/faq.md
+1 -1
View File
@@ -83,7 +83,7 @@ mysql -h127.0.0.1 -P3306 -uroot -p
# 如果是权限问题，授权用户
mysql -uroot -p
GRANT ALL PRIVILEGES ON `djangoadmin.django.elevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON `djangoadmin.django.antdvue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;
```
DjangoAdmin_Django_AntdVue/zh/volume3/directory.md
+2 -2
View File
@@ -150,14 +150,14 @@ config/
```python
# 应用配置
DJANGO_NAME = os.getenv('DJANGO_NAME', 'Django+EleVue旗舰版')
DJANGO_NAME = os.getenv('DJANGO_NAME', 'Django+AntDesign旗舰版')
DJANGO_VERSION = os.getenv('DJANGO_VERSION', 'v3.0.0')
DJANGO_DEBUG = (os.getenv('DJANGO_DEBUG', 'True') == 'True')
DJANGO_DEMO = (os.getenv('DJANGO_DEMO', 'True') == 'True')
# 数据库配置
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.antdvue')
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
DATABASE_PORT = os.getenv('DATABASE_PORT', 3306)
DATABASE_PREFIX = os.getenv('DATABASE_PREFIX', "django_")
DjangoAdmin_Django_AntdVue/zh/volume3/tech-stack.md
+1 -1
View File
@@ -49,7 +49,7 @@ CACHES = {
**配置说明**（`config/env.py`）：
```python
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.antdvue')
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
DATABASE_PORT = os.getenv('DATABASE_PORT', 3306)
DATABASE_USER = os.getenv('DATABASE_USER', 'root')
DjangoAdmin_Django_AntdVue/zh/volume4/frontend/build.md
+1 -1
View File
@@ -191,7 +191,7 @@ import { defineStore } from 'pinia'; // 自动
window.__{SHORT_NAME}__PRODUCTION__CONF__ = {
"VITE_GLOB_API_URL": "",
"VITE_GLOB_API_URL_PREFIX": "/api",
"VITE_GLOB_FILE_URL": "http://file.django.elevue",
"VITE_GLOB_FILE_URL": "http://file.django.antdvue",
"VITE_GLOB_APP_TITLE": "Django+AntDesign版",
// ...
};
DjangoAdmin_Django_AntdVue/zh/volume4/integration/proxy.md
+1 -1
View File
@@ -157,7 +157,7 @@ location /uploads/ {
```
:::tip 温馨提示
后端的文件访问地址需要与前端 `DJANGO_FILE_URL` 配置一致。开发环境为 `http://file.django.elevue`，生产环境需要配置为实际的文件服务域名。
后端的文件访问地址需要与前端 `DJANGO_FILE_URL` 配置一致。开发环境为 `http://file.django.antdvue`，生产环境需要配置为实际的文件服务域名。
:::
## 总结
DjangoAdmin_Django_AntdVue/zh/volume4/tools/db-session.md
+1 -1
View File
@@ -15,7 +15,7 @@
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
# 数据库名称
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.antdvue')
# 数据库地址
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
DjangoAdmin_Django_AntdVue/zh/volume4/tools/upload-guide.md
+3 -3
View File
@@ -29,7 +29,7 @@
| 变量 | 默认值 | 说明 |
|:----|:----|:----|
| `DJANGO_UPLOAD_DIR` | `{项目根目录}/public/uploads` | 上传文件存储目录 |
| `DJANGO_FILE_URL` | `http://file.django.elevue` | 文件访问域名 |
| `DJANGO_FILE_URL` | `http://file.django.antdvue` | 文件访问域名 |
| `DJANGO_TEMP_PATH` | `{DJANGO_UPLOAD_DIR}/temp` | 临时文件目录 |
## 上传接口
@@ -66,7 +66,7 @@ file: <文件>
"fileSize": 306995,
"fileName": "2025030614302512345.jpg",
"filePath": "/temp/20250306/2025030614302512345.jpg",
"fileUrl": "http://file.django.elevue/temp/20250306/2025030614302512345.jpg"
"fileUrl": "http://file.django.antdvue/temp/20250306/2025030614302512345.jpg"
},
"ok": true
}
@@ -118,7 +118,7 @@ public/uploads/
上传成功后返回的 `fileUrl` 是拼接了 `DJANGO_FILE_URL` 前缀的完整 URL：
```
http://file.django.elevue/temp/20250306/2025030614302512345.jpg
http://file.django.antdvue/temp/20250306/2025030614302512345.jpg
```
Service 层的 `get_file_url()` 会自动为文件字段补此前缀。
DjangoAdmin_Django_AntdVue/zh/volume4/tools/upload.md
+2 -2
View File
@@ -26,7 +26,7 @@ DJANGO_UPLOAD_DIR = os.getenv('DJANGO_UPLOAD_DIR', os.path.join(DJANGO_ROOT_PATH
DJANGO_TEMP_PATH = DJANGO_UPLOAD_DIR + '/temp'
# 文件访问域名
DJANGO_FILE_URL = os.getenv('DJANGO_FILE_URL', 'http://file.django.elevue')
DJANGO_FILE_URL = os.getenv('DJANGO_FILE_URL', 'http://file.django.antdvue')
```
:::tip 温馨提示
@@ -70,7 +70,7 @@ Authorization: Bearer <token>
"fileSize": 306995,
"fileName": "2025030614302512345.jpg",
"filePath": "/temp/20250306/2025030614302512345.jpg",
"fileUrl": "http://file.django.elevue/temp/20250306/2025030614302512345.jpg"
"fileUrl": "http://file.django.antdvue/temp/20250306/2025030614302512345.jpg"
},
"ok": true
}
DjangoAdmin_Django_AntdVue/zh/volume6/backup.md
+5 -5
View File
@@ -18,11 +18,11 @@
# 使用 mysqldump 备份单个数据库
mysqldump -h 127.0.0.1 -u root -p --single-transaction \
--routines --triggers --events \
djangoadmin.django.elevue > backup_$(date +%Y%m%d_%H%M%S).sql
djangoadmin.django.antdvue > backup_$(date +%Y%m%d_%H%M%S).sql
# 压缩备份
mysqldump -h 127.0.0.1 -u root -p --single-transaction \
djangoadmin.django.elevue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
djangoadmin.django.antdvue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
```
:::tip --single-transaction 作用
@@ -100,7 +100,7 @@ mkdir -p ${BACKUP_DIR}/{mysql,redis,uploads}
# MySQL 备份
mysqldump -h 127.0.0.1 -u djangoadmin -p'<密码>' \
--single-transaction djangoadmin.django.elevue | gzip > \
--single-transaction djangoadmin.django.antdvue | gzip > \
${BACKUP_DIR}/mysql/backup_${DATE}.sql.gz
# Redis 备份
@@ -134,10 +134,10 @@ crontab -e
```bash
# 从 SQL 文件恢复
mysql -h 127.0.0.1 -u root -p djangoadmin.django.elevue < backup_20260905.sql
mysql -h 127.0.0.1 -u root -p djangoadmin.django.antdvue < backup_20260905.sql
# 从压缩文件恢复
gunzip < backup_20260905.sql.gz | mysql -h 127.0.0.1 -u root -p djangoadmin.django.elevue
gunzip < backup_20260905.sql.gz | mysql -h 127.0.0.1 -u root -p djangoadmin.django.antdvue
```
### Redis 恢复
DjangoAdmin_Django_AntdVue/zh/volume6/db-migrate.md
+1 -1
View File
@@ -23,7 +23,7 @@ python manage.py migrate
```
:::tip 初始化流程
1. 确保数据库已创建：`CREATE DATABASE djangoadmin.django.elevue DEFAULT CHARACTER SET utf8mb4;`
1. 确保数据库已创建：`CREATE DATABASE djangoadmin.django.antdvue DEFAULT CHARACTER SET utf8mb4;`
2. 确保 `.env` 中的数据库配置正确
3. 执行 `python manage.py migrate` 自动创建所有表
:::
DjangoAdmin_Django_AntdVue/zh/volume6/deploy-checklist.md
+3 -3
View File
@@ -29,7 +29,7 @@
**数据库**：
- [ ] 安装 MySQL 8.0+
- [ ] 创建数据库：`CREATE DATABASE djangoadmin.django.elevue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
- [ ] 创建数据库：`CREATE DATABASE djangoadmin.django.antdvue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
- [ ] 创建数据库用户并授权
- [ ] 修改 `.env` 中的数据库配置（DATABASE_ENGINE、DATABASE_NAME、DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD）
- [ ] 初始化数据库：`python manage.py migrate`
@@ -144,7 +144,7 @@ server {
### 数据库迁移
- [ ] 备份数据库：`mysqldump -uroot -p djangoadmin.django.elevue > backup.sql`
- [ ] 备份数据库：`mysqldump -uroot -p djangoadmin.django.antdvue > backup.sql`
- [ ] 执行迁移：`python manage.py makemigrations && python manage.py migrate`
- [ ] 验证迁移结果
@@ -204,7 +204,7 @@ cp -r /opt/backup/dist /opt/project/ui/dist
```bash
# 从备份恢复
mysql -uroot -p djangoadmin.django.elevue < backup.sql
mysql -uroot -p djangoadmin.django.antdvue < backup.sql
```
## 总结
DjangoAdmin_Django_AntdVue/zh/volume6/docker.md
+1 -1
View File
@@ -151,7 +151,7 @@ services:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: djangoadmin.django.elevue
MYSQL_DATABASE: djangoadmin.django.antdvue
volumes:
- mysql_data:/var/lib/mysql
ports:
DjangoAdmin_Django_AntdVue/zh/volume6/env-plan.md
+5 -5
View File
@@ -49,7 +49,7 @@ REDIS_PASSWORD=123456
REDIS_DB=0
# 文件配置
DJANGO_FILE_URL=http://file.django.elevue
DJANGO_FILE_URL=http://file.django.antdvue
```
### Prod 环境
@@ -91,7 +91,7 @@ DJANGO_FILE_URL=https://files.example.com
```python
# config/env.py 中的配置读取方式
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.antdvue')
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
```
@@ -105,12 +105,12 @@ Docker 部署时，`docker-compose.yml` 通过 `env_file: .env` 注入环境变
| 变量名 | 说明 | 默认值 |
|:----|:----|:----|
| `DJANGO_NAME` | 应用名称（显示在浏览器标题） | Django+EleVue旗舰版 |
| `DJANGO_NAME` | 应用名称（显示在浏览器标题） | Django+AntDesign旗舰版 |
| `DJANGO_VERSION` | 应用版本号 | v3.0.0 |
| `DJANGO_DEBUG` | 调试模式开关 | True |
| `DJANGO_DEMO` | 演示模式（限制写操作） | True |
| `DATABASE_ENGINE` | 数据库引擎 | django.db.backends.mysql |
| `DATABASE_NAME` | 数据库名称 | djangoadmin.django.elevue |
| `DATABASE_NAME` | 数据库名称 | djangoadmin.django.antdvue |
| `DATABASE_HOST` | 数据库主机 | 127.0.0.1 |
| `DATABASE_PORT` | 数据库端口 | 3306 |
| `DATABASE_USER` | 数据库用户名 | root |
@@ -120,7 +120,7 @@ Docker 部署时，`docker-compose.yml` 通过 `env_file: .env` 注入环境变
| `REDIS_PORT` | Redis 端口 | 6379 |
| `REDIS_PASSWORD` | Redis 密码 | 123456 |
| `REDIS_DB` | Redis 数据库索引 | 0 |
| `DJANGO_FILE_URL` | 文件访问域名 | http://file.django.elevue |
| `DJANGO_FILE_URL` | 文件访问域名 | http://file.django.antdvue |
| `DJANGO_UPLOAD_DIR` | 文件上传目录 | /public/uploads |
| `IP_LOCATION_SOURCE` | IP 地理位置来源 | api |
| `SITE_DOMAIN` | 站点域名 | http://127.0.0.1:8000 |
DjangoAdmin_Django_AntdVue/zh/volume6/upgrade.md
+2 -2
View File
@@ -18,7 +18,7 @@
```bash
# 1. 数据库全量备份
mysqldump -h 127.0.0.1 -u root -p --single-transaction \
djangoadmin.django.elevue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
djangoadmin.django.antdvue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
# 2. 上传文件备份
tar -czf uploads_$(date +%Y%m%d).tar.gz /data/apps/DjangoAdmin_Django_AntdVue/public/uploads/
@@ -174,7 +174,7 @@ cd /data/apps/
tar -xzf app_20260905.tar.gz
# 3. 恢复数据库
gunzip < backup_20260905.sql.gz | mysql -u root -p djangoadmin.django.elevue
gunzip < backup_20260905.sql.gz | mysql -u root -p djangoadmin.django.antdvue
# 4. 恢复上传文件
tar -xzf uploads_20260905.tar.gz -C /
DjangoAdmin_Django_EleVue/zh/volume7/fe-component.md
+1 -1
View File
@@ -6,7 +6,7 @@
:::tip 技术栈
- Vue3（Composition API + `<script setup>`）
- ElementPlus 2.x
- ElementPlus
- 自定义组件（BasicTable / BasicForm / TableAction / PageWrapper）
- Pinia 状态管理
- Vue Router 路由管理
DjangoAdmin_Django_NaiveVue/.vitepress/config/zh.ts
+8 -8
View File
@@ -3,7 +3,7 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress";
export const META_URL = "https://www.djangoadmin.cn";
export const META_TITLE = "DjangoAdmin 企业级中台解决方案";
export const META_DESCRIPTION =
"DjangoAdmin 企业级中台解决方案 - Django + ElementPlus 前后端分离版本";
"DjangoAdmin 企业级中台解决方案 - Django + NaiveUI 前后端分离版本";
export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
description: META_DESCRIPTION,
@@ -30,7 +30,7 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
themeConfig: {
editLink: {
pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue",
pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveVue",
text: "对本页提出修改建议",
},
@@ -197,7 +197,7 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
},
{
text: "Gitee 仓库",
link: "https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue",
link: "https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveVue",
},
{
text: "Django 文档",
@@ -208,8 +208,8 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
link: "https://cn.vuejs.org/",
},
{
text: "ElementPlus",
link: "https://element-plus.org/zh-CN/",
text: "NaiveUI",
link: "https://www.naiveui.com/zh-CN",
},
],
},
@@ -779,10 +779,10 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
},
// ================================================================
// 第 9 章：其他
// 第 9 章：附录
// ================================================================
{
text: "📄 9. 其他",
text: "📄 附录",
collapsed: false,
items: [
{ text: "9.1 常见问题汇总", link: "/zh/faq.html" },
@@ -790,7 +790,7 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
{ text: "9.3 免责声明", link: "/zh/other/declare.html" },
{
text: "9.4 开源协议",
link: "https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue/blob/master/LICENSE",
link: "https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveVue/blob/master/LICENSE",
},
{ text: "9.5 广告赞助", link: "/zh/other/sponsor.html" },
],
DjangoAdmin_Django_NaiveVue/index.md
+3 -3
View File
@@ -2,11 +2,11 @@
layout: home
title: DjangoAdmin文档
titleTemplate: 前后端分离Django+ElementPlus版
titleTemplate: 前后端分离Django+NaiveUI版
hero:
name: DjangoAdmin
text: "企业级中台解决方案Django+ElementPlus版"
text: "企业级中台解决方案Django+NaiveUI版"
tagline: "赋能开发者，助力企业发展。\n企业级数据平台底座 · 让数字化触手可及。"
image:
src: /logo.svg
@@ -17,7 +17,7 @@ hero:
link: /zh/introduction
- theme: alt
text: 在线演示
link: http://manage.django.elevue.djangoadmin.cn
link: http://manage.django.naiveue.djangoadmin.cn
- theme: alt
text: 官方授权
link: https://www.djangoadmin.cn/goods/detail/2
DjangoAdmin_Django_NaiveVue/zh/changelog.md
+5 -5
View File
@@ -12,15 +12,15 @@
| 2.1.0 | 2024-06-23 | RBAC 权限体系 + JWT 认证 + 验证码 |
| 2.2.0 | 2024-09-06 | 字典管理 + 系统配置 + 参数管理 |
| 2.3.0 | 2024-12-19 | 文章管理 + 分类管理 + 文件上传 + XSS 防护 |
| 2.4.0 | 2025-03-11 | Vue3 + ElementPlus + TypeScript + Vite |
| 2.4.0 | 2025-03-11 | Vue3 + NaiveUI + TypeScript + Vite |
| 2.5.0 | 2025-06-25 | 代码生成器 CLI + Web UI + Excel 导入导出 |
| 2.6.0 | 2025-09-17 | 定时任务 + 操作日志 + 登录日志 |
| 2.7.0 | 2025-12-08 | 接口限流 + IP 地理位置 + 安全防护 |
| 2.8.0 | 2026-03-22 | Docker 容器化 + Nginx + Supervisor |
| 2.9.0 | 2026-06-15 | 文档体系 + 缓存优化 + 性能提升 |
| **3.0.0** | **2026-09-01** | **Django 6.0 + Python 3.12 + 架构优化** |
| **3.0.0** | **2026-09-10** | **Django 6.0 + Python 3.12 + 架构优化** |
## [3.0.0] - 2026-09-01
## [3.0.0] - 2026-09-10
**Django 6.0 升级，技术栈全面焕新。**
@@ -172,7 +172,7 @@
### 新增
- **Vue3 升级**：前端框架从 Vue 2 升级至 Vue3.4+，全面拥抱 Composition API
- **ElementPlus**：采用 ElementPlus 组件库，适配 Vue3 生态
- **NaiveUI**：采用 NaiveUI 组件库，适配 Vue3 生态
- **Pinia 状态管理**：替代 Vuex，更轻量、更灵活、TypeScript 支持更完善
- **TypeScript 类型安全**：全量类型定义，IDE 智能提示与编译时类型检查
- **Vite 构建工具**：替代 Webpack，开发服务器毫秒级启动，HMR 即时生效
@@ -274,7 +274,7 @@
- **Django Web 框架**：基于 Django 5.x，成熟的 MTV 架构，丰富的生态系统
- **Django ORM**：声明式模型定义，自动迁移，多数据库方言支持
- **Django ModelForm**：声明式表单验证，自动错误信息生成
- **Vue3 前端**：基于 Vue3 + ElementPlus，前后端分离架构
- **Vue3 前端**：基于 Vue3 + NaiveUI，前后端分离架构
- **用户管理**：用户账号管理、密码重置、启用/停用状态控制
- **角色管理**：角色 CRUD、权限节点配置
- **菜单管理**：菜单 CRUD、图标设置、动态路由生成
DjangoAdmin_Django_NaiveVue/zh/course.md
+5 -5
View File
@@ -45,7 +45,7 @@
```bash
# 进入项目目录（以实际解压路径为准）
cd DjangoAdmin_Django_EleVue
cd DjangoAdmin_Django_NaiveVue
```
:::tip 温馨提示
@@ -95,7 +95,7 @@ DJANGO_DEMO=False
# ==================== 数据库配置 ====================
DATABASE_ENGINE=django.db.backends.mysql
DATABASE_NAME=djangoadmin.django.elevue
DATABASE_NAME=djangoadmin.django.naivevue
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
@@ -109,13 +109,13 @@ REDIS_PASSWORD=your_redis_password
REDIS_DB=0
# ==================== 文件配置 ====================
DJANGO_FILE_URL=http://file.django.elevue
DJANGO_FILE_URL=http://file.django.naivevue
```
:::danger
:::danger 重要提示
`DATABASE_NAME` 需要提前在 MySQL 中创建对应的数据库：
```sql
CREATE DATABASE `djangoadmin.django.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE DATABASE `djangoadmin.django.naivevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```
:::
DjangoAdmin_Django_NaiveVue/zh/introduction.md
+84 -78
View File
@@ -8,9 +8,9 @@
## 软件说明
基于 Django、Django ORM、Vue3、TypeScript、Vite、ElementPlus、MySQL 等技术栈构建的企业级前后端分离后台管理系统。
基于 Django、Django ORM、Vue3、TypeScript、Vite、NaiveUI 等技术栈构建的企业级前后端分离后台管理系统，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库。
后端采用 Python 语言，基于 Django Web 框架、Django ORM 数据库操作、Django Form 数据校验等主流技术栈；前端基于 Vue3、TypeScript、Vite 构建，采用 ElementPlus 框架，遵循 Vue 前后端分离主流设计思想。
后端采用 Python 语言，基于 Django Web 框架、Django ORM 数据库操作、Django Form 数据校验等主流技术栈；前端基于 Vue3、TypeScript、Vite 构建，采用 NaiveUI 框架，遵循 Vue 前后端分离主流设计思想。
系统采用完全前后端分离架构，前端通过 API 调用后端服务实现数据交互。内置完善的 RBAC 权限体系，权限颗粒度精细至按钮级别；支持多主题切换，兼容桌面端和平板端。系统预置了用户、角色、菜单、部门、岗位、职级、日志、字典、配置、参数、定时任务、代码生成器等基础功能模块，开箱即用。
@@ -21,7 +21,7 @@
+ **分层架构**：Model（数据）→ Form（验证）→ Service（业务）→ View（视图）→ URL（路由），职责清晰
+ **基类复用**：BaseModel 提供 6 个公共字段（id、创建人、时间、软删除），子类只需声明业务字段
+ **模块可插拔**：业务模块位于 `application/`，按 Django App 机制注册，增删不影响核心框架
+ **多数据库支持**：通过 `DATABASE_ENGINE` 环境变量一键切换 MySQL / PostgreSQL / SQLite / Oracle
+ **多数据库支持**：通过 `DATABASE_ENGINE` 环境变量一键切换 MySQL / PostgreSQL / SQLite / Oracle / SQL Server 等数据库
+ **中间件可扩展**：CORS、认证、权限、日志通过 Django 中间件链式处理，按需注册
+ **RBAC 权限**：后端 PermissionRequired + 前端 v-perm 指令双重校验，精确到按钮级
+ **代码生成器**：根据数据库表结构一键生成前后端 CRUD 代码，含列表、表单、API 全套
@@ -42,99 +42,105 @@
+ **通知公告**：主要对通知、公告等站内数据进行管理
+ **行政区划**：针对全国行政区划分数据进行管理和维护
+ **文件模板**：主要对系统中使用的文件模板进行上传和管理
+ **文件上传**：提供统一的文件上传服务，支持图片、文档等多类型文件管理，自动重命名、按日期分目录存储
+ **友情链接**：用于管理外部链接和合作伙伴链接数据，支持分类管理和排序
+ **文章管理**：用于发布和管理文章内容，支持富文本编辑、分类管理和状态管理
+ **任务调度**：主要用于对定时任务进行定义和统一调度管理
+ **代码生成**：根据数据库表结构一键生成前后端 CRUD 代码，含列表、表单、API 全套
+ **分类管理**：用于文章分类、商品分类等树形分类数据的管理
+ **示例模块**：提供代码生成器的示例参考，展示标准 CRUD 模块的实现方式
## 软件出处
+ 软件名称：小蚂蚁云前后端分离Django+ElementPlus版本
+ 软件名称：小蚂蚁云前后端分离Django+NaiveUI版本
+ 软件作者：@小蚂蚁云团队
+ 软件协议：Apache-2.0
+ 官网网址：[https://www.djangoadmin.cn](https://www.djangoadmin.cn)
+ 文档网址：[http://docs.django.elevue.djangoadmin.cn](http://docs.django.elevue.djangoadmin.cn)
+ 演示地址：[http://manage.django.elevue.djangoadmin.cn](http://manage.django.elevue.djangoadmin.cn)
+ 文档网址：[http://docs.django.naiveue.djangoadmin.cn](http://docs.django.naiveue.djangoadmin.cn)
+ 演示地址：[http://manage.django.naiveue.djangoadmin.cn](http://manage.django.naiveue.djangoadmin.cn)
## 软件版本
| 版本名称 | 说明 | 地址 |
|:---------|:-----|:-----|
| Django+Layui混编版 | 基于 Django、Jinja2、Layui、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_Layui) |
| Django+EleVue前后端分离版 | 基于 Django、Django ORM、Vue3、ElementPlus、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue) |
| Django+AntdVue前后端分离版 | 基于 Django、Django ORM、Vue3、AntDesign、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_AntdVue) |
| Django+NaiveVue前后端分离版 | 基于 Django、Django ORM、Vue3、NaiveUI、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveVue) |
| Flask+Layui混编版 | 基于 Flask、Jinja2、Layui、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_Layui) |
| Flask+EleVue前后端分离版 | 基于 Flask、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue) |
| Flask+AntdVue前后端分离版 | 基于 Flask、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue) |
| Flask+NaiveVue前后端分离版 | 基于 Flask、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveVue) |
| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_Layui) |
| FastAPI+EleVue前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue) |
| FastAPI+AntdVue前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_AntdVue) |
| FastAPI+NaiveVue前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_NaiveVue) |
| Tornado+Layui混编版 | 基于 Tornado、Jinja2、Layui、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_Layui) |
| Tornado+EleVue前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_EleVue) |
| Tornado+AntdVue前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_AntdVue) |
| Tornado+NaiveVue前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite、MySQL 等技术栈 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_NaiveVue) |
| Django+Layui混编版 | 基于 Django、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_Layui) |
| Django+ElementPlus前后端分离版 | 基于 Django、Django ORM、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue) |
| Django+AntDesign前后端分离版 | 基于 Django、Django ORM、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_AntdVue) |
| Django+NaiveUI前后端分离版 | 基于 Django、Django ORM、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveVue) |
| Flask+Layui混编版 | 基于 Flask、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_Layui) |
| Flask+ElementPlus前后端分离版 | 基于 Flask、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue) |
| Flask+AntDesign前后端分离版 | 基于 Flask、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue) |
| Flask+NaiveUI前后端分离版 | 基于 Flask、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveVue) |
| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_Layui) |
| FastAPI+ElementPlus前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue) |
| FastAPI+AntDesign前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_AntdVue) |
| FastAPI+NaiveUI前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_NaiveVue) |
| Tornado+Layui混编版 | 基于 Tornado、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_Layui) |
| Tornado+ElementPlus前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_EleVue) |
| Tornado+AntDesign前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_AntdVue) |
| Tornado+NaiveUI前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_NaiveVue) |
## 模块展示
<table>
<tr>
<td><img src="/demo/1.png"/></td>
<td><img src="/demo/2.png"/></td>
</tr>
<tr>
<td><img src="/demo/3.png"/></td>
<td><img src="/demo/4.png"/></td>
</tr>
<tr>
<td><img src="/demo/5.png"/></td>
<td><img src="/demo/6.png"/></td>
</tr>
<tr>
<td><img src="/demo/7.png"/></td>
<td><img src="/demo/8.png"/></td>
</tr>
<tr>
<td><img src="/demo/9.png"/></td>
<td><img src="/demo/10.png"/></td>
</tr>
<tr>
<td><img src="/demo/11.png"/></td>
<td><img src="/demo/12.png"/></td>
</tr>
<tr>
<td><img src="/demo/13.png"/></td>
<td><img src="/demo/14.png"/></td>
</tr>
<tr>
<td><img src="/demo/15.png"/></td>
<td><img src="/demo/16.png"/></td>
</tr>
<tr>
<td><img src="/demo/17.png"/></td>
<td><img src="/demo/18.png"/></td>
</tr>
<tr>
<td><img src="/demo/19.png"/></td>
<td><img src="/demo/20.png"/></td>
</tr>
<tr>
<td><img src="/demo/21.png"/></td>
<td><img src="/demo/22.png"/></td>
</tr>
<tr>
<td><img src="/demo/23.png"/></td>
<td><img src="/demo/24.png"/></td>
</tr>
<tr>
<td><img src="/demo/25.png"/></td>
<td><img src="/demo/26.png"/></td>
</tr>
<tr>
<td><img src="/demo/27.png"/></td>
<td><img src="/demo/28.png"/></td>
</tr>
<tbody>
<tr>
<td><img src="/demo/1.png"/></td>
<td><img src="/demo/2.png"/></td>
</tr>
<tr>
<td><img src="/demo/3.png"/></td>
<td><img src="/demo/4.png"/></td>
</tr>
<tr>
<td><img src="/demo/5.png"/></td>
<td><img src="/demo/6.png"/></td>
</tr>
<tr>
<td><img src="/demo/7.png"/></td>
<td><img src="/demo/8.png"/></td>
</tr>
<tr>
<td><img src="/demo/9.png"/></td>
<td><img src="/demo/10.png"/></td>
</tr>
<tr>
<td><img src="/demo/11.png"/></td>
<td><img src="/demo/12.png"/></td>
</tr>
<tr>
<td><img src="/demo/13.png"/></td>
<td><img src="/demo/14.png"/></td>
</tr>
<tr>
<td><img src="/demo/15.png"/></td>
<td><img src="/demo/16.png"/></td>
</tr>
<tr>
<td><img src="/demo/17.png"/></td>
<td><img src="/demo/18.png"/></td>
</tr>
<tr>
<td><img src="/demo/19.png"/></td>
<td><img src="/demo/20.png"/></td>
</tr>
<tr>
<td><img src="/demo/21.png"/></td>
<td><img src="/demo/22.png"/></td>
</tr>
<tr>
<td><img src="/demo/23.png"/></td>
<td><img src="/demo/24.png"/></td>
</tr>
<tr>
<td><img src="/demo/25.png"/></td>
<td><img src="/demo/26.png"/></td>
</tr>
<tr>
<td><img src="/demo/27.png"/></td>
<td><img src="/demo/28.png"/></td>
</tr>
</tbody>
</table>
## 开源协议
DjangoAdmin_Django_NaiveVue/zh/other/contributing.md
+1 -1
View File
@@ -7,7 +7,7 @@
## 开发环境搭建
1. Fork 项目到自己的 Gitee/GitHub 账号
2. 克隆到本地：`git clone https://gitee.com/yourname/DjangoAdmin_Django_EleVue.git`
2. 克隆到本地：`git clone https://gitee.com/yourname/DjangoAdmin_Django_NaiveVue.git`
3. 参考 [开发环境准备](/zh/volume1/environment.html) 安装依赖
4. 创建开发分支：`git checkout -b feature/your-feature`
DjangoAdmin_Django_NaiveVue/zh/struct.md
-1
View File
@@ -3,7 +3,6 @@
## 整体结构
```
DjangoAdmin_Django_EleVue/
├── application/ # Django 应用目录（所有业务模块）
│ ├── example/ # 示例模块（标准 CRUD 模板，可作为开发参考）
│ │ ├── models.py # 数据模型
DjangoAdmin_Django_NaiveVue/zh/volume1/backend.md
+7 -14
View File
@@ -19,7 +19,7 @@
```bash
# 进入项目根目录（以实际解压路径为准
cd DjangoAdmin_Django_EleVue
cd DjangoAdmin_Django_NaiveVue
```
:::tip 温馨提示
@@ -142,7 +142,7 @@ vim .env
# ============================================================
# 基础配置
# ============================================================
DJANGO_NAME=Django+EleVue旗舰版
DJANGO_NAME=Django+NaiveUI旗舰版
DJANGO_VERSION=v3.0.0
DJANGO_DEBUG=True
DJANGO_DEMO=False # 默认值为True（演示模式），开发时请设为False
@@ -151,7 +151,7 @@ DJANGO_DEMO=False # 默认值为True（演示模式），开
# 数据库配置（根据实际情况修改）
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.elevue'
DATABASE_NAME='djangoadmin.django.naivevue'
DATABASE_HOST="127.0.0.1"
DATABASE_PORT=3306
DATABASE_USER="root"
@@ -185,7 +185,7 @@ REDIS_DB=0
```sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.django.elevue`
CREATE DATABASE `djangoadmin.django.naivevue`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;
```
@@ -204,20 +204,13 @@ python manage.py migrate
`makemigrations` 会根据 `models.py` 中的模型定义自动生成迁移文件，`migrate` 会执行迁移文件创建或修改数据表结构。更多数据库相关内容请参见 [数据库初始化](/zh/volume1/database) 章节。
:::
### 第三步：回填数据库字段注释（可选）
```bash
# 为数据库表和字段添加中文注释
python manage.py add_full_comments
```
### 第四步：导入初始数据
### 第三步：导入初始数据
数据库初始数据（管理员账号、默认角色、菜单权限等）通过 SQL 脚本导入。脚本位于项目对应目录中：
```bash
# 使用 mysql 命令行导入
mysql -uroot -p djangoadmin.django.elevue < document/mysql/djangoadmin.django.elevue.sql
mysql -uroot -p djangoadmin.django.naivevue < document/mysql/djangoadmin.django.naivevue.sql
```
:::tip 种子数据说明
@@ -328,7 +321,7 @@ lsof -i :8000
```
1. MySQL 服务是否已启动
2. .env 中的 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD 是否正确
3. 数据库 djangoadmin.django.elevue 是否已创建
3. 数据库 djangoadmin.django.naivevue 是否已创建
4. 防火墙是否放行了数据库端口
```
DjangoAdmin_Django_NaiveVue/zh/volume1/database.md
+12 -26
View File
@@ -17,7 +17,7 @@
```sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.django.elevue`
CREATE DATABASE `djangoadmin.django.naivevue`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;
@@ -26,7 +26,7 @@ SHOW DATABASES;
```
:::tip 温馨提示
数据库名称需要与 `.env` 文件中的 `DATABASE_NAME` 配置一致，默认为 `djangoadmin.django.elevue`。
数据库名称需要与 `.env` 文件中的 `DATABASE_NAME` 配置一致，默认为 `djangoadmin.django.naivevue`。
:::
## 第二步：配置数据库连接
@@ -38,7 +38,7 @@ SHOW DATABASES;
# 数据库配置
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql" # 数据库引擎
DATABASE_NAME='djangoadmin.django.elevue' # 数据库名称
DATABASE_NAME='djangoadmin.django.naivevue' # 数据库名称
DATABASE_HOST="127.0.0.1" # 数据库地址
DATABASE_PORT=3306 # 数据库端口
DATABASE_USER="root" # 数据库用户名
@@ -54,7 +54,7 @@ DATABASE_PREFIX="django_" # 数据表前缀
| MySQL | `django.db.backends.mysql` | 3306 | mysqlclient |
| PostgreSQL | `django.db.backends.postgresql` | 5432 | psycopg2-binary |
| SQLite | `django.db.backends.sqlite3` | - | 内置 |
| Oracle | `django.db.backends.oracle` | 1521 | cx-Oracle |
| Oracle | `django.db.backends.oracle` | 1521 | oracledb |
| SQL Server | `mssql` | 1433 | mssql-django |
切换数据库引擎后，需安装对应的 Python 驱动包。例如切换到 PostgreSQL：
@@ -105,7 +105,7 @@ python manage.py migrate application.user 0001
```bash
# 使用 mysql 命令行导入
mysql -uroot -p djangoadmin.django.elevue < document/mysql/djangoadmin.django.elevue.sql
mysql -uroot -p djangoadmin.django.naivevue < document/mysql/djangoadmin.django.naivevue.sql
# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件
```
@@ -122,20 +122,7 @@ mysql -uroot -p djangoadmin.django.elevue < document/mysql/djangoadmin.django.el
| 系统配置 | 系统默认配置项 |
:::
## 第五步：回填数据库字段注释（可选）
项目提供了自定义管理命令，用于为数据库表和字段添加中文注释：
```bash
# 为所有数据表添加字段注释
python manage.py add_full_comments
```
:::tip 温馨提示
此命令会读取 Django 模型中的 `verbose_name` 和 `help_text` 属性，将其写入数据库的字段注释中，便于使用 Navicat 等工具查看表结构时理解每个字段的含义。
:::
## 第六步：验证
## 第五步：验证
启动后端服务，验证数据库连接是否正常：
@@ -236,20 +223,20 @@ python generator.py --config config.json
```bash
# 备份数据库
mysqldump -uroot -p djangoadmin.django.elevue > backup.sql
mysqldump -uroot -p djangoadmin.django.naivevue > backup.sql
# 恢复数据库
mysql -uroot -p djangoadmin.django.elevue < backup.sql
mysql -uroot -p djangoadmin.django.naivevue < backup.sql
```
+ PostgreSQL 备份
```bash
# 备份数据库
pg_dump -U postgres djangoadmin.django.elevue > backup.sql
pg_dump -U postgres djangoadmin.django.naivevue > backup.sql
# 恢复数据库
psql -U postgres djangoadmin.django.elevue < backup.sql
psql -U postgres djangoadmin.django.naivevue < backup.sql
```
+ SQLite 备份
@@ -267,11 +254,10 @@ cp db_backup.sqlite3 db.sqlite3
数据库初始化的核心步骤：
```
1. 创建数据库：CREATE DATABASE `djangoadmin.django.elevue`
1. 创建数据库：CREATE DATABASE `djangoadmin.django.naivevue`
2. 配置 .env：设置 DATABASE_ENGINE、DATABASE_NAME 等连接信息
3. 执行迁移：python manage.py makemigrations && python manage.py migrate
4. 导入初始数据：mysql ... < document/mysql/djangoadmin.django.elevue.sql
5. 回填注释（可选）：python manage.py add_full_comments
4. 导入初始数据：mysql ... < document/mysql/djangoadmin.django.naivevue.sql
```
后续的模型变更通过 Django 迁移系统管理（`makemigrations` + `migrate`），确保数据库结构与代码保持同步。如需使用代码生成器创建新模块，生成器会自动处理数据库迁移。
DjangoAdmin_Django_NaiveVue/zh/volume1/docker.md
+12 -12
View File
@@ -56,7 +56,7 @@ cp .env.example .env
# 说明：连接 Docker 容器中运行的 MySQL 数据库
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.elevue'
DATABASE_NAME='djangoadmin.django.naivevue'
DATABASE_HOST=127.0.0.1 # 数据库主机地址（本地容器）
DATABASE_PORT=3306 # 数据库端口（MySQL 默认 3306）
DATABASE_USER=root # 数据库用户名
@@ -80,7 +80,7 @@ REDIS_DB=0 # Redis 数据库索引
```yaml
# +======================================================================
# | 模块: Docker Compose 配置
# | 说明: Django+EleVue 应用服务容器编排
# | 说明: Django+NaiveUI 应用服务容器编排
# +======================================================================
version: '3.7'
# ============================================================
@@ -90,11 +90,11 @@ services:
# ------------------------------------------------------------
# 后端服务
# ------------------------------------------------------------
django_elevue:
django_naivevue:
# 构建镜像名称
image: django_elevue
image: django_naivevue
# 容器运行时名称
container_name: django_elevue
container_name: django_naivevue
# 镜像构建配置
build:
context: ./ # 构建上下文路径（项目根目录）
@@ -168,7 +168,7 @@ docker compose up -d
[+] Building 45.2s (12/12) FINISHED
[+] Running 2/2
✔ Network djangoadmin_default Created
✔ Container django_elevue Started
✔ Container django_naivevue Started
```
:::tip 访问服务
@@ -202,7 +202,7 @@ docker compose logs -f
docker compose logs --tail 100
# 查看指定服务日志
docker compose logs -f django_elevue
docker compose logs -f django_naivevue
```
+ 停止与重启
@@ -232,10 +232,10 @@ docker compose up --build
```bash
# 进入运行中的容器终端
docker compose exec django_elevue bash
docker compose exec django_naivevue bash
# 在容器内执行 Django 命令
docker compose exec django_elevue python manage.py shell
docker compose exec django_naivevue python manage.py shell
```
## 环境变量注入
@@ -244,10 +244,10 @@ Docker 模式下，环境变量通过 `env_file` 从 `.env` 文件注入到容
```bash
# 使用 --env-file 指定环境变量文件
docker run --env-file .env django_elevue
docker run --env-file .env django_naivevue
# 通过 -e 参数覆盖单个变量
docker run -e DJANGO_DEBUG=False django_elevue
docker run -e DJANGO_DEBUG=False django_naivevue
```
:::tip 温馨提示
@@ -302,7 +302,7 @@ ports:
```bash
# 查看容器日志排查原因
docker compose logs django_elevue
docker compose logs django_naivevue
```
常见原因：数据库连接失败、Redis 连接失败、数据库未创建。
DjangoAdmin_Django_NaiveVue/zh/volume1/env-vars.md
+8 -8
View File
@@ -12,12 +12,12 @@
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| `DJANGO_NAME` | `Django+EleVue旗舰版` | 应用名称，用于界面显示和系统标识 |
| `DJANGO_NAME` | `Django+NaiveUI旗舰版` | 应用名称，用于界面显示和系统标识 |
| `DJANGO_VERSION` | `v3.0.0` | 应用版本号 |
| `DJANGO_DEBUG` | `True` | 是否开启调试模式。`True` 时输出详细错误堆栈，生产环境务必设为 `False` |
| `DJANGO_DEMO` | `True` | 是否开启演示模式。`True` 时所有写操作（add/update/delete/status）返回"演示环境，暂无操作权限"。**开发调试时请设为 `False`** |
| `DJANGO_UPLOAD_DIR` | `项目根目录/public/uploads` | 文件上传存储路径 |
| `DJANGO_FILE_URL` | `http://file.django.elevue` | 文件访问域名，用于拼接上传文件的访问 URL |
| `DJANGO_FILE_URL` | `http://file.django.naivevue` | 文件访问域名，用于拼接上传文件的访问 URL |
:::tip 安全提示
1. 生产环境务必设置 `DJANGO_DEBUG=False`，调试模式会输出详细的错误堆栈信息，可能泄漏内部实现细节。
@@ -29,7 +29,7 @@
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| `DATABASE_ENGINE` | `django.db.backends.mysql` | 数据库引擎。支持：`mysql`、`postgresql`、`sqlite3`、`oracle`、`mssql` |
| `DATABASE_NAME` | `djangoadmin.django.elevue` | 数据库名称。SQLite 时作为数据库文件路径 |
| `DATABASE_NAME` | `djangoadmin.django.naivevue` | 数据库名称。SQLite 时作为数据库文件路径 |
| `DATABASE_HOST` | `127.0.0.1` | 数据库地址 |
| `DATABASE_PORT` | `3306` | 数据库端口 |
| `DATABASE_USER` | `root` | 数据库账号 |
@@ -142,18 +142,18 @@ Redis 用于存储验证码、JWT 令牌黑名单等功能，是项目正常运
# ============================================================
# 应用配置
# ============================================================
DJANGO_NAME=Django+EleVue旗舰版
DJANGO_NAME=Django+NaiveUI旗舰版
DJANGO_VERSION=v3.0.0
DJANGO_DEBUG=True
DJANGO_DEMO=False # 代码默认True（演示模式），开发环境设为False以启用写操作
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_V3\DjangoAdmin_Django_EleVue\public\uploads"
DJANGO_FILE_URL='http://file.django.elevue'
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_Django_NaiveVue\public\uploads"
DJANGO_FILE_URL='http://file.django.naivevue'
# ============================================================
# 数据库配置
# ============================================================
DATABASE_ENGINE="django.db.backends.mysql"
DATABASE_NAME='djangoadmin.django.elevue'
DATABASE_NAME='djangoadmin.django.naivevue'
DATABASE_HOST="127.0.0.1"
DATABASE_PORT=3306
DATABASE_USER="root"
@@ -200,7 +200,7 @@ extends/extends_dotenv.py
│ 3. 调用 load_dotenv(env_path) 注入环境变量
▼
config/env.py
│ os.getenv('DJANGO_NAME', 'Django+EleVue旗舰版')
│ os.getenv('DJANGO_NAME', 'Django+NaiveUI旗舰版')
│ os.getenv('DATABASE_HOST', '127.0.0.1')
│ ...（所有配置项）
▼
DjangoAdmin_Django_NaiveVue/zh/volume1/environment.md
+4 -4
View File
@@ -1,8 +1,8 @@
# 环境准备
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `Django` 后端、`Vue3` + `ElementPlus` 前端的分离架构，本地开发需准备以下软件。
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `Django` 后端、`Vue3` + `NaiveUI` 前端的分离架构，本地开发需准备以下软件。
安装软件：`Python(3.12+)`、`MySQL(8.0+)`、`Redis(6.0+)`、`Node.js(18+)`、`pnpm` 等。
安装软件：`Python(3.12+)`、`MySQL(8.0+)`（或其他支持的数据库）、`Redis(6.0+)`、`Node.js(18+)`、`pnpm` 等。
:::tip 温馨提示
1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。
@@ -127,7 +127,7 @@ mysql>
```sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.django.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE DATABASE `djangoadmin.django.naivevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
-- 查看数据库
SHOW DATABASES;
@@ -192,7 +192,7 @@ OK
## 安装 Node.js
`Node.js` 是前端项目的运行环境，要求 `18` 或更高版本。前端基于 `Vue3` + `ElementPlus` 构建。
`Node.js` 是前端项目的运行环境，要求 `18` 或更高版本。前端基于 `Vue3` + `NaiveUI` 构建。
+ 下载 Node.js
DjangoAdmin_Django_NaiveVue/zh/volume1/faq.md
+3 -3
View File
@@ -83,7 +83,7 @@ mysql -h127.0.0.1 -P3306 -uroot -p
# 如果是权限问题，授权用户
mysql -uroot -p
GRANT ALL PRIVILEGES ON `djangoadmin.django.elevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON `djangoadmin.django.naivevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;
```
@@ -378,8 +378,8 @@ python manage.py shell
```bash
# .env 中的上传配置
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_V3\DjangoAdmin_Django_EleVue\public\uploads"
DJANGO_FILE_URL='http://file.django.elevue'
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_Django_NaiveVue\public\uploads"
DJANGO_FILE_URL='http://file.django.naivevue'
```
:::tip 温馨提示
DjangoAdmin_Django_NaiveVue/zh/volume1/frontend.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 前端启动
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `ElementPlus` + `TypeScript` + `Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `NaiveUI` + `TypeScript` + `Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
:::tip 温馨提示
启动前端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的 `Node.js` 和 `pnpm` 安装，并已启动后端服务（参见 [后端启动](/zh/volume1/backend)）。
DjangoAdmin_Django_NaiveVue/zh/volume2/faq.md
+1 -1
View File
@@ -162,7 +162,7 @@ avatar = save_file(avatar_url, "example")
```vue
<!-- 权限标识必须与后端一致 -->
<el-button v-perm="['sys:example:add']">添加案例</el-button>
<n-button v-perm="['sys:example:add']">添加案例</n-button>
```
### Q13: 表格数据不刷新
DjangoAdmin_Django_NaiveVue/zh/volume2/fe-view.md
+538 -177
View File
@@ -1,6 +1,6 @@
# 前端页面视图
前端页面视图是用户直接交互的界面。项目使用 Vue3 + ElementPlus + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成：
前端页面视图是用户直接交互的界面。项目使用 Vue3 + NaiveUI + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成：
```
ui/src/views/tool/example/
@@ -19,38 +19,68 @@ ui/src/views/tool/example/
```vue
<template>
<PageWrapper>
<div>
<!-- 搜索表单卡片 -->
<el-card :bordered="false" class="pt-3 mb-3 proCard">
<n-card :bordered="false" class="pt-3 mb-3 proCard">
<BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
</el-card>
</n-card>
<!-- 数据表格卡片 -->
<el-card :bordered="false" class="proCard">
<n-card :bordered="false" class="proCard">
<BasicTable
:columns="columns"
:request="loadDataTable"
:row-key="(row) => row.id"
ref="tableRef"
ref="basicTableRef"
:actionColumn="actionColumn"
@selection-change="onSelectionChange"
@update:checked-row-keys="onCheckedRow"
:auto-scroll-x="true"
>
<template #tableTitle>
<el-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
添加案例
</el-button>
<el-button type="danger" @click="handleDelete()" :disabled="!selectionData.length">
批量删除
</el-button>
<n-space>
<n-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
<template #icon>
<n-icon>
<PlusOutlined />
</n-icon>
</template>
添加案例
</n-button>
<n-button
type="error"
@click="handleDelete()"
:disabled="!rowKeys.length"
v-perm="['sys:example:batchDelete']"
>
<template #icon>
<n-icon>
<DeleteOutlined />
</n-icon>
</template>
批量删除
</n-button>
</n-space>
</template>
</BasicTable>
</el-card>
</n-card>
<!-- 编辑对话框 -->
<editDialog v-if="editVisible" :id="currentId" v-model:visible="editVisible" @success="reloadTable('noRefresh')" />
<!-- 详情对话框 -->
<detailDialog v-if="detailVisible" :id="currentId" v-model:visible="detailVisible" @success="reloadTable('noRefresh')" />
</PageWrapper>
<!-- 编辑对话框组件 -->
<editDialog
ref="editModalRef"
v-if="editVisible"
:id="currentId"
v-model:visible="editVisible"
@success="reloadTable('noRefresh')"
/>
<!-- 查看详情对话框组件 -->
<detailDialog
ref="detailModalRef"
v-if="detailVisible"
:id="currentId"
v-model:visible="detailVisible"
@success="reloadTable('noRefresh')"
/>
</div>
</template>
```
@@ -58,40 +88,72 @@ ui/src/views/tool/example/
```vue
<script lang="ts" setup>
import { reactive, ref, h, nextTick, defineAsyncComponent } from 'vue';
import { schemas } from './querySchemas';
import { useForm } from '@/components/Form/index';
import { h, nextTick, reactive, ref } from 'vue';
import { useMessage, useDialog } from 'naive-ui';
import { PlusOutlined, DeleteOutlined, EditOutlined, EyeOutlined } from '@vicons/antd';
import { TableAction } from '@/components/Table';
import { BasicForm, useForm } from '@/components/Form/index';
import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
import { renderIcon } from '@/utils';
import { columns } from './columns';
import { schemas } from './querySchemas';
// 动态导入弹窗组件
const editDialog = defineAsyncComponent(() => import('./edit.vue'));
const detailDialog = defineAsyncComponent(() => import('./detail.vue'));
// 动态导入编辑对话框组件
import editDialog from './edit.vue';
// 动态导入详情对话框组件
import detailDialog from './detail.vue';
// 响应式状态
const currentId = ref(0);
const editVisible = ref(false);
const detailVisible = ref(false);
const selectionData = ref([]);
const tableRef = ref();
// 消息提示和对话框
const message = useMessage();
const dialog = useDialog();
// 表格引用
const basicTableRef = ref();
const editModalRef = ref();
const detailModalRef = ref();
// 响应式状态定义
const currentId = ref(0); // 当前操作的ID
const editVisible = ref(false); // 编辑对话框显示状态
const detailVisible = ref(false); // 详情对话框显示状态
const rowKeys = ref([]); // 表格选中行Key
// 查询参数
const formParams = reactive({ name: '', type: '', status: '' });
// 操作栏配置
const actionColumn = reactive({
width: 300,
label: '操作',
prop: 'action',
width: 280,
title: '操作',
align: 'center',
key: 'action',
fixed: 'right',
render(record) {
return h(TableAction, {
return h(TableAction as any, {
style: 'button',
actions: [
{ label: '编辑', icon: 'Edit', type: 'warning', onClick: handleEdit.bind(null, record), auth: ['sys:example:update'] },
{ label: '详情', icon: 'View', type: '', onClick: handleDetail.bind(null, record), auth: ['sys:example:detail'] },
{ label: '删除', icon: 'Delete', type: 'danger', onClick: handleDelete.bind(null, record), auth: ['sys:example:delete'] },
{
label: '编辑',
icon: renderIcon(EditOutlined),
type: 'info',
onClick: handleEdit.bind(null, record),
auth: ['sys:example:update'],
},
{
label: '详情',
icon: renderIcon(EyeOutlined),
type: 'default',
onClick: handleDetail.bind(null, record),
auth: ['sys:example:detail'],
},
{
label: '删除',
icon: renderIcon(DeleteOutlined),
type: 'error',
onClick: handleDelete.bind(null, record),
auth: ['sys:example:delete'],
},
],
});
},
@@ -99,105 +161,194 @@ ui/src/views/tool/example/
// 加载数据
const loadDataTable = async (params: any) => {
return await getExamplePage({ ...formParams, ...params });
rowKeys.value = [];
const result = await getExamplePage({ ...formParams, ...params });
return result;
};
// 注册搜索表单
const [register, {}] = useForm({
gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
labelWidth: 80,
layout: 'horizontal',
colProps: { span: 6 },
submitOnReset: true,
schemas,
});
// 提交搜索
function handleSubmit(values: Recordable) {
handleReset();
for (const key in formParams) { formParams[key] = ''; }
for (const key in values) { formParams[key] = values[key]; }
reloadTable();
}
// 重置搜索
function handleReset() {
function handleReset(values: Recordable) {
for (const key in formParams) { formParams[key] = ''; }
for (const key in values) { formParams[key] = values[key]; }
reloadTable();
}
// 表格选择项变化
function onCheckedRow(keys: (string | number)[]) {
rowKeys.value = keys;
}
// 刷新表格
function reloadTable(noRefresh = '') {
basicTableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
}
// 新增
const handleAdd = async () => { currentId.value = 0; await nextTick(); editVisible.value = true; };
const handleAdd = async () => {
currentId.value = 0;
editVisible.value = true;
await nextTick();
editModalRef.value?.openModal();
};
// 编辑
const handleEdit = async (record: Recordable) => { currentId.value = record.row.id; await nextTick(); editVisible.value = true; };
const handleEdit = async (record: Recordable) => {
currentId.value = record.id;
editVisible.value = true;
await nextTick();
editModalRef.value?.openModal();
};
// 详情
const handleDetail = async (record: Recordable) => { currentId.value = record.row.id; await nextTick(); detailVisible.value = true; };
const handleDetail = async (record: Recordable) => {
currentId.value = record.id;
detailVisible.value = true;
await nextTick();
detailModalRef.value?.openModal();
};
// 删除
async function handleDelete(record: Recordable) {
// 删除（支持单个删除和批量删除）
async function handleDelete(record?: Recordable) {
let ids = [];
if (!record) {
ids = selectionData.value.map(({ id }) => id);
if (!ids.length) { message('请选择要删除的数据', 'warning'); return; }
ids = rowKeys.value;
if (!ids.length) {
message.warning('请选择要删除的数据');
return;
}
}
await confirm('确定要删除选中的案例吗？');
record ? await exampleDelete(record.row.id) : await exampleBatchDelete(ids);
message('删除成功');
reloadTable();
dialog.warning({
title: '提示',
content: '确定要删除选中的案例吗？',
positiveText: '确定',
negativeText: '取消',
onPositiveClick: async () => {
record ? await exampleDelete(record.id) : await exampleBatchDelete(ids);
message.success('删除成功');
reloadTable();
},
});
}
</script>
```
### 关键点
- **PageWrapper**：页面容器，提供统一的页面布局
- **BasicForm**：搜索表单组件，通过 `useForm` 注册
- **BasicTable**：数据表格组件，内置分页功能
- **TableAction**：操作栏组件，支持权限控制
- **defineAsyncComponent**：懒加载弹窗组件，优化首屏加载
- **n-card**：NaiveUI 卡片容器，提供统一的页面布局
- **BasicForm**：搜索表单组件，通过 `useForm` 注册，`gridProps` 配置响应式栅格
- **BasicTable**：数据表格组件，内置分页功能，使用 `@update:checked-row-keys` 监听多选
- **TableAction**：操作栏组件，图标通过 `renderIcon` 包装 `@vicons/antd` 图标
- **useMessage / useDialog**：NaiveUI 的消息和对话框 Hook
- **v-perm**：权限指令，控制按钮显示
## 2. 编辑弹窗 edit.vue
编辑弹窗是独立组件，负责新增和编辑操作的表单展示与提交。
编辑弹窗是独立组件，负责新增和编辑操作的表单展示与提交。使用 `basicModal` + `useModal` 模式。
### 核心结构
```vue
<template>
<el-dialog
v-model="props.visible"
:title="props.id ? '编辑案例' : '新增案例'"
width="500"
:close-on-click-modal="false"
:before-close="dialogClose"
<basicModal
@register="modalRegister"
ref="modalRef"
class="basicModal basicFormModal"
@on-ok="handleSubmit"
@on-close="dialogClose"
>
<el-form class="ls-form" ref="formRef" :model="formData" label-width="80px">
<el-form-item label="案例名称" prop="name" :rules="{ required: true, message: '请输入案例名称', trigger: 'blur' }">
<el-input v-model="formData.name" placeholder="请输入案例名称" clearable />
</el-form-item>
<el-form-item label="案例图片" prop="avatar">
<UploadImg v-model:image-url="formData.avatar" name="example" />
</el-form-item>
<el-form-item label="案例类型" prop="type" :rules="{ required: true, message: '请选择案例类型', trigger: 'change' }">
<el-select v-model="formData.type" placeholder="请选择" clearable filterable>
<el-option v-for="item in optionsData.typeList" :key="item.id" :label="item.name" :value="item.id" />
</el-select>
</el-form-item>
<el-form-item label="案例状态" prop="status" :rules="{ required: true, message: '请选择状态', trigger: 'change' }">
<el-radio-group v-model="formData.status">
<el-radio :value="1">正常</el-radio>
<el-radio :value="2">禁用</el-radio>
</el-radio-group>
</el-form-item>
<el-form-item label="排序" prop="sort" :rules="{ required: true, message: '请输入排序', trigger: 'blur' }">
<el-input-number v-model="formData.sort" :min="0" :max="99999" />
</el-form-item>
</el-form>
<template #footer>
<el-button @click="dialogClose">取消</el-button>
<el-button :loading="subLoading" type="primary" @click="submit">确定</el-button>
<template #default>
<n-form
class="ls-form"
ref="formRef"
:model="formData"
label-placement="left"
label-width="80px"
>
<!-- 案例名称 -->
<n-form-item
label="案例名称"
path="name"
:rule="{ required: true, message: '请输入案例名称', trigger: 'blur' }"
>
<n-input
class="ls-input"
v-model:value="formData.name"
placeholder="请输入案例名称"
clearable
/>
</n-form-item>
<!-- 案例图片（图片上传） -->
<n-form-item label="案例图片" path="avatar">
<UploadImg
@change-file-name="(name) => (formData.avatarImgName = name)"
:fileType="['image/jpeg', 'image/png', 'image/jpg', 'image/gif', 'image/webp']"
name="example"
:fileSize="20"
v-model:image-url="formData.avatar"
>
<template #tip>支持扩展名: jpg png jpeg gif webp; 文件大小不超过20M</template>
</UploadImg>
</n-form-item>
<!-- 案例类型（下拉选择） -->
<n-form-item
label="案例类型"
path="type"
:rule="{
type: 'number',
required: true,
message: '请选择案例类型',
trigger: 'change',
}"
>
<n-select
v-model:value="formData.type"
placeholder="请选择案例类型"
clearable
filterable
:options="optionsData.typeList"
/>
</n-form-item>
<!-- 案例状态（单选） -->
<n-form-item
label="案例状态"
path="status"
:rule="{
type: 'number',
required: true,
message: '请选择案例状态',
trigger: 'change',
}"
>
<n-radio-group v-model:value="formData.status">
<n-radio :value="1">正常</n-radio>
<n-radio :value="2">禁用</n-radio>
</n-radio-group>
</n-form-item>
<!-- 排序（数字输入） -->
<n-form-item
label="排序"
path="sort"
:rule="{ type: 'number', required: true, message: '请输入排序', trigger: 'blur' }"
>
<n-input-number v-model:value="formData.sort" :min="0" :max="99999" />
</n-form-item>
</n-form>
</template>
</el-dialog>
</basicModal>
</template>
```
@@ -206,11 +357,187 @@ ui/src/views/tool/example/
```vue
<script lang="ts" setup>
import { getExampleDetail, exampleAdd, exampleUpdate } from '@/api/tool/example';
import { onMounted, reactive, shallowRef, watch } from 'vue';
import { useLockFn } from '@/utils/useLockFn';
import { onMounted, reactive, ref, watch } from 'vue';
import { useMessage } from 'naive-ui';
import { useModal } from '@/components/Modal';
import UploadImg from '@/components/Upload/Image.vue';
// 定义事件
const emit = defineEmits(['success', 'update:visible']);
const formRef = shallowRef<FormInstance>();
// 消息提示
const message = useMessage();
// 表单引用
const formRef = ref();
// 选项数据
const optionsData = reactive({
typeList: [
{ label: '类型1', value: 1 },
{ label: '类型2', value: 2 },
{ label: '类型3', value: 3 },
{ label: '类型4', value: 4 },
],
});
// 表单数据
const formData = reactive({
id: '',
name: '',
avatar: '',
type: 1,
status: 1,
sort: 0,
avatarImgName: '',
});
// 接收的参数
const props = defineProps({
visible: { type: Boolean, required: true, default: false },
id: { type: Number, required: true, default: 0 },
});
// 定义模态框
const [modalRegister, { openModal, setSubLoading, closeModal }] = useModal({
title: props.id ? '编辑案例' : '新增案例',
subBtuText: '确定',
width: 500,
});
// 提交表单
const handleSubmit = async () => {
formRef.value
.validate()
.then(async () => {
props.id ? await exampleUpdate(formData) : await exampleAdd(formData);
message.success('操作成功');
setSubLoading(false);
emit('update:visible', false);
emit('success');
})
.catch(() => {
setSubLoading(false);
});
};
// 关闭窗体
const dialogClose = () => {
emit('update:visible', false);
};
// 编辑时加载数据
const setFormData = async () => {
const data = await getExampleDetail(props.id);
for (const key in formData) {
if (data[key] != null && data[key] != undefined) {
// @ts-ignore
formData[key] = data[key];
}
}
};
// 重置表单
const resetForm = () => {
if (formRef.value) {
formRef.value.restoreValidation();
}
};
// 监听visible变化
watch(
() => props.visible,
(newVal) => {
if (newVal && props.id) {
setFormData();
openModal();
} else if (newVal && !props.id) {
resetForm();
openModal();
}
},
);
onMounted(() => {
if (props.visible) {
if (props.id) { setFormData(); } else { resetForm(); }
openModal();
}
});
defineExpose({ openModal });
</script>
```
### 关键点
- **basicModal + useModal**：NaiveUI 弹窗模式，通过 `useModal` 注册弹窗
- **n-form + n-form-item**：NaiveUI 表单组件，使用 `path` 指定字段，`:rule` 定义校验规则
- **n-select + :options**：NaiveUI 下拉选择，选项通过 `:options` 传入
- **n-radio-group + n-radio**：NaiveUI 单选组件
- **n-input-number**：NaiveUI 数字输入组件
- **useMessage**：NaiveUI 消息 Hook
- **setSubLoading**：通过 `useModal` 控制弹窗确认按钮的 loading 状态
- **openModal / closeModal**：通过 `useModal` 返回的方法控制弹窗显隐
## 3. 详情弹窗 detail.vue
详情弹窗用于展示记录的详细信息，使用 NaiveUI 的 `n-descriptions` 组件。
### 核心结构
```vue
<template>
<basicModal @register="modalRegister" ref="modalRef" class="basicModal basicFormModal">
<template #default>
<n-descriptions
class="margin-top"
:column="2"
bordered
:label-style="{ width: '120px' }"
label-placement="left"
>
<n-descriptions-item label="案例名称:">
<span>{{ formData.name || '-' }}</span>
</n-descriptions-item>
<n-descriptions-item label="案例图片:">
<n-image
v-if="formData.avatar"
:src="formData.avatar"
width="80"
height="80"
fit="cover"
:preview-disabled="false"
/>
<span v-else>-</span>
</n-descriptions-item>
<n-descriptions-item label="案例类型:">
<span>{{ getChoiceLabel('type', formData.type) }}</span>
</n-descriptions-item>
<n-descriptions-item label="案例状态:">
<span>{{ getChoiceLabel('status', formData.status) }}</span>
</n-descriptions-item>
<n-descriptions-item label="排序:">
<span>{{ formData.sort || '-' }}</span>
</n-descriptions-item>
</n-descriptions>
</template>
<template #action>
<n-button @click="dialogClose">关闭</n-button>
</template>
</basicModal>
</template>
```
### 核心逻辑
```vue
<script lang="ts" setup>
import { getExampleDetail } from '@/api/tool/example';
import { onMounted, reactive, watch } from 'vue';
import { useModal } from '@/components/Modal';
const emit = defineEmits(['update:visible']);
const formData = reactive({
id: '', name: '', avatar: '', type: 0, status: 0, sort: 0,
@@ -221,71 +548,61 @@ ui/src/views/tool/example/
id: { type: Number, required: true, default: 0 },
});
// 提交表单
const handleSubmit = async () => {
await formRef.value?.validate();
props.id ? await exampleUpdate(formData) : await exampleAdd(formData);
message('操作成功');
emit('update:visible', false);
emit('success');
const [modalRegister, { openModal, closeModal }] = useModal({
title: '案例详情',
width: 750,
});
// 获取选项字段的标签
const getChoiceLabel = (fieldName: string, value: any) => {
const choiceMap: Record<string, Record<string, string>> = {
type: { 1: '类型1', 2: '类型2', 3: '类型3', 4: '类型4' },
status: { 1: '正常', 2: '禁用' },
};
return choiceMap[fieldName]?.[value] || value || '-';
};
// 防重复提交
const { isLock: subLoading, lockFn: submit } = useLockFn(handleSubmit);
const dialogClose = () => {
closeModal();
emit('update:visible', false);
};
// 编辑时加载数据
const setFormData = async () => {
const data = await getExampleDetail(props.id);
for (const key in formData) {
if (data[key] != null && data[key] != undefined) { formData[key] = data[key]; }
if (data[key] != null && data[key] != undefined) {
formData[key] = data[key];
}
}
};
watch(
() => props.visible,
(newVal) => {
if (newVal && props.id) {
setFormData();
openModal();
}
},
);
onMounted(() => {
if (props.id) { setFormData(); } else { resetForm(); }
if (props.visible && props.id) {
setFormData();
openModal();
}
});
defineExpose({ openModal });
</script>
```
### 关键点
- **Props 接收**：`visible` 控制弹窗显示，`id` 区分新增/编辑模式
- **新增/编辑判断**：`props.id ? exampleUpdate : exampleAdd`
- **防重复提交**：`useLockFn` 包装提交函数，点击后按钮变为 loading 状态
- **数据回填**：编辑模式下调用 `getExampleDetail` 获取数据并填充表单
- **事件通信**：`emit('update:visible')` 关闭弹窗，`emit('success')` 通知刷新
## 3. 详情弹窗 detail.vue
详情弹窗用于展示记录的详细信息，使用 ElementPlus 的 `el-descriptions` 组件。
### 核心结构
```vue
<template>
<el-dialog v-model="props.visible" title="案例详情" width="750" :close-on-click-modal="false">
<el-descriptions column="2" border>
<el-descriptions-item label="案例名称:">{{ formData.name || '-' }}</el-descriptions-item>
<el-descriptions-item label="案例图片:">
<el-image v-if="formData.avatar" :src="formData.avatar" :preview-src-list="[formData.avatar]" fit="cover" style="width: 80px; height: 80px" />
<span v-else>-</span>
</el-descriptions-item>
<el-descriptions-item label="案例类型:">{{ getChoiceLabel('type', formData.type) }}</el-descriptions-item>
<el-descriptions-item label="案例状态:">{{ getChoiceLabel('status', formData.status) }}</el-descriptions-item>
<el-descriptions-item label="排序:">{{ formData.sort || '-' }}</el-descriptions-item>
</el-descriptions>
<template #footer>
<el-button @click="dialogClose">关闭</el-button>
</template>
</el-dialog>
</template>
```
### 关键点
- **el-descriptions**：ElementPlus 的描述列表组件，用于展示详情
- **basicModal**：使用 `basicModal` + `useModal` 注册弹窗
- **n-descriptions**：NaiveUI 的描述列表组件，用于展示详情
- **n-image**：NaiveUI 的图片组件，支持预览功能
- **getChoiceLabel**：将枚举值转换为中文标签
- **图片预览**：使用 `el-image` 的 `preview-src-list` 实现图片预览
## 4. 表格列定义 columns.ts
@@ -295,54 +612,92 @@ ui/src/views/tool/example/
```typescript
import { h } from 'vue';
import { ElAvatar, ElTag } from 'element-plus';
import { NTag, NAvatar, NImage } from 'naive-ui';
export const columns = [
{ type: 'selection' },
{ label: 'ID', prop: 'id', fixed: 'left', width: 50 },
{ label: '案例名称', prop: 'name', minWidth: 120 },
{
label: '案例图片', prop: 'avatar', minWidth: 120,
type: 'selection', // 多选框列
width: 50,
fixed: 'left',
},
{
title: 'ID',
key: 'id',
fixed: 'left',
width: 50,
},
{
title: '案例名称',
key: 'name',
width: 150,
ellipsis: { tooltip: true },
},
{
title: '案例图片',
key: 'avatar',
width: 150,
render(record) {
return h(ElAvatar, { size: 48, src: record.row.avatar, shape: 'square', fit: 'fill' });
return record.avatar
? h(NAvatar, {
src: record.avatar,
size: 48,
shape: 'square',
fit: 'cover',
style: { borderRadius: '4px' },
})
: h('span', '-');
},
},
{
label: '案例类型', prop: 'type', minWidth: 100,
title: '案例类型',
key: 'type',
width: 100,
render(record) {
const statusMap = {
1: { text: '类型1', type: 'success' },
2: { text: '类型2', type: 'danger' },
2: { text: '类型2', type: 'error' },
3: { text: '类型3', type: 'warning' },
4: { text: '类型4', type: 'info' },
};
const status = statusMap[record.row.type];
return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.type });
const status = statusMap[record.type];
return h(
NTag,
{ bordered: false, type: status?.type || 'info' },
{ default: () => status?.text || record.type },
);
},
},
{
label: '案例状态', prop: 'status', minWidth: 100,
title: '案例状态',
key: 'status',
width: 100,
render(record) {
const statusMap = {
1: { text: '正常', type: 'success' },
2: { text: '禁用', type: 'danger' },
2: { text: '禁用', type: 'error' },
};
const status = statusMap[record.row.status];
return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.status });
const status = statusMap[record.status];
return h(
NTag,
{ bordered: false, type: status?.type || 'info' },
{ default: () => status?.text || record.status },
);
},
},
{ label: '排序', prop: 'sort', minWidth: 100 },
{ label: '创建人', prop: 'createUser', minWidth: 100 },
{ label: '创建时间', prop: 'createTime', width: 180 },
{ title: '排序', key: 'sort', width: 100, ellipsis: { tooltip: true } },
{ title: '创建人', key: 'createUser', width: 100 },
{ title: '创建时间', key: 'createTime', width: 180 },
];
```
### 关键点
- **title / key**：NaiveUI 列定义使用 `title` 和 `key` 指定列标题和字段名
- **type: 'selection'**：自动添加复选框列
- **render 函数**：使用 Vue 的 `h()` 函数创建虚拟 DOM
- **ElTag 组件**：将状态值渲染为彩色标签
- **ElAvatar 组件**：将图片 URL 渲染为缩略图
- **render 函数**：使用 Vue 的 `h()` 函数创建虚拟 DOM，`record` 直接是行数据
- **NTag 组件**：将状态值渲染为彩色标签
- **NAvatar 组件**：将图片 URL 渲染为缩略图
- **ellipsis**：NaiveUI 使用 `ellipsis: { tooltip: true }` 实现溢出省略
## 5. 搜索表单 querySchemas.ts
@@ -356,17 +711,21 @@ import { FormSchema } from '@/components/Form/index';
export const schemas: FormSchema[] = [
{
field: 'name',
component: 'Input',
component: 'NInput',
label: '案例名称',
componentProps: { placeholder: '请输入案例名称', clearable: true },
componentProps: {
placeholder: '请输入案例名称',
clearable: true,
},
},
{
field: 'type',
component: 'Select',
component: 'NSelect',
label: '案例类型',
componentProps: {
placeholder: '请输入案例类型',
clearable: true,
filterable: true,
options: [
{ label: '类型1', value: 1 },
{ label: '类型2', value: 2 },
@@ -377,11 +736,12 @@ export const schemas: FormSchema[] = [
},
{
field: 'status',
component: 'Select',
component: 'NSelect',
label: '案例状态',
componentProps: {
placeholder: '请输入案例状态',
clearable: true,
filterable: true,
options: [
{ label: '正常', value: 1 },
{ label: '禁用', value: 2 },
@@ -394,9 +754,9 @@ export const schemas: FormSchema[] = [
### 关键点
- **field**：字段名，与后端查询参数对应
- **component**：表单组件类型：`Input` / `Select` / `DatePicker` 等
- **componentProps**：组件属性，透传给 ElementPlus 组件
- **options**：Select 组件的下拉选项
- **component**：表单组件类型使用 NaiveUI 组件名：`NInput` / `NSelect`
- **componentProps**：组件属性，透传给 NaiveUI 组件
- **options**：NSelect 组件的下拉选项
## 文件关系图
@@ -419,12 +779,13 @@ detail.vue（详情弹窗）
1. **一个模块一个目录**：放在 `ui/src/views/{group}/{module}/` 下
2. **5 个文件各司其职**：主页面、编辑弹窗、详情弹窗、列定义、搜索 Schema
3. **弹窗是独立组件**：通过 Props 接收 ID，通过 Emit 通知父页面
4. **列定义使用 `h()` 渲染复杂内容**：如状态标签、图片缩略图
5. **搜索 Schema 使用 `FormSchema` 类型**：配置化定义表单字段
6. **新增/编辑通过 `id` 区分**：0 为新增，非 0 为编辑
7. **防重复提交使用 `useLockFn`**：提交时按钮 loading
3. **弹窗使用 basicModal + useModal**：通过 `useModal` 注册，`openModal()` 打开
4. **列定义使用 `h()` 渲染复杂内容**：如 NTag 状态标签、NAvatar 图片缩略图
5. **列定义使用 `title` / `key`**：指定列标题和字段名
6. **搜索 Schema 使用 `NInput` / `NSelect` 组件名**：NaiveUI 表单组件
7. **消息使用 `useMessage()` Hook**：NaiveUI 消息提示
8. **对话框使用 `useDialog()` Hook**：NaiveUI 确认对话框
## 总结
前端页面统一使用 `PageWrapper` + `BasicForm` + `BasicTable` + `TableAction` 四件套，分页由 `BasicTable` 内置处理。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`detail.vue`（详情弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）五个文件。
前端页面统一使用 `n-card` + `BasicForm` + `BasicTable` + `TableAction` 组件组合，分页由 `BasicTable` 内置处理。编辑弹窗使用 `basicModal` + `useModal` 模式。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`detail.vue`（详情弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）五个文件。
DjangoAdmin_Django_NaiveVue/zh/volume2/form.md
+58 -1
View File
@@ -16,15 +16,32 @@ from django import forms
from application.example import models
# =============================================================
# 案例表单验证类
# =============================================================
class ExampleForm(forms.ModelForm):
"""
案例表单验证类
用于创建和更新案例信息时的表单验证。
验证字段包括：name, avatar, type, status, sort
包含案例名称, 案例图片, 案例类型等属性
验证字段包括：
- name: 案例名称
- avatar: 案例图片
- type: 案例类型
- status: 案例状态（1-正常, 2-禁用）
- sort: 排序
"""
# ----------------------------------------------------------
# 案例名称
# ----------------------------------------------------------
# 字段说明: 案例的名称
# 字段类型: 字符串（CharField）
# 验证规则: 必填（required=True），最大长度100字符
# 业务说明: 案例的核心标识字段，用于列表展示和搜索
name = forms.CharField(
required=True,
max_length=100,
@@ -34,7 +51,13 @@ class ExampleForm(forms.ModelForm):
}
)
# ----------------------------------------------------------
# 案例图片
# ----------------------------------------------------------
# 字段说明: 案例的图片
# 字段类型: 字符串（CharField）
# 验证规则: 可选（required=False），最大长度255字符
# 业务说明: 用于案例列表展示和详情页的图片
avatar = forms.CharField(
required=False,
max_length=255,
@@ -43,7 +66,13 @@ class ExampleForm(forms.ModelForm):
}
)
# ----------------------------------------------------------
# 案例类型
# ----------------------------------------------------------
# 字段说明: 案例的分类类型
# 字段类型: 整数（IntegerField）
# 验证规则: 必填（required=True），取值范围1-4
# 业务说明: 对案例进行分类管理，支持按类型筛选
type = forms.IntegerField(
required=True,
min_value=1,
@@ -55,7 +84,13 @@ class ExampleForm(forms.ModelForm):
}
)
# ----------------------------------------------------------
# 案例状态
# ----------------------------------------------------------
# 字段说明: 案例的显示状态
# 字段类型: 整数（IntegerField）
# 验证规则: 必填（required=True），取值范围1-2
# 业务说明: 1-正常, 2-禁用，控制案例是否在前端展示
status = forms.IntegerField(
required=True,
min_value=1,
@@ -67,7 +102,14 @@ class ExampleForm(forms.ModelForm):
}
)
# ----------------------------------------------------------
# 排序
# ----------------------------------------------------------
# 字段说明: 案例的排序权重
# 字段类型: 整数（IntegerField）
# 验证规则: 必填（required=True）
# 排序规则: 数值越小越靠前
# 业务说明: 手动控制案例在列表中的显示顺序
sort = forms.IntegerField(
required=True,
error_messages={
@@ -75,8 +117,23 @@ class ExampleForm(forms.ModelForm):
}
)
# =============================================================
# 表单元数据配置
# =============================================================
class Meta:
"""
表单元数据配置类
定义表单绑定的模型和需要验证的字段。
"""
# 绑定模型
# 指定该表单对应的数据模型为 Example（案例）
model = models.Example
# 指定需要验证的字段
# 只验证以下字段，其他字段不进行表单验证
fields = [
'name',
'avatar',
DjangoAdmin_Django_NaiveVue/zh/volume2/model.md
+89 -7
View File
@@ -17,6 +17,10 @@ from application.models import BaseModel
from utils.common import get_table_name
# =============================================================
# 案例模型类
# =============================================================
class Example(BaseModel):
"""
案例模型类
@@ -29,29 +33,53 @@ class Example(BaseModel):
- create_time: 创建时间
- update_user: 更新人
- update_time: 更新时间
主要业务字段：
- name: 案例名称
- avatar: 案例图片
- type: 案例类型
- status: 案例状态（1-正常, 2-禁用）
- sort: 排序权重（数值越小越靠前）
"""
# ----------------------------------------------------------
# 案例名称
# ----------------------------------------------------------
# 字段说明: 案例的名称
# 字段类型: 字符串（CharField）
# 约束: 非空（null=False），最大长度100字符
# 索引: 添加了数据库索引（db_index=True）以提升查询效率
# 作用: 案例的核心标识字段，用于列表展示和搜索
name = models.CharField(
null=False,
max_length=100,
db_index=True,
verbose_name="案例名称",
help_text="案例名称",
db_comment='案例名称'
db_comment='案例名称' # 数据库字段注释
)
# ----------------------------------------------------------
# 案例图片
# ----------------------------------------------------------
# 字段说明: 案例的图片
# 字段类型: 字符串（CharField）
# 约束: 允许为空（null=True, blank=True），最大长度255字符
# 存储: 存储的是相对路径，通过 get_file_url() 生成完整访问URL
# 作用: 用于案例列表展示和详情页的图片
avatar = models.CharField(
null=True,
blank=True,
max_length=255,
verbose_name="案例图片",
help_text="案例图片",
db_comment='案例图片'
db_comment='案例图片' # 数据库字段注释
)
# ----------------------------------------------------------
# 案例类型
# ----------------------------------------------------------
# 类型常量定义
TYPE_CHOICES = (
(1, "类型1"),
(2, "类型2"),
@@ -59,44 +87,98 @@ class Example(BaseModel):
(4, "类型4"),
)
# 字段说明: 案例的分类类型
# 字段类型: 整数（IntegerField）
# 约束: 非空（null=False）
# 选择项: 使用 TYPE_CHOICES 限制可选值
# 作用: 对案例进行分类管理，支持按类型筛选
type = models.IntegerField(
null=False,
choices=TYPE_CHOICES,
verbose_name="案例类型：1-类型1 2-类型2 3-类型3 4-类型4",
help_text="案例类型：1-类型1 2-类型2 3-类型3 4-类型4",
db_comment='案例类型：1-类型1 2-类型2 3-类型3 4-类型4'
db_comment='案例类型：1-类型1 2-类型2 3-类型3 4-类型4' # 数据库字段注释
)
# ----------------------------------------------------------
# 案例状态
# ----------------------------------------------------------
# 状态常量定义
STATUS_CHOICES = (
(1, "正常"),
(2, "禁用"),
(1, "正常"), # 正常状态：案例正常显示
(2, "禁用"), # 禁用状态：案例不对外展示
)
# 字段说明: 案例的显示状态
# 字段类型: 整数（IntegerField）
# 约束: 非空（null=False）
# 选择项: 使用 STATUS_CHOICES 限制可选值
# 作用: 控制案例是否在前端展示
status = models.IntegerField(
null=False,
choices=STATUS_CHOICES,
verbose_name="案例状态：1-正常 2-禁用",
help_text="案例状态：1-正常 2-禁用",
db_comment='案例状态：1-正常 2-禁用'
db_comment='案例状态：1-正常 2-禁用' # 数据库字段注释
)
# ----------------------------------------------------------
# 排序
# ----------------------------------------------------------
# 字段说明: 案例的排序权重
# 字段类型: 整数（IntegerField）
# 约束: 非空（null=False）
# 排序规则: 数值越小越靠前（升序排列）
# 作用: 手动控制案例在列表中的显示顺序
sort = models.IntegerField(
null=False,
verbose_name="排序",
help_text="排序",
db_comment='排序'
db_comment='排序' # 数据库字段注释
)
# =============================================================
# 模型元数据配置
# =============================================================
class Meta:
"""
模型元数据配置类
定义模型在数据库中的表名、显示名称、默认排序规则等。
"""
# 数据表名
# 使用配置文件中的表前缀 + "example"，避免与其他应用表名冲突
db_table = get_table_name('example')
# 表注释（Django 3.2+ 支持）
# 在数据库中生成 COMMENT 语句，便于数据库管理
db_table_comment = "案例表"
# 模型在admin后台显示的友好名称（单数）
verbose_name = "案例表"
# 模型在admin后台显示的友好名称（复数）
verbose_name_plural = verbose_name
# 默认排序规则
# 按照 sort 字段升序排列（数值小的在前），确保显示顺序可控
ordering = ("sort",)
# =============================================================
# 实例方法
# =============================================================
def __str__(self):
"""
模型的字符串表示方法
当需要将模型实例转换为字符串时调用，如admin后台显示、日志输出等。
Returns:
str: 包含案例名称的字符串
"""
return f"案例{self.name}"
```
DjangoAdmin_Django_NaiveVue/zh/volume2/permission.md
+2 -2
View File
@@ -101,10 +101,10 @@ class PermissionRequired(PermissionRequiredMixin):
```vue
<!-- 新增按钮 -->
<el-button v-perm="['sys:example:add']">添加案例</el-button>
<n-button v-perm="['sys:example:add']">添加案例</n-button>
<!-- 批量删除按钮 -->
<el-button v-perm="['sys:example:batchDelete']">批量删除</el-button>
<n-button v-perm="['sys:example:batchDelete']">批量删除</n-button>
```
操作栏按钮使用 `auth` 属性：
DjangoAdmin_Django_NaiveVue/zh/volume2/url.md
+61 -1
View File
@@ -17,30 +17,90 @@ application/urls.py # 主路由
from django.urls import path
from application.example import views
"""
案例模块路由配置
=============================================================
URL端点概览：
------------------------------------------------------------------------
| 功能说明 | 请求方法 | URL路径 | 视图类 |
|-----------------|----------|-----------------------------|-------------------------|
| 分页查询 | GET | /example/page | ExamplePageView |
| 列表查询 | GET | /example/list | ExampleListView |
| 详情查询 | GET | /example/detail/<id> | ExampleDetailView |
| 添加案例 | POST | /example/add | ExampleAddView |
| 更新案例 | PUT | /example/update | ExampleUpdateView |
| 删除案例 | DELETE | /example/delete/<ids>| ExampleDeleteView |
| 设置状态 | PUT | /example/status | ExampleStatusView |
| 获取列表 | GET | /example/data | ExampleDataView |
------------------------------------------------------------------------
URL参数说明：
- id: int类型，案例ID（用于查询详情）
- id: str类型，逗号分隔的案例ID字符串（用于批量删除）
使用示例：
1. 分页查询：GET /api/example/page?pageNo=1&pageSize=10
2. 列表查询：GET /api/example/list
3. 详情查询：GET /api/example/detail/5
4. 添加案例：POST /api/example/add
5. 更新案例：PUT /api/example/update
6. 删除案例：DELETE /api/example/delete/1,2,3
7. 设置状态：PUT /api/example/status
8. 获取列表：GET /api/example/data
"""
# 案例模块路由配置
urlpatterns = [
# 查询案例分页列表
# URL: /example/page
# 请求方法: GET
# 功能: 获取案例分页数据，支持按案例名称、案例类型、案例状态等条件筛选
path('page', views.ExamplePageView.as_view()),
# 查询案例数据列表（支持筛选）
# URL: /example/list
# 请求方法: GET
# 功能: 获取所有案例的列表数据，支持按条件筛选，用于下拉选择等前端组件
path('list', views.ExampleListView.as_view()),
# 查询案例详情
# URL: /example/detail/<int:id>
# 请求方法: GET
# URL参数: id - 案例ID（整数类型）
# 功能: 根据ID获取指定案例的详细信息
path('detail/<int:id>', views.ExampleDetailView.as_view()),
# 添加案例
# URL: /example/add
# 请求方法: POST
# 功能: 创建新的案例记录，请求体需包含案例信息（name、avatar、type、status、sort等）
path('add', views.ExampleAddView.as_view()),
# 更新案例
# URL: /example/update
# 请求方法: PUT
# 功能: 更新现有案例信息，请求体需包含案例ID和更新内容
path('update', views.ExampleUpdateView.as_view()),
# 删除案例
# URL: /example/delete/<str:id>
# 请求方法: DELETE
# URL参数: id - 案例ID字符串，支持单个ID或逗号分隔的多个ID（如 "1,2,3"）
# 功能: 删除指定案例（逻辑删除，设置is_delete=True）
path('delete/<str:id>', views.ExampleDeleteView.as_view()),
# 设置案例状态
# URL: /example/status
# 请求方法: PUT
# 功能: 更新案例的启用/禁用状态
path('status', views.ExampleStatusView.as_view()),
# 查询案例数据列表
path('list', views.ExampleDataView.as_view()),
# URL: /example/data
# 请求方法: GET
# 功能: 获取所有启用案例的列表数据，用于下拉选择等前端组件
path('data', views.ExampleDataView.as_view()),
]
```
DjangoAdmin_Django_NaiveVue/zh/volume2/view.md
+225 -13
View File
@@ -23,93 +23,305 @@ from application.operation_log.constants import LogType
from application.operation_log.decorators import operation_log
# =============================================================
# 分页查询视图
# =============================================================
@method_decorator(check_login, name="get")
class ExamplePageView(PermissionRequired, View):
"""案例分页数据查询视图"""
"""
案例分页数据查询视图
处理GET请求，返回案例列表的分页数据。
支持按案例名称、案例类型、案例状态等条件筛选。
URL: /example/page
请求方法: GET
权限要求：sys:example:page
"""
# 方法权限标识
permission_required = ("sys:example:page",)
@operation_log(title="案例管理-查询分页列表", log_type=LogType.QUERY)
@operation_log(
title="案例管理-查询分页列表",
log_type=LogType.QUERY
)
def get(self, request):
"""
处理GET请求，返回案例分页数据
Args:
request: HttpRequest对象，包含分页参数和筛选条件
- pageNo: 当前页码
- pageSize: 每页记录数
- name: 案例名称（可选，模糊查询）
- type: 案例类型（可选，精确匹配）
- status: 案例状态（可选，精确匹配）
Returns:
JsonResponse: 包含分页数据的JSON响应
"""
result = services.get_example_page(request)
return result
# =============================================================
# 列表查询视图（不分页）
# =============================================================
@method_decorator(check_login, name='get')
class ExampleListView(View):
"""案例列表获取视图（支持筛选，不分页）"""
"""
案例列表获取视图（支持筛选，不分页）
处理GET请求，返回所有案例的列表数据。
支持按案例名称、案例类型、案例状态等条件筛选。
URL: /example/list
请求方法: GET
权限要求：需要登录
"""
def get(self, request):
"""
处理GET请求，返回案例列表
Args:
request: HttpRequest对象
Returns:
JsonResponse: 包含案例列表的JSON响应
"""
result = services.get_example_list(request)
return R.ok(data=result)
# =============================================================
# 详情查询视图
# =============================================================
@method_decorator(check_login, name="get")
class ExampleDetailView(PermissionRequired, View):
"""案例详情查询视图"""
"""
案例详情查询视图
处理GET请求，根据案例ID返回案例详细信息。
URL: /example/detail/<int:id>
请求方法: GET
权限要求：sys:example:detail
"""
# 方法权限标识
permission_required = ("sys:example:detail",)
@operation_log(title="案例管理-查询记录详情", log_type=LogType.QUERY)
@operation_log(
title="案例管理-查询记录详情",
log_type=LogType.QUERY
)
def get(self, request, id):
"""
处理GET请求，返回案例详情
Args:
request: HttpRequest对象
id: 案例ID（URL参数）
Returns:
JsonResponse: 包含案例详情的JSON响应
"""
data = services.get_example_detail(id)
return R.ok(data=data)
# =============================================================
# 添加视图
# =============================================================
@method_decorator(check_login, name="post")
class ExampleAddView(PermissionRequired, View):
"""添加案例视图"""
"""
添加案例视图
处理POST请求，创建新的案例记录。
请求体需包含案例信息（name、avatar、type、status、sort等）。
URL: /example/add
请求方法: POST
权限要求：sys:example:add
"""
# 方法权限标识
permission_required = ("sys:example:add",)
@operation_log(title="案例管理-添加记录", log_type=LogType.ADD)
@operation_log(
title="案例管理-添加记录",
log_type=LogType.ADD
)
def post(self, request):
"""
处理POST请求，添加案例
Args:
request: HttpRequest对象，请求体包含案例信息
Returns:
JsonResponse: 操作结果的JSON响应
"""
# 演示模式检查
if DJANGO_DEMO:
return R.failed("演示环境，暂无操作权限")
result = services.add_example(request)
return result
# =============================================================
# 更新视图
# =============================================================
@method_decorator(check_login, name="put")
class ExampleUpdateView(PermissionRequired, View):
"""更新案例视图"""
"""
更新案例视图
处理PUT请求，更新现有案例信息。
请求体需包含案例ID和更新内容。
URL: /example/update
请求方法: PUT
权限要求：sys:example:update
"""
# 方法权限标识
permission_required = ('sys:example:update',)
@operation_log(title="案例管理-更新记录", log_type=LogType.UPDATE)
@operation_log(
title="案例管理-更新记录",
log_type=LogType.UPDATE
)
def put(self, request):
"""
处理PUT请求，更新案例
Args:
request: HttpRequest对象，请求体包含更新信息
Returns:
JsonResponse: 操作结果的JSON响应
"""
# 演示模式检查
if DJANGO_DEMO:
return R.failed("演示环境，暂无操作权限")
result = services.update_example(request)
return result
# =============================================================
# 删除视图
# =============================================================
@method_decorator(check_login, name="delete")
class ExampleDeleteView(PermissionRequired, View):
"""删除案例视图"""
"""
删除案例视图
处理DELETE请求，删除指定案例（逻辑删除）。
支持批量删除，多个ID用逗号分隔。
URL: /example/delete/<str:id>
请求方法: DELETE
权限要求：sys:example:delete
"""
# 方法权限标识
permission_required = ('sys:example:delete',)
@operation_log(title="案例管理-删除记录", log_type=LogType.DELETE)
@operation_log(
title="案例管理-删除记录",
log_type=LogType.DELETE
)
def delete(self, request, id):
"""
处理DELETE请求，删除案例
Args:
request: HttpRequest对象
id: 案例ID字符串，支持逗号分隔的多个ID（如 "1,2,3"）
Returns:
JsonResponse: 操作结果的JSON响应
"""
# 演示模式检查
if DJANGO_DEMO:
return R.failed("演示环境，暂无操作权限")
result = services.delete_examples(id)
return result
# =============================================================
# 状态更新视图
# =============================================================
@method_decorator(check_login, name="put")
class ExampleStatusView(PermissionRequired, View):
"""设置案例状态视图"""
"""
设置案例状态视图
处理PUT请求，更新案例的启用/禁用状态。
URL: /example/status
请求方法: PUT
权限要求：sys:example:status
"""
# 方法权限标识
permission_required = ('sys:example:status',)
def put(self, request):
"""
处理PUT请求，更新案例状态
Args:
request: HttpRequest对象，请求体包含案例ID和新状态
Returns:
JsonResponse: 操作结果的JSON响应
"""
# 演示模式检查
if DJANGO_DEMO:
return R.failed("演示环境，暂无操作权限")
result = services.update_example_status(request)
return result
# =============================================================
# 数据列表视图（下拉选择用）
# =============================================================
@method_decorator(check_login, name='get')
class ExampleDataView(View):
"""案例列表获取视图"""
"""
案例列表获取视图
处理GET请求，返回所有启用案例的列表数据。
用于下拉选择等前端组件。
URL: /example/data
请求方法: GET
权限要求：需要登录
"""
def get(self, request):
"""
处理GET请求，返回案例数据列表
Args:
request: HttpRequest对象
Returns:
JsonResponse: 包含案例列表的JSON响应
"""
result = services.get_example_data()
return R.ok(data=result)
```
DjangoAdmin_Django_NaiveVue/zh/volume3/base-classes.md
+68 -33
View File
@@ -53,65 +53,100 @@ JsonResponse <-- Django HTTP响应
```python
class BaseModel(models.Model):
"""基础模型抽象类"""
"""
基础模型抽象类
==============
功能：提供所有模型的公共字段，如主键、创建人、创建时间等
特点：定义为抽象类，不会在数据库中创建对应的表
用途：被其他业务模型继承，实现字段复用
继承此基类的模型会自动拥有以下6个公共字段：
- id: 自增主键
- create_user: 创建人
- create_time: 创建时间
- update_user: 更新人
- update_time: 更新时间
- is_delete: 逻辑删除标识
注意：公共字段会自动排列在业务字段之后，使数据库表结构更清晰
"""
# ==================== 公共字段定义 ====================
# 主键ID字段
# 自增主键，每个模型的唯一标识符
id = models.AutoField(
auto_created=True,
primary_key=True,
serialize=False,
verbose_name='主键ID',
db_comment='主键ID'
auto_created=True, # 自动创建主键字段
primary_key=True, # 设置为主键
serialize=False, # 不参与序列化（避免在API响应中暴露）
verbose_name='主键ID', # 字段中文名称
db_comment='主键ID' # 数据库字段注释
)
# 创建人字段
# 记录数据由谁创建，通常关联用户表的用户名或ID
# 例如：admin, zhangsan, system
create_user = models.CharField(
null=True,
max_length=50,
default=None,
db_default=None,
verbose_name='创建人',
db_comment='创建人'
null=True, # 数据库允许为NULL
max_length=50, # 最大长度50个字符
default=None, # 默认值为None
db_default=None, # 数据库层默认值
verbose_name='创建人', # 字段中文名称
db_comment='创建人' # 数据库字段注释
)
# 创建时间字段
# 自动记录数据创建的时间戳
# auto_now_add: 仅在创建时自动设置当前时间，后续更新不会改变
create_time = models.DateTimeField(
null=True,
auto_now_add=True,
verbose_name="创建时间",
max_length=11,
db_comment='创建时间'
null=True, # 数据库允许为NULL
auto_now_add=True, # 创建时自动设为当前时间
verbose_name="创建时间", # 字段中文名称
max_length=11, # 时间戳长度
db_comment='创建时间' # 数据库字段注释
)
# 更新人字段
# 记录数据最后由谁更新，通常关联用户表的用户名或ID
# null=True: 允许数据库为NULL（新创建记录时可能没有更新人）
update_user = models.CharField(
null=True,
max_length=50,
default=None,
db_default=None,
verbose_name='更新人',
db_comment='更新人'
null=True, # 数据库允许为NULL
max_length=50, # 最大长度50个字符
default=None, # 默认值为None
db_default=None, # 数据库层默认值
verbose_name='更新人', # 字段中文名称
db_comment='更新人' # 数据库字段注释
)
# 更新时间字段
# 自动记录数据最后更新的时间戳
# auto_now: 每次保存（更新）时自动设为当前时间
update_time = models.DateTimeField(
null=True,
auto_now=True,
verbose_name="更新时间",
max_length=11,
db_comment='更新时间'
null=True, # 数据库允许为NULL
auto_now=True, # 每次保存时自动更新为当前时间
verbose_name="更新时间", # 字段中文名称
max_length=11, # 时间戳长度
db_comment='更新时间' # 数据库字段注释
)
# 逻辑删除标识
# 用于软删除，避免物理删除数据造成的数据丢失
# 0：正常（默认值）| 1：已删除
is_delete = models.BooleanField(
default=0,
db_default=0,
verbose_name="逻辑删除",
db_comment='逻辑删除：0-正常 1-已删除'
default=0, # 默认为0，表示正常
db_default=0, # 数据库层默认值
verbose_name="逻辑删除", # 字段中文名称
db_comment='逻辑删除：0-正常 1-已删除' # 数据库字段注释
)
class Meta:
abstract = True # 抽象模型，不创建数据库表
"""
元数据配置
"""
# 定义为抽象模型类
# abstract = True 表示这个模型是抽象的，不会在数据库中创建对应的表
# 子类模型会继承这些字段，并在各自对应的表中创建这些列
abstract = True
```
### 字段说明
DjangoAdmin_Django_NaiveVue/zh/volume3/cache.md
+1 -1
View File
@@ -65,7 +65,7 @@ REDIS_DB = int(os.getenv('REDIS_DB', 0))
|------|--------|------|
| `REDIS_HOST` | `127.0.0.1` | Redis服务器地址 |
| `REDIS_PORT` | `6379` | Redis端口 |
| `REDIS_PASSWORD` | `123456` | Redis密码 |
| `REDIS_PASSWORD` | `123456` | Redis密码（`.env` 中配置，无密码时留空） |
| `REDIS_DB` | `0` | Redis数据库索引（0-15） |
## 4.3 缓存应用场景
DjangoAdmin_Django_NaiveVue/zh/volume3/directory.md
+3 -3
View File
@@ -3,7 +3,7 @@
## 4.1 项目根目录
```
DjangoAdmin_Django_EleVue/
DjangoAdmin_Django_NaiveVue/
|
+-- application/ # Django后端应用主目录
+-- middleware/ # 自定义中间件
@@ -150,14 +150,14 @@ config/
```python
# 应用配置
DJANGO_NAME = os.getenv('DJANGO_NAME', 'Django+EleVue旗舰版')
DJANGO_NAME = os.getenv('DJANGO_NAME', 'Django+NaiveUI旗舰版')
DJANGO_VERSION = os.getenv('DJANGO_VERSION', 'v3.0.0')
DJANGO_DEBUG = (os.getenv('DJANGO_DEBUG', 'True') == 'True')
DJANGO_DEMO = (os.getenv('DJANGO_DEMO', 'True') == 'True')
# 数据库配置
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.naivevue')
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
DATABASE_PORT = os.getenv('DATABASE_PORT', 3306)
DATABASE_PREFIX = os.getenv('DATABASE_PREFIX', "django_")
DjangoAdmin_Django_NaiveVue/zh/volume3/extensibility.md
+2 -3
View File
@@ -162,7 +162,7 @@ public/templates/
### 4.4.2 模板语法示例
```jinja2
```jinja
{# models.py.tpl #}
from django.db import models
from application.models import BaseModel
@@ -294,7 +294,6 @@ python manage.py runserver # 启动开发服务器
python manage.py makemigrations <app> # 生成迁移文件
python manage.py migrate # 执行迁移
python manage.py createsuperuser # 创建超级用户
python manage.py add_full_comments # 回填数据库字段注释
```
## 4.8 前端扩展
@@ -310,7 +309,7 @@ VALUES ('案例管理', '/example', 'tool/example/index', 'sys:example:page', 0,
### 4.8.2 组件扩展
前端使用 Vue3 + ElementPlus，可通过以下方式扩展：
前端使用 Vue3 + NaiveUI，可通过以下方式扩展：
1. **自定义组件**：在 `ui/src/components/` 目录下创建新组件
2. **组合式函数**：在 `ui/src/hooks/` 目录下创建自定义 hooks
DjangoAdmin_Django_NaiveVue/zh/volume3/overview.md
+4 -4
View File
@@ -2,12 +2,12 @@
## 4.1 整体架构
项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + ElementPlus 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。
项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + NaiveUI 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。
### 架构图
```
浏览器 (Vue3 + ElementPlus)
浏览器 (Vue3 + NaiveUI)
|
v
Nginx (反向代理)
@@ -117,14 +117,14 @@ application/<module>/
| 缓存 | Redis | 6.0+ |
| 认证 | JWT (PyJWT) | - |
| 前端框架 | Vue3 | 3.x |
| UI组件库 | ElementPlus | - |
| UI组件库 | NaiveUI | - |
| 构建工具 | Vite | - |
| 状态管理 | Pinia | - |
## 4.7 目录结构
```
DjangoAdmin_Django_EleVue/
DjangoAdmin_Django_NaiveVue/
+-- application/ # Django后端应用
| +-- settings.py # 项目配置
| +-- urls.py # 主路由
DjangoAdmin_Django_NaiveVue/zh/volume3/performance.md
+3 -3
View File
@@ -192,8 +192,8 @@ const routes = [
### 组件按需导入
```typescript
// ElementPlus 按需导入
import { ElButton, ElTable, ElForm } from 'element-plus';
// NaiveUI 按需导入
import { NButton, NDataTable, NForm } from 'naive-ui';
```
### 图片懒加载
@@ -212,7 +212,7 @@ import(/* webpackChunkName: "editor" */ '@wangeditor/editor');
## Gunicorn Worker 配置
```ini
```bash
# gunicorn.conf.py
import multiprocessing
DjangoAdmin_Django_NaiveVue/zh/volume3/tech-stack.md
+4 -4
View File
@@ -49,7 +49,7 @@ CACHES = {
**配置说明**（`config/env.py`）：
```python
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.naivevue')
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
DATABASE_PORT = os.getenv('DATABASE_PORT', 3306)
DATABASE_USER = os.getenv('DATABASE_USER', 'root')
@@ -119,12 +119,12 @@ def parse_payload(token):
- TypeScript 提供类型安全，减少运行时错误
- 生态成熟，社区活跃
### ElementPlus
### NaiveUI
**选型理由**：
- 基于 Vue3 的企业级 UI 组件库
- 组件丰富，覆盖表单、表格、弹窗等常见场景
- 文档完善，中文社区支持好
- 文档完善，社区支持好
- 与 Vue3 深度集成
### Vite
@@ -197,7 +197,7 @@ jinja2
{
"dependencies": {
"vue": "^3.x",
"element-plus": "^2.x",
"naive-ui": "^2.x",
"pinia": "^2.x",
"vue-router": "^4.x",
"axios": "^1.x"
DjangoAdmin_Django_NaiveVue/zh/volume4/business/category.md
+14 -13
View File
@@ -145,16 +145,17 @@ def update_category(request):
### 树形选择组件
分类选择通常使用 el-tree-select 组件：
分类选择通常使用 n-tree-select 组件：
```vue
<template>
<el-tree-select
v-model="form.category_id"
:data="categoryTree"
:props="{ label: 'categoryName', value: 'id' }"
<n-tree-select
v-model:value="form.category_id"
:options="categoryTree"
label-field="categoryName"
key-field="id"
placeholder="请选择分类"
check-strictly
check-strategy="all"
/>
</template>
```
@@ -166,9 +167,9 @@ def update_category(request):
```vue
<template>
<BasicTable :data="categoryTree" row-key="id" default-expand-all>
<el-table-column prop="categoryName" label="分类名称" />
<el-table-column prop="categoryCode" label="分类编码" />
<el-table-column prop="sort" label="排序" />
<n-table-column title="分类名称" field="categoryName" />
<n-table-column title="分类编码" field="categoryCode" />
<n-table-column title="排序" field="sort" />
</BasicTable>
</template>
```
@@ -178,11 +179,11 @@ def update_category(request):
支持拖拽调整分类层级和顺序：
```vue
<el-tree
<n-tree
:data="categoryTree"
draggable
allow-drop="allowDrop"
@node-drop="handleDrop"
:allow-drop="allowDrop"
@drop="handleDrop"
/>
```
@@ -197,5 +198,5 @@ def update_category(request):
4. 排序控制：sort 字段控制分类显示顺序
5. 删除校验：删除前检查子级，保证数据完整性
6. 循环引用校验：更新时防止 A→B→C→A 死循环
7. 前端集成：el-tree-select、树形表格、拖拽排序
7. 前端集成：n-tree-select、树形表格、拖拽排序
```
DjangoAdmin_Django_NaiveVue/zh/volume4/business/city.md
+9 -5
View File
@@ -190,12 +190,16 @@ def delete_cities(city_ids):
## 前端级联选择
前端使用 `el-cascader` 组件实现省市区三级联动选择：
前端使用 `ChinaArea` 组件或 `n-cascader` 实现省市区三级联动选择：
```vue
<el-cascader
v-model="selectedRegion"
:props="cascaderProps"
<!-- 推荐使用项目内置的 ChinaArea 组件 -->
<ChinaArea v-model="formData.cityCode" :type="3" @change="handleCityChange" />
<!-- 或使用 NaiveUI 的 n-cascader -->
<n-cascader
v-model:value="selectedRegion"
:options="regionOptions"
placeholder="请选择省/市/区"
/>
@@ -237,7 +241,7 @@ python manage.py migrate
1. 五级行政区划：省/市/区/街道/社区，通过 parent_code 形成树形结构
2. 丰富字段：含经纬度、拼音、邮编等信息
3. 用户关联：用户表通过四级编码关联城市表
4. 级联选择：前端通过 el-cascader 组件实现级联选择
4. 级联选择：前端通过 ChinaArea 组件或 n-cascader 实现级联选择
5. 删除校验：删除前检查子级，保证数据完整性
6. 批量导入：内置全国行政区划数据
```
DjangoAdmin_Django_NaiveVue/zh/volume4/business/content.md
+1 -1
View File
@@ -209,7 +209,7 @@ application/notice/ application/link/
<BasicForm @register="registerSearch" />
<BasicTable @register="registerTable">
<template #tableTitle>
<el-button type="primary" @click="handleAdd">新增链接</el-button>
<n-button type="primary" @click="handleAdd">新增链接</n-button>
</template>
</BasicTable>
</PageWrapper>
DjangoAdmin_Django_NaiveVue/zh/volume4/core/config.md
+7 -9
View File
@@ -146,7 +146,7 @@ class ConfigWeb(BaseModel):
| 用途 | 枚举值（下拉选项） | 系统参数（配置值） |
| 值类型 | 简单值（字符串） | 可存储较长的配置内容 |
| 典型场景 | 状态、性别、类型 | SMTP配置、站点信息 |
| 前端用法 | el-select 选项 | 配置表单 |
| 前端用法 | n-select 选项 | 配置表单 |
| 缓存策略 | Redis 缓存 | 按需查询 |
| 数据量 | 通常每个字典 < 50 项 | 每个分组 < 20 项 |
@@ -158,18 +158,16 @@ class ConfigWeb(BaseModel):
```vue
<template>
<el-form-item :label="item.name">
<n-form-item :label="item.name">
<!-- 文本输入 -->
<el-input v-if="item.type === 'text'" v-model="item.value" />
<n-input v-if="item.type === 'text'" v-model:value="item.value" />
<!-- 数字输入 -->
<el-input-number v-else-if="item.type === 'number'" v-model="item.value" />
<n-input-number v-else-if="item.type === 'number'" v-model:value="item.value" />
<!-- 下拉选择 -->
<el-select v-else-if="item.type === 'select'" v-model="item.value">
<el-option v-for="opt in parseOptions(item.options)" :key="opt.value" :label="opt.label" :value="opt.value" />
</el-select>
<n-select v-else-if="item.type === 'select'" v-model:value="item.value" :options="parseOptions(item.options)" />
<!-- 开关 -->
<el-switch v-else-if="item.type === 'switch'" v-model="item.value" />
</el-form-item>
<n-switch v-else-if="item.type === 'switch'" v-model:value="item.value" />
</n-form-item>
</template>
```
DjangoAdmin_Django_NaiveVue/zh/volume4/core/dict-guide.md
+3 -10
View File
@@ -87,14 +87,7 @@ def _enrich_records(records):
```vue
<template>
<el-select v-model="form.trainingMethod" placeholder="请选择培训方式">
<el-option
v-for="item in dictOptions"
:key="item.value"
:label="item.label"
:value="item.value"
/>
</el-select>
<n-select v-model:value="form.trainingMethod" placeholder="请选择培训方式" :options="dictOptions" />
</template>
<script setup>
@@ -116,7 +109,7 @@ onMounted(async () => {
```typescript
import { h } from 'vue';
import { ElTag } from 'element-plus';
import { NTag } from 'naive-ui';
export const columns = [
{
@@ -125,7 +118,7 @@ export const columns = [
render(record) {
const map = { 1: '线上', 2: '线下', 3: '混合' };
const typeMap = { 1: 'success', 2: 'warning', 3: 'info' };
return h(ElTag, { type: typeMap[record.row.trainingMethod] }, {
return h(NTag, { type: typeMap[record.row.trainingMethod] }, {
default: () => map[record.row.trainingMethod] || '-'
});
},
DjangoAdmin_Django_NaiveVue/zh/volume4/core/dict.md
+6 -13
View File
@@ -105,19 +105,12 @@ const statusOptions = dictStore.getDict('sys_status')
```vue
<template>
<!-- el-select 下拉选择 -->
<el-select v-model="form.status" placeholder="请选择状态">
<el-option
v-for="item in statusOptions"
:key="item.value"
:label="item.label"
:value="item.value"
/>
</el-select>
<!-- n-select 下拉选择 -->
<n-select v-model:value="form.status" placeholder="请选择状态" :options="statusOptions" />
<!-- el-tag 标签展示 -->
<el-tag v-if="form.status === '1'">正常</el-tag>
<el-tag v-else type="danger">停用</el-tag>
<!-- n-tag 标签展示 -->
<n-tag v-if="form.status === '1'">正常</n-tag>
<n-tag v-else type="error">停用</n-tag>
</template>
```
@@ -174,7 +167,7 @@ export const useDictStore = defineStore('dict', {
```
1. 两级结构：字典类型（分组）+ 字典项（具体值），清晰管理
2. 前端集成：useDictStore 统一管理，el-select 直接绑定
2. 前端集成：useDictStore 统一管理，n-select 直接绑定
3. 值为字符串：字典项 value 统一为字符串类型
4. 避免硬编码：枚举值统一走字典，修改无需改代码
5. Redis 缓存：减少数据库查询，提升性能
DjangoAdmin_Django_NaiveVue/zh/volume4/core/idempotent.md
+3 -3
View File
@@ -37,16 +37,16 @@ function useLockFn(fn) {
### 按钮 loading
ElementPlus 的按钮组件支持 `loading` 属性，请求期间禁用按钮：
NaiveUI 的按钮组件支持 `loading` 属性，请求期间禁用按钮：
```vue
<el-button
<n-button
type="primary"
:loading="submitting"
@click="handleSubmit"
>
提交
</el-button>
</n-button>
<script setup>
const submitting = ref(false)
DjangoAdmin_Django_NaiveVue/zh/volume4/core/rbac.md
+2 -2
View File
@@ -119,10 +119,10 @@ def get_user_permissions(user_id):
```html
<!-- 只有拥有 sys:user:add 权限的用户才能看到此按钮 -->
<el-button v-perm="'sys:user:add'" type="primary">新增</el-button>
<n-button v-perm="'sys:user:add'" type="primary">新增</n-button>
<!-- 多个权限，满足其一即可 -->
<el-button v-perm="['sys:user:update', 'sys:user:delete']">操作</el-button>
<n-button v-perm="['sys:user:update', 'sys:user:delete']">操作</n-button>
```
### 路由守卫
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/build.md
+12 -17
View File
@@ -68,8 +68,8 @@ Vite 按 mode 加载环境变量，后面的文件覆盖前面的：
|------|------|--------|------|
| `VITE_PORT` | `number` | `8001` | 开发服务器端口 |
| `VITE_PUBLIC_PATH` | `string` | `/` | 部署基础路径（子目录部署时修改） |
| `VITE_GLOB_APP_TITLE` | `string` | `Django+ElementPlus版` | 应用标题（注入 HTML） |
| `VITE_GLOB_APP_SHORT_NAME` | `string` | `Django+ElementPlus版` | 应用短名（用于生成运行时配置变量名） |
| `VITE_GLOB_APP_TITLE` | `string` | `Django+NaiveUI版` | 应用标题（注入 HTML） |
| `VITE_GLOB_APP_SHORT_NAME` | `string` | `Django+NaiveUI版` | 应用短名（用于生成运行时配置变量名） |
| `VITE_GLOB_API_URL` | `string` | 空 | API 基础路径（留空使用相对路径） |
| `VITE_GLOB_API_URL_PREFIX` | `string` | `/api` | API 前缀 |
| `VITE_GLOB_FILE_URL` | `string` | - | 文件访问域名（拼接上传文件 URL） |
@@ -177,7 +177,7 @@ import { defineStore } from 'pinia'; // 自动
```html
<!-- 构建后的 index.html -->
<title>Django+ElementPlus版</title>
<title>Django+NaiveUI版</title>
<script src="/app.config.js?v=1.0.0-1725000000000"></script>
```
@@ -191,8 +191,8 @@ import { defineStore } from 'pinia'; // 自动
window.__{SHORT_NAME}__PRODUCTION__CONF__ = {
"VITE_GLOB_API_URL": "",
"VITE_GLOB_API_URL_PREFIX": "/api",
"VITE_GLOB_FILE_URL": "http://file.django.elevue",
"VITE_GLOB_APP_TITLE": "Django+ElementPlus版",
"VITE_GLOB_FILE_URL": "http://file.django.naivevue",
"VITE_GLOB_APP_TITLE": "Django+NaiveUI版",
// ...
};
Object.freeze(window.__{SHORT_NAME}__PRODUCTION__CONF__);
@@ -256,7 +256,7 @@ dist/
├── app.config.js # 运行时配置（VITE_GLOB_* 变量）
├── favicon.ico # 网站图标
└── assets/
├── index-[hash].js # 主包（Vue、ElementPlus、Pinia 等）
├── index-[hash].js # 主包（Vue、NaiveUI、Pinia 等）
├── index-[hash].css # 全局样式
├── [name]-[hash].js # 路由懒加载 chunk（按视图分割）
└── ... # 字体、图片等静态资源
@@ -283,7 +283,7 @@ Vite 自动将 `node_modules` 中的库分割为独立 chunk：
| chunk | 内容 |
|-------|------|
| `vendor-vue.js` | vue + vue-router + pinia |
| `vendor-element.js` | element-plus |
| `vendor-naive.js` | naive-ui |
| `vendor-echarts.js` | echarts（如果使用） |
| `vendor-*.js` | 其他大型依赖 |
@@ -293,7 +293,7 @@ Vite 自动将 `node_modules` 中的库分割为独立 chunk：
```typescript
optimizeDeps: {
include: ['dayjs', '@vicons/ionicons5', '@vicons/antd', '@element-plus/icons-vue'],
include: ['dayjs', '@vicons/ionicons5', '@vicons/antd'],
}
```
@@ -307,13 +307,8 @@ optimizeDeps: {
async function bootstrap() {
const app = createApp(App);
// 1. 全局注册 ElementPlus 图标
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
app.component(key, component);
}
// 2. 全局引入 ElementPlus（中文包）
setupElement(app);
// 1. 全局引入 NaiveUI（中文包）
setupNaive(app);
// 3. 全局注册自定义组件（BasicTable、BasicForm 等）
setupCustomComponents(app);
@@ -339,7 +334,7 @@ async function bootstrap() {
| 注册项 | 文件 | 说明 |
|--------|------|------|
| ElementPlus | `element.ts` | 全局引入 + 中文包 |
| NaiveUI | `naive.ts` | 全局引入 + 中文包 |
| 自定义组件 | `customComponents.ts` | BasicTable、BasicForm、PageWrapper 等 |
| 自定义指令 | `directives.ts` | `v-perm`、`v-perms`、`v-scrollBar` |
@@ -504,7 +499,7 @@ pnpm report
**优化手段**：
1. 路由懒加载（已默认启用）
2. 按需引入 ElementPlus 组件（当前为全量引入）
2. 按需引入 NaiveUI 组件（当前为全量引入）
3. 大型依赖（echarts、wangeditor）按需引入
4. 开启 gzip 压缩（`VITE_BUILD_COMPRESS=gzip`）
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/components.md
+80 -56
View File
@@ -3,7 +3,7 @@
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
:::tip 说明
项目提供丰富的公共组件，位于 `ui/src/components/` 目录，基于 ElementPlus 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。组件通过 `src/plugins/` 中的 `setupCustomComponents` 全局注册，任何页面直接使用，无需单独 import。
项目提供丰富的公共组件，位于 `ui/src/components/` 目录，基于 NaiveUI 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。组件通过 `src/plugins/` 中的 `setupCustomComponents` 全局注册，任何页面直接使用，无需单独 import。
:::
## 组件总览
@@ -19,7 +19,7 @@
| CropperImage | `components/Cropper/` | 图片裁剪（圆形/矩形、实时预览） |
| QrCode | `components/Qrcode/` | 二维码生成（canvas/img、内嵌 logo） |
| ChinaArea | `components/ChinaArea/` | 省市区级联（懒加载、二/三级联动） |
| Icon | `components/icon/` | 图标（支持 ElementPlus 图标 + SVG 图标） |
| Icon | `components/icon/` | 图标（支持 @vicons/antd 图标 + SVG 图标） |
| BasicSelect | `components/Select/` | 增强下拉（远程请求、本地缓存） |
| CountTo | `components/CountTo/` | 数字动画（前缀/后缀、千分位、缓动曲线） |
| Password | `components/Password/` | 密码强度（强度指示器、重复确认、复杂度校验） |
@@ -40,7 +40,7 @@
## BasicTable 表格
表格组件是使用频率最高的组件，基于 `el-table` + `el-pagination` 封装，详见 [BasicTable 表格](/zh/volume4/frontend/table) 章节。
表格组件是使用频率最高的组件，基于 NaiveUI 的 `n-data-table` 封装，详见 [BasicTable 表格](/zh/volume4/frontend/table) 章节。
### Props
@@ -79,8 +79,8 @@
| 属性 | 类型 | 说明 |
|------|------|------|
| `label` | `string` | 列标题 |
| `prop` | `string` | 字段名 |
| `title` | `string` | 列标题 |
| `key` | `string` | 字段名 |
| `width` | `number` | 列宽 |
| `align` | `string` | 对齐方式 |
| `type` | `string` | 类型：`index` / `selection` |
@@ -96,7 +96,7 @@
|------|------|------|
| `fetch-success` | `(data, result)` | 数据请求成功 |
| `fetch-error` | `(error)` | 数据请求失败 |
| `selection-change` | `(rows)` | 多选变化 |
| `update:checked-row-keys` | `(keys)` | 多选变化 |
| `columns-change` | `(columns)` | 列设置变化 |
| `checked-row-change` | `(rowKeys)` | 选中行变化 |
@@ -129,39 +129,59 @@
```vue
<template>
<BasicTable :columns="columns" :request="loadDataTable" ref="tableRef">
<BasicTable :columns="columns" :request="loadDataTable" ref="basicTableRef" :actionColumn="actionColumn">
<template #tableTitle>
<el-button v-perm="['sys:level:add']" type="primary" @click="handleAdd">
<el-icon><Plus /></el-icon>新增
</el-button>
<n-space>
<n-button v-perm="['sys:level:add']" type="primary" @click="handleAdd">
<template #icon><n-icon><PlusOutlined /></n-icon></template>
新增
</n-button>
</n-space>
</template>
</BasicTable>
</template>
<script setup lang="ts">
import { h, reactive, ref } from 'vue';
import { NTag } from 'naive-ui';
import { PlusOutlined, FormOutlined, DeleteOutlined } from '@vicons/antd';
import { TableAction } from '@/components/Table';
import { renderIcon } from '@/utils';
const basicTableRef = ref();
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,
render(record) {
return h(NTag, { bordered: false, type: record.status == 1 ? 'success' : 'error' },
{ default: () => record.status == 1 ? '正常' : '停用' });
},
},
{ title: '创建时间', key: 'createTime', width: 180 },
];
const actionColumn = {
const actionColumn = reactive({
width: 200,
actions: [
{ label: '编辑', auth: ['sys:level:update'], onClick: handleEdit },
{
label: '删除',
auth: ['sys:level:delete'],
isConfirm: true,
popConfirm: { title: '确认删除？' },
onClick: handleDelete,
},
],
};
title: '操作',
align: 'center',
key: 'action',
fixed: 'right',
render(record) {
return h(TableAction as any, {
style: 'button',
actions: [
{ label: '编辑', icon: renderIcon(FormOutlined), type: 'info', onClick: handleEdit.bind(null, record), auth: ['sys:level:update'] },
{ label: '删除', icon: renderIcon(DeleteOutlined), type: 'error', onClick: handleDelete.bind(null, record), auth: ['sys:level:delete'] },
],
});
},
});
async function loadDataTable({ page, pageSize }) {
const res = await getListApi({ pageNo: page, pageSize });
return { items: res.data, total: res.count };
async function loadDataTable(params) {
const result = await getListApi(params);
return result;
}
</script>
```
@@ -230,13 +250,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` | 栅格配置（如 `{ cols: '1 s:1 m:2 l:3' }`） |
| `labelMessage` | `string` | 标签提示信息 |
| `suffix` | `string` | 后缀文字 |
@@ -268,17 +288,19 @@ async function loadDataTable({ page, pageSize }) {
<script setup lang="ts">
const [registerForm] = useForm({
gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
labelWidth: 80,
schemas: [
{
field: 'name',
label: '名称',
component: 'Input',
component: 'NInput',
componentProps: { placeholder: '请输入名称' },
},
{
field: 'status',
label: '状态',
component: 'Select',
component: 'NSelect',
componentProps: {
options: [
{ label: '启用', value: 1 },
@@ -286,12 +308,6 @@ const [registerForm] = useForm({
],
},
},
{
field: 'dateRange',
label: '日期范围',
component: 'DatePicker',
componentProps: { type: 'daterange' },
},
],
});
</script>
@@ -301,7 +317,7 @@ const [registerForm] = useForm({
## BasicModal 弹窗
弹窗组件基于 `el-dialog` 封装，支持拖拽、自定义按钮，详见 [Modal 弹窗](/zh/volume4/frontend/modal) 章节。
弹窗组件基于 NaiveUI 封装，支持拖拽、自定义按钮，详见 [Modal 弹窗](/zh/volume4/frontend/modal) 章节。
### Props
@@ -335,21 +351,29 @@ const [registerForm] = useForm({
```vue
<template>
<BasicModal title="编辑用户" :width="600" @register="registerModal" @ok="handleSubmit">
<BasicForm @register="registerForm" />
</BasicModal>
<basicModal @register="modalRegister" ref="modalRef" class="basicModal basicFormModal" @on-ok="handleSubmit">
<template #default>
<n-form ref="formRef" :model="formData" label-placement="left" label-width="85px">
<n-form-item label="用户名" path="name" :rule="{ required: true, message: '请输入用户名', trigger: 'blur' }">
<n-input v-model:value="formData.name" placeholder="请输入用户名" />
</n-form-item>
</n-form>
</template>
</basicModal>
</template>
<script setup lang="ts">
const [registerModal, { openModal, closeModal, setModalProps }] = useModal();
import { useModal } from '@/components/Modal';
const [modalRegister, { openModal, closeModal, setSubLoading }] = useModal({
title: '编辑用户',
subBtuText: '确定',
width: 600,
});
function handleEdit(record) {
setModalProps({ title: '编辑用户' });
openModal();
// 回填表单数据
nextTick(() => {
setFieldsValue(record);
});
}
</script>
```
@@ -358,7 +382,7 @@ function handleEdit(record) {
## BasicUpload 上传
文件/图片上传组件，基于 `el-upload` 封装，支持卡片/列表模式、数量限制、图片预览。
文件/图片上传组件，基于 NaiveUI 封装，支持卡片/列表模式、数量限制、图片预览。
### Props
@@ -700,10 +724,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>
@@ -726,7 +750,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>
```
@@ -734,7 +758,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>
```
:::
@@ -742,7 +766,7 @@ async function getDeptOptions() {
## Icon 图标
统一图标组件，支持 ElementPlus 图标和 SVG 图标。
统一图标组件，支持 @vicons/antd 图标和 SVG 图标。
### Props
@@ -756,8 +780,8 @@ async function getDeptOptions() {
```vue
<template>
<!-- ElementPlus 图标 -->
<Icon name="el-icon-Plus" size="18px" />
<!-- @vicons/antd 图标 -->
<n-icon :component="PlusOutlined" size="18" />
<!-- SVG 图标 -->
<Icon name="svg-icon-user" />
</template>
@@ -838,4 +862,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。优先使用公共组件，避免重复开发。
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/form.md
+234 -70
View File
@@ -3,7 +3,7 @@
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
:::tip 说明
`BasicForm` 位于 `src/components/Form/src/BasicForm.vue`，基于 ElementPlus 的 `el-form` 二次封装，通过 schemas 配置化定义表单字段，支持查询表单和业务表单两种模式。
`BasicForm` 位于 `src/components/Form/src/BasicForm.vue`，基于 NaiveUI 的 `n-form` 二次封装，通过 schemas 配置化定义表单字段，支持查询表单和业务表单两种模式。
:::
## 组件架构
@@ -26,9 +26,9 @@ src/components/Form/
列表页的搜索区域使用 `useForm` 注册表单：
```vue
<el-card :bordered="false" class="pt-3 mb-3 proCard">
<n-card :bordered="false" class="pt-3 mb-3 proCard">
<BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
</el-card>
</n-card>
```
### querySchemas 定义
@@ -41,7 +41,7 @@ import { FormSchema } from '@/components/Form/index';
export const schemas: FormSchema[] = [
{
field: 'name',
component: 'Input',
component: 'NInput',
label: '岗位名称',
componentProps: {
placeholder: '请输入岗位名称',
@@ -49,14 +49,14 @@ export const schemas: FormSchema[] = [
},
{
field: 'status',
component: 'Select',
component: 'NSelect',
label: '状态',
componentProps: {
placeholder: '请选择状态',
clearable: true,
options: [
{ label: '正常', value: '1' },
{ label: '禁用', value: '2' },
{ label: '停用', value: '2' },
],
},
},
@@ -68,26 +68,25 @@ export const schemas: FormSchema[] = [
```typescript
import { schemas } from './querySchemas';
import { useForm } from '@/components/Form/index';
import { ColProps } from 'element-plus';
const formParams = reactive({ name: '', status: '' });
const [register, {}] = useForm({
gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
labelWidth: 80,
layout: 'horizontal',
colProps: { span: 6 } as ColProps,
submitOnReset: true,
schemas,
});
function handleSubmit(values: Recordable) {
handleReset();
for (const key in formParams) { formParams[key] = ''; }
for (const key in values) { formParams[key] = values[key]; }
reloadTable();
}
function handleReset() {
function handleReset(values: Recordable) {
for (const key in formParams) { formParams[key] = ''; }
for (const key in values) { formParams[key] = values[key]; }
reloadTable();
}
```
@@ -95,73 +94,173 @@ function handleReset() {
## 业务表单（编辑弹窗）
编辑弹窗中直接使用 `el-form` + `el-form-item` 构建表单：
编辑弹窗使用 `basicModal` + `useModal` + `n-form` 构建表单：
```vue
<!-- src/views/system/position/edit.vue -->
<template>
<el-dialog v-model="props.visible" :title="props.positionId ? '编辑' : '新增'" width="500">
<el-form class="ls-form" ref="formRef" :model="formData" label-width="80px">
<el-form-item
label="岗位名称"
prop="name"
:rules="{ required: true, message: '请输入岗位名称', trigger: 'blur' }"
<basicModal
@register="modalRegister"
ref="modalRef"
class="basicModal basicFormModal"
@on-ok="handleSubmit"
@on-close="handleClose"
>
<template #default>
<n-form
class="ls-form"
ref="formRef"
:model="formData"
label-placement="left"
label-width="85px"
>
<el-input v-model="formData.name" placeholder="请输入岗位名称" clearable />
</el-form-item>
<el-form-item label="岗位状态" prop="status">
<el-radio-group v-model="formData.status">
<el-radio :value="1">正常</el-radio>
<el-radio :value="2">停用</el-radio>
</el-radio-group>
</el-form-item>
<el-form-item label="排序" prop="sort">
<el-input-number v-model="formData.sort" />
</el-form-item>
</el-form>
</el-dialog>
<n-form-item
label="岗位名称"
path="name"
:rule="{ required: true, message: '请输入岗位名称', trigger: 'blur' }"
>
<n-input v-model:value="formData.name" placeholder="请输入岗位名称" clearable />
</n-form-item>
<n-form-item label="岗位状态" path="status">
<n-radio-group v-model:value="formData.status" name="status">
<n-radio :value="1">正常</n-radio>
<n-radio :value="2">停用</n-radio>
</n-radio-group>
</n-form-item>
<n-form-item label="排序" path="sort">
<n-input-number v-model:value="formData.sort" />
</n-form-item>
</n-form>
</template>
</basicModal>
</template>
```
### useModal 注册
```typescript
import { useModal } from '@/components/Modal';
const [modalRegister, { openModal, setSubLoading }] = useModal({
title: props.positionId ? '编辑岗位' : '添加岗位',
subBtuText: '确定',
width: 600,
});
```
### 完整 script 示例
```typescript
import { getPositionDetail, positionAdd, positionUpdate } from '@/api/system/position';
import { onMounted, reactive, ref } from 'vue';
import { useMessage } from 'naive-ui';
import { useModal } from '@/components/Modal';
const emit = defineEmits(['success', 'update:visible']);
const formRef = ref();
const message = useMessage();
const formData = reactive({
id: '',
name: '',
status: 1,
sort: 0,
});
const props = defineProps({
visible: { type: Boolean, required: true, default: false },
positionId: { type: Number, required: true, default: 0 },
});
const [modalRegister, { openModal, setSubLoading }] = useModal({
title: props.positionId ? '编辑岗位' : '添加岗位',
subBtuText: '确定',
width: 600,
});
const handleSubmit = async () => {
formRef.value
.validate()
.then(async () => {
props.positionId ? await positionUpdate(formData) : await positionAdd(formData);
message.success('操作成功');
setSubLoading(false);
emit('update:visible', false);
emit('success');
})
.catch(() => {
setSubLoading(false);
});
};
const handleClose = () => {
emit('update:visible', false);
};
const setFormData = async () => {
const data = await getPositionDetail(props.positionId);
for (const key in formData) {
if (data[key] != null && data[key] != undefined) {
formData[key] = data[key];
}
}
};
onMounted(() => {
if (props.positionId) setFormData();
});
defineExpose({ openModal });
```
## BasicForm 内部渲染机制
`BasicForm.vue` 根据 `schema.component` 动态渲染对应的 ElementPlus 组件：
`BasicForm.vue` 根据 `schema.component` 动态渲染对应的 NaiveUI 组件：
```vue
<!-- src/components/Form/src/BasicForm.vue 核心逻辑 -->
<template v-for="schema in getSchema" :key="schema.field">
<!-- Checkbox -->
<template v-if="schema.component === 'Checkbox'">
<el-checkbox-group v-model="formModel[schema.field]">
<el-checkbox v-for="item in schema.componentProps?.options" :value="item.value">
{{ item.label }}
</el-checkbox>
</el-checkbox-group>
<!-- NCheckbox -->
<template v-if="schema.component === 'NCheckbox'">
<n-checkbox-group v-model:value="formModel[schema.field]">
<n-space>
<n-checkbox
v-for="item in schema.componentProps?.options"
:value="item.value"
:label="item.label"
/>
</n-space>
</n-checkbox-group>
</template>
<!-- RadioGroup -->
<template v-else-if="schema.component === 'RadioGroup'">
<el-radio-group v-model="formModel[schema.field]">
<el-radio v-for="item in schema.componentProps?.options" :value="item.value">
{{ item.label }}
</el-radio>
</el-radio-group>
<!-- NRadioGroup -->
<template v-else-if="schema.component === 'NRadioGroup'">
<n-radio-group v-model:value="formModel[schema.field]">
<n-space>
<n-radio v-for="item in schema.componentProps?.options" :value="item.value">
{{ item.label }}
</n-radio>
</n-space>
</n-radio-group>
</template>
<!-- Select -->
<template v-else-if="schema.component === 'Select'">
<el-select v-model="formModel[schema.field]">
<el-option v-for="item in schema.componentProps?.options" :value="item.value" :label="item.label" />
</el-select>
<!-- NDatePicker（带 valueFormat） -->
<template v-else-if="schema.component === 'NDatePicker' && schema.componentProps?.valueFormat">
<n-date-picker
v-model:formatted-value="formModel[schema.field]"
v-bind="schema.componentProps"
clearable
/>
</template>
<!-- Daterange -->
<template v-else-if="schema.component === 'Daterange'">
<el-date-picker v-model="formModel[schema.field]" type="daterange" value-format="YYYY-MM-DD" />
</template>
<!-- 其他组件：动态渲染 el-{component} -->
<component v-else :is="`el-${schema.component}`" v-model="formModel[schema.field]" />
<!-- 动态渲染表单组件 -->
<component
v-else
v-bind="getComponentProps(schema)"
:is="schema.component"
:type="schema.type"
v-model:value="formModel[schema.field]"
/>
</template>
```
@@ -170,11 +269,10 @@ function handleReset() {
```typescript
interface FormSchema {
field: string; // 字段名
label: string; // 标签文本
component: string; // 组件类型：Input / Select / RadioGroup / Checkbox / DatePicker 等
label?: string; // 标签文本
component?: ComponentType; // 组件类型：NInput / NSelect / NRadioGroup / NCheckbox / NDatePicker 等
componentProps?: any; // 组件属性（placeholder、options、clearable 等）
required?: boolean; // 是否必填
rules?: any[]; // 自定义校验规则
rules?: object | object[]; // 自定义校验规则
defaultValue?: any; // 默认值
hidden?: boolean | (({ schema, values, model }) => boolean); // 是否隐藏
slot?: string; // 自定义插槽名
@@ -182,6 +280,9 @@ interface FormSchema {
labelMessage?: string; // 标签提示信息
isFull?: boolean; // 是否全宽
type?: string; // 组件子类型
giProps?: GridItemProps; // 栅格子项属性
showFeedback?: boolean; // 是否显示反馈
labelWidth?: number | string; // 标签宽度
}
```
@@ -190,8 +291,14 @@ interface FormSchema {
```typescript
// 手动校验
const handleSubmit = async () => {
await formRef.value?.validate();
// 校验通过，提交数据
formRef.value
.validate()
.then(async () => {
// 校验通过，提交数据
})
.catch(() => {
// 校验失败
});
};
// 清除校验
@@ -203,15 +310,27 @@ Schema 中的 `required: true` 会自动生成必填校验规则，也可以通
```typescript
{
field: 'name',
label: '岗位名称',
component: 'Input',
label: '案例名称',
component: 'NInput',
rules: [
{ required: true, message: '请输入岗位名称', trigger: 'blur' },
{ required: true, message: '请输入案例名称', trigger: 'blur' },
{ min: 1, max: 150, message: '长度在 1 到 150 个字符', trigger: 'blur' },
],
}
```
在模板中使用 `n-form-item` 的 `rule` 属性也可以直接定义校验规则：
```vue
<n-form-item
label="案例名称"
path="name"
:rule="{ required: true, message: '请输入案例名称', trigger: 'blur' }"
>
<n-input v-model:value="formData.name" placeholder="请输入案例名称" clearable />
</n-form-item>
```
## 表单赋值
编辑时需要将行数据赋值给表单：
@@ -233,10 +352,55 @@ onMounted(() => {
});
```
## n-select 用法
NaiveUI 的 `n-select` 使用 `:options` 传递选项数据，无需嵌套 `el-option`：
```vue
<n-select
v-model:value="formData.type"
placeholder="请选择案例类型"
clearable
filterable
:options="optionsData.typeList"
/>
```
选项数据格式：
```typescript
const optionsData = reactive({
typeList: [
{ label: '类型1', value: 1 },
{ label: '类型2', value: 2 },
{ label: '类型3', value: 3 },
{ label: '类型4', value: 4 },
],
});
```
## 查询表单完整示例（带响应式栅格）
```typescript
const [register, {}] = useForm({
gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
labelWidth: 80,
schemas,
});
```
`gridProps` 使用 NaiveUI 的响应式栅格断点：
- `1` — 默认每行 1 列
- `s:1` — 小屏 1 列
- `m:2` — 中屏 2 列
- `l:3` — 大屏 3 列
- `xl:4` — 超大屏 4 列
- `2xl:4` — 超超大屏 4 列
:::tip 温馨提示
查询表单的字段名需要与后端 `page_like_fields` 和 `page_eq_fields` 对应，确保查询参数能正确传递到后端。`useForm` 返回的 `register` 函数传给 `@register` 事件完成表单绑定，`formActionType` 提供 `setFieldsValue`、`resetFields`、`validate` 等方法。
查询表单的字段名需要与后端 `page_like_fields` 和 `page_eq_fields` 对应，确保查询参数能正确传递到后端。`useForm` 返回的 `register` 函数传给 `@register` 事件完成表单绑定，`formActionType` 提供 `setFieldsValue`、`resetFields`、`validate` 等方法。业务弹窗使用 `basicModal` + `useModal` 管理弹窗状态，通过 `@on-ok` 事件处理提交，通过 `setSubLoading(false)` 关闭提交按钮的 loading 状态。
:::
## 总结
BasicForm 通过 schemas 配置化定义表单字段，内部根据 `component` 动态渲染对应的 ElementPlus 组件。查询表单使用 `useForm` 注册并绑定 `@submit`/`@reset` 事件，业务表单直接使用 `el-form` + `reactive` 管理数据。支持多种组件类型、表单校验、数据绑定、条件隐藏等能力。
BasicForm 通过 schemas 配置化定义表单字段，内部根据 `component` 动态渲染对应的 NaiveUI 组件（`NInput`、`NSelect`、`NRadioGroup`、`NCheckbox`、`NDatePicker` 等）。查询表单使用 `useForm` 注册并绑定 `@submit`/`@reset` 事件，业务表单使用 `basicModal` + `useModal` + `n-form` + `reactive` 管理数据。NaiveUI 的表单组件统一使用 `v-model:value` 进行双向绑定，`n-form-item` 使用 `path` 代替 `prop` 指定校验字段，使用 `rule` 代替 `rules` 指定校验规则。支持多种组件类型、表单校验、数据绑定、条件隐藏、响应式栅格等能力。
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/hooks.md
+1 -1
View File
@@ -132,7 +132,7 @@ const { isLock: subLoading, lockFn: submit } = useLockFn(handleSubmit);
```
```vue
<el-button :loading="subLoading" type="primary" @click="submit">确定</el-button>
<n-button :loading="subLoading" type="primary" @click="submit">确定</n-button>
```
## useAsync
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/i18n.md
+33 -26
View File
@@ -3,38 +3,42 @@
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
:::tip 说明
当前项目仅支持中文界面，ElementPlus 使用中文语言包（`zh-cn`），所有界面文本直接硬编码在组件中。如需扩展多语言支持，可基于 vue-i18n 实现。
当前项目仅支持中文界面，NaiveUI 使用中文语言包（`zhCN`），所有界面文本直接硬编码在组件中。如需扩展多语言支持，可基于 vue-i18n 实现。
:::
## 当前状态
项目当前为中文单语言版本：
- ElementPlus 全局配置中文语言包：`app.use(ElementPlus, { locale: zhCn })`
- 所有界面文本直接硬编码在组件中：`<el-button>添加岗位</el-button>`
- NaiveUI 通过 ConfigProvider 配置中文语言包：`<n-config-provider :locale="zhCN" :date-locale="dateZhCN">`
- 所有界面文本直接硬编码在组件中：`<n-button>添加岗位</n-button>`
- 后端返回的 `msg` 字段为中文：`"操作成功"`、`"岗位名称不能重复"`
```vue
<template>
<el-button type="primary">添加岗位</el-button>
<el-table-column label="岗位名称" prop="name" />
<el-table-column label="创建时间" prop="createTime" />
<n-button type="primary">添加岗位</n-button>
<!-- 表格列通过 columns.ts 配置，使用 title/key -->
</template>
```
## ElementPlus 中文配置
## NaiveUI 中文配置
项目在入口文件中全局配置 ElementPlus 中文语言包：
项目通过 NaiveUI 的 ConfigProvider 配置中文语言包：
```typescript
// main.ts
import ElementPlus from 'element-plus';
import zhCn from 'element-plus/es/locale/lang/zh-cn';
app.use(ElementPlus, { locale: zhCn });
// App.vue 或入口组件
import { zhCN, dateZhCN } from 'naive-ui';
```
配置后，ElementPlus 组件的默认文本（如分页、日期选择器、表格空数据等）自动显示中文。
```vue
<template>
<n-config-provider :locale="zhCN" :date-locale="dateZhCN">
<App />
</n-config-provider>
</template>
```
配置后，NaiveUI 组件的默认文本（如分页、日期选择器、表格空数据等）自动显示中文。
## 扩展方案
@@ -126,8 +130,8 @@ export default i18n;
```vue
<template>
<el-button type="primary">{{ $t('common.add') }}</el-button>
<el-table-column :label="$t('position.name')" prop="name" />
<n-button type="primary">{{ $t('common.add') }}</n-button>
<!-- 表格列通过 columns.ts 配置，使用 title/key -->
</template>
<script setup>
@@ -136,23 +140,26 @@ const { t } = useI18n();
</script>
```
### ElementPlus 国际化联动
### NaiveUI 国际化联动
```typescript
// 动态切换 ElementPlus 语言
import zhCn from 'element-plus/es/locale/lang/zh-cn';
import en from 'element-plus/es/locale/lang/en';
// 动态切换 NaiveUI 语言
import { zhCN, dateZhCN, enUS, dateEnUS } from 'naive-ui';
const locale = computed(() => {
return i18n.global.locale.value === 'zh-CN' ? zhCn : en;
return i18n.global.locale.value === 'zh-CN' ? zhCN : enUS;
});
const dateLocale = computed(() => {
return i18n.global.locale.value === 'zh-CN' ? dateZhCN : dateEnUS;
});
```
```vue
<template>
<el-config-provider :locale="locale">
<n-config-provider :locale="locale" :date-locale="dateLocale">
<App />
</el-config-provider>
</n-config-provider>
</template>
```
@@ -163,7 +170,7 @@ const locale = computed(() => {
function changeLanguage(lang: string) {
i18n.global.locale.value = lang;
localStorage.setItem('lang', lang);
// 同步切换 ElementPlus 语言
// 同步切换 NaiveUI 语言
}
```
@@ -206,7 +213,7 @@ const errorMap = {
```
:::warning 注意事项
1. ElementPlus 内置组件的文本（如"暂无数据"、"请选择"）通过 `locale` 属性自动切换
1. NaiveUI 内置组件的文本（如"暂无数据"、"请选择"）通过 `locale` 属性自动切换
2. 后端返回的 `msg` 字段需要额外处理
3. 日期格式、数字格式也需要考虑国际化
:::
@@ -227,4 +234,4 @@ const errorMap = {
## 总结
当前项目为中文单语言版本，ElementPlus 使用中文语言包。如需扩展多语言支持，可基于 vue-i18n 实现前端国际化，配合 ElementPlus 内置语言包和后端消息 code 实现全链路多语言。改造需考虑前端文本、ElementPlus 组件、后端消息三个维度的国际化。
当前项目为中文单语言版本，NaiveUI 使用中文语言包。如需扩展多语言支持，可基于 vue-i18n 实现前端国际化，配合 NaiveUI 内置语言包和后端消息 code 实现全链路多语言。改造需考虑前端文本、NaiveUI 组件、后端消息三个维度的国际化。
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/modal.md
+135 -84
View File
@@ -3,7 +3,7 @@
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
:::tip 说明
项目提供 `BasicModal` 组件（`src/components/Modal/src/BasicModal.vue`）和原生 `el-dialog` 两种弹窗用法。编辑弹窗通过 `defineAsyncComponent` 懒加载，减少首屏渲染负担。
项目使用 `basicModal` 组件（`src/components/Modal/src/BasicModal.vue`）配合 `useModal` hook 实现弹窗。编辑弹窗通过 `v-if` 懒加载，减少首屏渲染负担。
:::
## 组件架构
@@ -11,7 +11,7 @@
```
src/components/Modal/
├── src/
│ ├── BasicModal.vue # 主组件（基于 el-dialog）
│ ├── BasicModal.vue # 主组件（基于 NaiveUI n-modal）
│ ├── props.ts # 属性定义
│ ├── type.ts # 类型定义（ModalProps、ModalMethods）
│ └── hooks/
@@ -19,108 +19,149 @@ src/components/Modal/
└── index.ts # 导出 useModal 等
```
## BasicModal 组件
## basicModal 组件
`BasicModal` 基于 `el-dialog` 封装，提供全屏切换、自定义头部、提交按钮等能力：
`basicModal` 基于 NaiveUI `n-modal` 封装，通过 `useModal` hook 管理弹窗状态，提供全屏切换、自定义头部、自动 OK/Cancel 按钮等能力：
```vue
<BasicModal :title="'编辑'" :width="600" @register="registerModal" @ok="handleSubmit">
<BasicForm @register="registerForm" />
</BasicModal>
<basicModal @register="modalRegister" ref="modalRef" class="basicModal basicFormModal" @on-ok="handleSubmit" @on-close="handleClose">
<template #default>
<n-form ref="formRef" :model="formData" label-placement="left" label-width="85px">
...
</n-form>
</template>
</basicModal>
```
```typescript
const [modalRegister, { openModal, setSubLoading }] = useModal({
title: '编辑',
subBtuText: '确定',
width: 600,
});
```
核心功能：
- 自定义头部（标题 + 全屏/关闭按钮）
- 提交按钮自动 loading（`setSubLoading`）
- `setProps` 动态修改弹窗属性
- `openModal` / `closeModal` 控制显隐
- `useModal` hook 返回 `modalRegister`（绑定到组件 `@register`）和操作方法
- `openModal` 打开弹窗、`setSubLoading` 控制提交按钮 loading
- 自动渲染 OK/Cancel 底部按钮，无需手动编写 footer 模板
- `@on-ok` 监听确定按钮点击，`@on-close` 监听关闭事件
## 实际用法（position 模块）
以岗位管理为例，实际使用原生 `el-dialog` + `defineAsyncComponent` 懒加载：
以岗位管理为例，使用 `basicModal` + `useModal` hook 管理弹窗状态。
### 父组件（index.vue）
```vue
<!-- src/views/system/position/index.vue -->
<script setup>
import { defineAsyncComponent } from 'vue';
const editDialog = defineAsyncComponent(() => import('./edit.vue'));
import { h, nextTick, reactive, ref } from 'vue';
import { useMessage, useDialog } from 'naive-ui';
import editDialog from './edit.vue';
const positionId = ref(0);
const message = useMessage();
const dialog = useDialog();
const createModalRef = ref();
const editVisible = ref(false);
const positionId = ref(0);
// 新增
const handleAdd = async () => {
positionId.value = 0;
await nextTick();
editVisible.value = true;
await nextTick();
createModalRef.value.openModal();
};
// 编辑
const handleEdit = async (record: Recordable) => {
positionId.value = record.row.id;
await nextTick();
positionId.value = record.id;
editVisible.value = true;
await nextTick();
createModalRef.value.openModal();
};
// 删除
async function handleDelete(record) {
dialog.warning({
title: '提示',
content: '确定要删除？',
positiveText: '确定',
negativeText: '取消',
onPositiveClick: async () => {
record.id ? await positionDelete(record.id) : await positionBatchDelete(rowKeys.value);
message.success('删除成功');
reloadTable();
},
});
}
</script>
<template>
<editDialog
v-if="editVisible"
ref="createModalRef"
:positionId="positionId"
v-if="editVisible"
v-model:visible="editVisible"
@success="reloadTable('noRefresh')"
/>
</template>
```
`defineAsyncComponent` 实现懒加载：首屏不加载弹窗组件，首次打开时才加载，加载完成后缓存。
父组件通过 `ref` 获取子组件实例，调用 `createModalRef.value.openModal()` 打开弹窗。子组件通过 `defineExpose({ openModal })` 暴露该方法。
### 编辑弹窗（edit.vue）
```vue
<!-- src/views/system/position/edit.vue -->
<template>
<el-dialog
v-model="props.visible"
:title="props.positionId ? '编辑' : '新增'"
width="500"
:close-on-click-modal="false"
:before-close="dialogClose"
<basicModal
@register="modalRegister"
ref="modalRef"
class="basicModal basicFormModal"
@on-ok="handleSubmit"
@on-close="handleClose"
>
<el-form class="ls-form" ref="formRef" :model="formData" label-width="80px">
<el-form-item
label="岗位名称"
prop="name"
:rules="{ required: true, message: '请输入岗位名称', trigger: 'blur' }"
<template #default>
<n-form
class="ls-form"
ref="formRef"
:model="formData"
label-placement="left"
label-width="85px"
>
<el-input v-model="formData.name" placeholder="请输入岗位名称" clearable />
</el-form-item>
<el-form-item label="岗位状态" prop="status">
<el-radio-group v-model="formData.status">
<el-radio :value="1">正常</el-radio>
<el-radio :value="2">停用</el-radio>
</el-radio-group>
</el-form-item>
<el-form-item label="排序" prop="sort">
<el-input-number v-model="formData.sort" />
</el-form-item>
</el-form>
<template #footer>
<el-button @click="dialogClose">取消</el-button>
<el-button :loading="subLoading" type="primary" @click="submit">确定</el-button>
<n-form-item
label="岗位名称"
path="name"
:rule="{ required: true, message: '请输入岗位名称', trigger: 'blur' }"
>
<n-input v-model:value="formData.name" placeholder="请输入岗位名称" clearable />
</n-form-item>
<n-form-item label="岗位状态" path="code">
<n-radio-group v-model:value="formData.status" name="status">
<n-radio :value="1">正常</n-radio>
<n-radio :value="2">停用</n-radio>
</n-radio-group>
</n-form-item>
<n-form-item label="排序" path="sort">
<n-input-number v-model:value="formData.sort" />
</n-form-item>
</n-form>
</template>
</el-dialog>
</basicModal>
</template>
<script lang="ts" setup>
import { getPositionDetail, positionAdd, positionUpdate } from '@/api/system/position';
import { useLockFn } from '@/utils/useLockFn';
import { onMounted, reactive, ref } from 'vue';
import { useMessage } from 'naive-ui';
import { useModal } from '@/components/Modal';
const emit = defineEmits(['success', 'update:visible']);
const formRef = shallowRef<FormInstance>();
const formRef = ref();
const message = useMessage();
const formData = reactive({ id: '', name: '', status: 1, sort: 0 });
@@ -129,20 +170,31 @@ const props = defineProps({
positionId: { type: Number, required: true, default: 0 },
});
// 定义模态框
const [modalRegister, { openModal, setSubLoading }] = useModal({
title: props.positionId ? '编辑岗位' : '添加岗位',
subBtuText: '确定',
width: 600,
});
// 提交处理
const handleSubmit = async () => {
await formRef.value?.validate();
props.positionId ? await positionUpdate(formData) : await positionAdd(formData);
message('操作成功');
emit('update:visible', false);
emit('success');
formRef.value
.validate()
.then(async () => {
props.positionId ? await positionUpdate(formData) : await positionAdd(formData);
message.success('操作成功');
setSubLoading(false);
emit('update:visible', false);
emit('success');
})
.catch((error) => {
setSubLoading(false);
});
};
// 关闭弹窗
const dialogClose = () => { emit('update:visible', false); };
// useLockFn 防重复提交，isLock 绑定按钮 loading
const { isLock: subLoading, lockFn: submit } = useLockFn(handleSubmit);
const handleClose = () => { emit('update:visible', false); };
// 编辑时加载数据
const setFormData = async () => {
@@ -157,27 +209,34 @@ const setFormData = async () => {
onMounted(() => {
if (props.positionId) setFormData();
});
defineExpose({ openModal });
</script>
```
## 弹窗数据流
```
父组件点击编辑 → positionId = record.row.id → editVisible = true
父组件点击编辑 → positionId = record.id → editVisible = true → nextTick → createModalRef.openModal()
↓
basicModal 显示 → useModal 配置标题和按钮
↓
edit.vue onMounted → positionId != 0 → setFormData() → 获取详情填充表单
↓
用户修改 → submit → useLockFn(防重复) → formRef.validate() → positionUpdate(formData)
用户点击确定 → @on-ok → handleSubmit → formRef.validate() → positionUpdate(formData) → setSubLoading(false)
↓
emit('success') → 父组件 reloadTable() → 表格刷新
```
## 确认弹窗
删除等危险操作使用 `confirm` 封装函数（来自 `src/utils/auth.ts`）：
删除等危险操作使用 NaiveUI 的 `useDialog` 组合式函数：
```typescript
import { message, confirm } from '@/utils/auth';
import { useMessage, useDialog } from 'naive-ui';
const message = useMessage();
const dialog = useDialog();
async function handleDelete(record: Recordable) {
let ids = [];
@@ -185,34 +244,26 @@ async function handleDelete(record: Recordable) {
ids = selectionData.value.map(({ id }) => id);
}
await confirm('确定要删除？');
record ? await positionDelete(record.row.id) : await positionBatchDelete(ids);
message('删除成功');
reloadTable();
dialog.warning({
title: '提示',
content: '确定要删除？',
positiveText: '确定',
negativeText: '取消',
onPositiveClick: async () => {
record ? await positionDelete(record.id) : await positionBatchDelete(ids);
message.success('删除成功');
reloadTable();
},
});
}
```
`confirm` 内部调用 `ElMessageBox.confirm`，返回 Promise，用户取消时抛出异常中断后续逻辑。
## v-model:visible 双向绑定
弹窗使用 `v-model:visible` 实现父子组件双向绑定：
```vue
<!-- 父组件 -->
<editDialog v-model:visible="editVisible" />
<!-- 子组件 -->
<script setup>
const emit = defineEmits(['update:visible']);
const dialogClose = () => { emit('update:visible', false); };
</script>
```
`dialog.warning` 返回一个对话框实例，用户点击"确定"后执行 `onPositiveClick` 回调。与旧版 `confirm` 不同，不需要 `await` 和 `try/catch`，逻辑全部写在回调中。
:::tip 温馨提示
弹窗组件通过 `defineAsyncComponent(() => import('./edit.vue'))` 懒加载，首屏不加载弹窗代码。`useLockFn` 将 `isLock` 绑定按钮的 `:loading` 属性，防止重复提交。关闭弹窗时通过 `v-model:visible` 自动同步父子状态。
弹窗组件通过 `v-if` 控制懒加载，首屏不加载弹窗代码。`useModal` 的 `setSubLoading` 控制确定按钮 loading 状态，防止重复提交。`message.success` 和 `dialog.warning` 来自 NaiveUI 的 `useMessage()` 和 `useDialog()` 组合式函数，需要在 `setup` 中调用获取实例。
:::
## 总结
编辑弹窗使用 `el-dialog` + `defineAsyncComponent` 懒加载，通过 `v-model:visible` 双向绑定显隐状态，`useLockFn` 防重复提交。父组件通过 `positionId` prop 传递编辑行 ID，子组件在 `onMounted` 中判断并加载详情数据。操作成功后 `emit('success')` 通知父组件刷新表格。
编辑弹窗使用 `basicModal` + `useModal` hook 管理弹窗状态，通过 `defineExpose({ openModal })` 暴露给父组件调用。`useModal` 返回 `modalRegister` 绑定到 `@register`，以及 `openModal`、`setSubLoading` 等操作方法。表单使用 NaiveUI 的 `n-form` 系列组件，绑定方式为 `v-model:value`，校验字段用 `path` 属性。删除确认使用 `useDialog` 的 `dialog.warning` 回调模式。操作成功后通过 `emit('success')` 通知父组件刷新表格。
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/perm-directive.md
+12 -12
View File
@@ -92,15 +92,15 @@ export function usePermission() {
### v-perm（满足任一权限）
```vue
<el-button v-perm="['sys:position:add']">添加岗位</el-button>
<el-button v-perm="['sys:position:batchDelete']">删除</el-button>
<el-button v-perm="['sys:position:export']">导出</el-button>
<n-button v-perm="['sys:position:add']">添加岗位</n-button>
<n-button v-perm="['sys:position:batchDelete']">删除</n-button>
<n-button v-perm="['sys:position:export']">导出</n-button>
```
### v-perms（满足所有权限）
```vue
<el-button v-perms="['sys:user:add', 'sys:user:import']">高级操作</el-button>
<n-button v-perms="['sys:user:add', 'sys:user:import']">高级操作</n-button>
```
### 与 v-if 结合
@@ -115,7 +115,7 @@ const showAddBtn = computed(() => hasPermission(['sys:position:add']));
```
```vue
<el-button v-if="showAddBtn">添加岗位</el-button>
<n-button v-if="showAddBtn">添加岗位</n-button>
```
## 实际用法（position 模块）
@@ -127,15 +127,15 @@ const showAddBtn = computed(() => hasPermission(['sys:position:add']));
<template>
<BasicTable :columns="columns" :request="loadDataTable" ref="tableRef" :actionColumn="actionColumn">
<template #tableTitle>
<el-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">
<template #icon><el-icon><PlusOutlined /></el-icon></template>
<n-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">
<template #icon><n-icon><PlusOutlined /></n-icon></template>
添加岗位
</el-button>
<el-button type="danger" @click="handleDelete()" :disabled="!selectionData.length"
</n-button>
<n-button type="error" @click="handleDelete()" :disabled="!rowKeys.length"
v-perm="['sys:position:batchDelete']">
<template #icon><el-icon><Delete /></el-icon></template>
<template #icon><n-icon><DeleteOutlined /></n-icon></template>
删除
</el-button>
</n-button>
</template>
</BasicTable>
</template>
@@ -206,7 +206,7 @@ class ExampleAddView(PermissionRequired, View):
```vue
<!-- 前端 -->
<el-button v-perm="['sys:example:add']">添加案例</el-button>
<n-button v-perm="['sys:example:add']">添加案例</n-button>
```
## 超级管理员
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/setup.md
+6 -6
View File
@@ -3,7 +3,7 @@
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
:::tip 说明
前端基于 Vue3 + ElementPlus 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。
前端基于 Vue3 + NaiveUI 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。
:::
## 技术栈
@@ -11,7 +11,7 @@
| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.x | 渐进式 JavaScript 框架，组合式 API |
| ElementPlus | 2.x | Vue3 组件库 |
| NaiveUI | 2.x | Vue3 组件库 |
| Vite | 3.x | 下一代前端构建工具 |
| Pinia | 2.x | 状态管理（Vuex 替代方案） |
| Vue Router | 4.x | 路由管理 |
@@ -147,12 +147,12 @@ import { createApp } from 'vue';
import App from './App.vue';
import router, { setupRouter } from './router';
import { setupStore } from '@/store';
import { setupElement, setupDirectives, setupCustomComponents } from '@/plugins';
import { setupNaive, setupDirectives, setupCustomComponents } from '@/plugins';
async function bootstrap() {
const app = createApp(App);
setupElement(app); // 全局引入 ElementPlus 组件
setupNaive(app); // 全局引入 NaiveUI 组件
setupCustomComponents(app); // 注册自定义组件
setupDirectives(app); // 注册自定义指令（v-perm 等）
setupStore(app); // 挂载 Pinia 状态管理
@@ -165,8 +165,8 @@ async function bootstrap() {
void bootstrap();
```
初始化顺序：样式加载 -> ElementPlus -> 自定义组件 -> 自定义指令 -> Pinia Store -> Router -> 挂载。
初始化顺序：样式加载 -> NaiveUI -> 自定义组件 -> 自定义指令 -> Pinia Store -> Router -> 挂载。
## 总结
前端项目基于 Vue3 + ElementPlus + Vite + TypeScript + Pinia 构建，使用 pnpm 管理依赖，Tailwind CSS + SCSS 提供样式能力。通过 `main.ts` 的 `bootstrap()` 函数按顺序初始化所有基础设施，目录结构按功能分层组织，便于维护和扩展。
前端项目基于 Vue3 + NaiveUI + Vite + TypeScript + Pinia 构建，使用 pnpm 管理依赖，Tailwind CSS + SCSS 提供样式能力。通过 `main.ts` 的 `bootstrap()` 函数按顺序初始化所有基础设施，目录结构按功能分层组织，便于维护和扩展。
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/style.md
+23 -26
View File
@@ -3,7 +3,7 @@
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
:::tip 说明
前端样式方案采用 Tailwind CSS + SCSS + ElementPlus 主题覆盖，支持深色模式切换。全局 SCSS 变量通过 Vite 的 `additionalData` 注入。
前端样式方案采用 Tailwind CSS + SCSS + NaiveUI 主题覆盖，支持深色模式切换。全局 SCSS 变量通过 Vite 的 `additionalData` 注入。
:::
## 样式架构
@@ -13,7 +13,7 @@ src/styles/
├── var.scss # SCSS 全局变量（通过 Vite additionalData 注入）
├── index.scss # 入口文件，引入所有样式
├── tailwindbase.css # Tailwind CSS 基础样式
└── element-override.css # ElementPlus 主题覆盖（可选）
└── naive-override.css # NaiveUI 主题覆盖（可选）
```
## SCSS 全局变量
@@ -58,36 +58,33 @@ import './styles/tailwindbase.css';
<div class="w-full md:w-1/2 lg:w-1/3">响应式宽度</div>
```
## ElementPlus 主题
## NaiveUI 主题
ElementPlus 通过 CSS 变量支持主题定制：
NaiveUI 通过 CSS 变量和 ConfigProvider 支持主题定制：
```typescript
// main.ts
import 'element-plus/dist/index.css';
import 'element-plus/theme-chalk/display.css';
import 'element-plus/theme-chalk/dark/css-vars.css'; // 深色模式 CSS 变量
// App.vue 或入口组件
import { zhCN, dateZhCN } from 'naive-ui';
```
### ElementPlus 全局引入
### NaiveUI 全局引入
```typescript
// src/plugins/setupElement.ts
import ElementPlus from 'element-plus';
import zhCn from 'element-plus/es/locale/lang/zh-cn';
// src/plugins/naive.ts
import { setupNaiveUI } from '@/plugins/naive';
export function setupElement(app) {
app.use(ElementPlus, { locale: zhCn, size: 'default' });
export function setupNaive(app) {
setupNaiveUI(app);
}
```
## 深色模式
通过 ElementPlus 的 `dark/css-vars.css` 和 Tailwind 的 `dark` 模式实现深色主题：
通过 NaiveUI 的暗色主题和 Tailwind 的 `dark` 模式实现深色主题：
```vue
<template>
<el-switch v-model="isDark" @change="toggleDark" />
<n-switch v-model:value="isDark" @update:value="toggleDark" />
</template>
<script setup>
@@ -102,9 +99,9 @@ const toggleDark = (val) => {
```css
.dark {
--el-bg-color: #1d1e1f;
--el-text-color-primary: #e5eaf3;
--el-border-color: #4c4d4f;
--n-color: #1d1e1f;
--n-text-color: #e5eaf3;
--n-border-color: #4c4d4f;
}
```
@@ -131,14 +128,14 @@ export function useDesignSetting() {
```vue
<template>
<PageWrapper>
<el-card :bordered="false" class="pt-3 mb-3 proCard">
<div>
<n-card :bordered="false" class="pt-3 mb-3 proCard">
<!-- 搜索区域 -->
</el-card>
<el-card :bordered="false" class="proCard">
</n-card>
<n-card :bordered="false" class="proCard">
<!-- 表格区域 -->
</el-card>
</PageWrapper>
</n-card>
</div>
</template>
```
@@ -152,4 +149,4 @@ export function useDesignSetting() {
## 总结
样式方案采用 Tailwind CSS 提供原子化样式 + SCSS 全局变量（Vite `additionalData` 注入）+ ElementPlus 主题覆盖，支持深色模式切换。`designSetting` store 管理主题配置，`PageWrapper` 组件提供统一页面容器。
样式方案采用 Tailwind CSS 提供原子化样式 + SCSS 全局变量（Vite `additionalData` 注入）+ NaiveUI 主题覆盖，支持深色模式切换。`designSetting` store 管理主题配置，`PageWrapper` 组件提供统一页面容器。
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/table.md
+15 -15
View File
@@ -3,7 +3,7 @@
<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->
:::tip 说明
`BasicTable` 位于 `src/components/Table/src/Table.vue`，基于 ElementPlus 的 `el-table` 二次封装，提供列定义、数据请求、分页、操作列、多选、全屏、密度调整、列设置等能力。
`BasicTable` 位于 `src/components/Table/src/Table.vue`，基于 NaiveUI 的 `n-data-table` 二次封装，提供列定义、数据请求、分页、操作列、多选、全屏、密度调整、列设置等能力。
:::
## 组件架构
@@ -40,7 +40,7 @@ src/components/Table/
@selection-change="onSelectionChange"
>
<template #tableTitle>
<el-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">添加岗位</el-button>
<n-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">添加岗位</n-button>
</template>
</BasicTable>
```
@@ -53,27 +53,27 @@ src/components/Table/
// src/views/system/position/columns.ts
import { h } from 'vue';
import { ElTag } from 'element-plus';
import { NTag } from 'naive-ui';
export const columns = [
{ type: 'selection' },
{ label: 'ID', prop: 'id', fixed: 'left', width: 50 },
{ label: '岗位名称', prop: 'name', minWidth: 100 },
{ type: 'selection', width: 50, fixed: 'left' },
{ title: 'ID', key: 'id', width: 50 },
{ title: '岗位名称', key: 'name', width: 100 },
{
label: '岗位状态',
prop: 'status',
minWidth: 100,
title: '岗位状态',
key: 'status',
width: 100,
render(record) {
return h(
ElTag,
{ type: record.row.status == 1 ? 'success' : 'danger' },
{ default: () => (record.row.status == 1 ? '正常' : '停用') },
NTag,
{ bordered: false, type: record.status == 1 ? 'success' : 'error' },
{ default: () => (record.status == 1 ? '正常' : '停用') },
);
},
},
{ label: '排序', prop: 'sort', minWidth: 100 },
{ label: '创建人', prop: 'createUser', minWidth: 100 },
{ label: '创建时间', prop: 'createTime', width: 180 },
{ title: '排序', key: 'sort', width: 100 },
{ title: '创建人', key: 'createUser', width: 100 },
{ title: '创建时间', key: 'createTime', width: 180 },
];
```
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/utils.md
+2 -2
View File
@@ -235,9 +235,9 @@ export enum PageEnum {
```
:::tip 温馨提示
`Storage` 工具类自动将键名转为大写（如 `access-token` → `ACCESS-TOKEN`），存储时包含过期时间，读取时自动检查是否过期。`auth.ts` 中的 `confirm` 和 `message` 函数是对 ElementPlus 的简封装，在业务组件中直接调用即可。
`Storage` 工具类自动将键名转为大写（如 `access-token` → `ACCESS-TOKEN`），存储时包含过期时间，读取时自动检查是否过期。`auth.ts` 中的 `confirm` 和 `message` 函数是对 NaiveUI 的简封装，在业务组件中直接调用即可。
:::
## 总结
工具函数库提供了 Storage（本地存储，支持过期）、auth（认证管理、树结构操作、文件下载）、dateUtil（日期格式化）、httpEnum/pageEnum（枚举定义）等通用能力。`confirm` 和 `message` 是 ElementPlus 的简封装，`arrayToTree`/`treeToArray` 处理菜单数据转换。
工具函数库提供了 Storage（本地存储，支持过期）、auth（认证管理、树结构操作、文件下载）、dateUtil（日期格式化）、httpEnum/pageEnum（枚举定义）等通用能力。`confirm` 和 `message` 是 NaiveUI 的简封装，`arrayToTree`/`treeToArray` 处理菜单数据转换。
DjangoAdmin_Django_NaiveVue/zh/volume4/frontend/view.md
+372 -90
View File
@@ -26,9 +26,9 @@ src/views/
| 文件 | 职责 | 说明 |
|------|------|------|
| `index.vue` | 列表页 | 搜索表单 + 工具栏 + BasicTable + 编辑弹窗引用 |
| `edit.vue` | 编辑弹窗 | el-dialog + el-form，懒加载 |
| `detail.vue` | 详情弹窗 | el-dialog 展示详情，懒加载 |
| `columns.ts` | 表格列定义 | 定义列 prop、label、render 函数等 |
| `edit.vue` | 编辑弹窗 | n-dialog + n-form，懒加载 |
| `detail.vue` | 详情弹窗 | n-dialog 展示详情，懒加载 |
| `columns.ts` | 表格列定义 | 定义列 key、title、render 函数等 |
| `querySchemas.ts` | 搜索表单定义 | FormSchema 数组，定义搜索字段 |
## index.vue 列表页
@@ -37,122 +37,284 @@ src/views/
```vue
<template>
<PageWrapper>
<div>
<!-- 搜索表单卡片 -->
<el-card :bordered="false" class="pt-3 mb-3 proCard">
<n-card :bordered="false" class="pt-3 mb-3 proCard">
<BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
</el-card>
</n-card>
<!-- 数据表格卡片 -->
<el-card :bordered="false" class="proCard">
<n-card :bordered="false" class="proCard">
<BasicTable
:columns="columns"
:request="loadDataTable"
:row-key="(row) => row.id"
ref="tableRef"
ref="basicTableRef"
:actionColumn="actionColumn"
@selection-change="onSelectionChange"
@update:checked-row-keys="onCheckedRow"
:auto-scroll-x="true"
>
<!-- 表格顶部工具栏 -->
<template #tableTitle>
<el-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
添加案例
</el-button>
<el-button type="danger" @click="handleDelete()" :disabled="!selectionData.length"
v-perm="['sys:example:batchDelete']">
批量删除
</el-button>
<n-space>
<!-- 新增按钮 -->
<n-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
<template #icon>
<n-icon>
<PlusOutlined />
</n-icon>
</template>
添加案例
</n-button>
<!-- 批量删除按钮 -->
<n-button
type="error"
@click="handleDelete()"
:disabled="!rowKeys.length"
v-perm="['sys:example:batchDelete']"
>
<template #icon>
<n-icon>
<DeleteOutlined />
</n-icon>
</template>
批量删除
</n-button>
</n-space>
</template>
</BasicTable>
</el-card>
</n-card>
<!-- 编辑对话框组件 -->
<editDialog v-if="editVisible" :id="currentId" v-model:visible="editVisible" @success="reloadTable('noRefresh')" />
<editDialog
ref="editModalRef"
v-if="editVisible"
:id="currentId"
v-model:visible="editVisible"
@success="reloadTable('noRefresh')"
/>
<!-- 查看详情对话框组件 -->
<detailDialog v-if="detailVisible" :id="currentId" v-model:visible="detailVisible" @success="reloadTable('noRefresh')" />
</PageWrapper>
<detailDialog
ref="detailModalRef"
v-if="detailVisible"
:id="currentId"
v-model:visible="detailVisible"
@success="reloadTable('noRefresh')"
/>
</div>
</template>
<script lang="ts" setup>
import { reactive, ref, h, nextTick, defineAsyncComponent } from 'vue';
import { schemas } from './querySchemas';
import { useForm } from '@/components/Form/index';
import { h, nextTick, reactive, ref } from 'vue';
import { useMessage, useDialog } from 'naive-ui';
import { PlusOutlined, DeleteOutlined, EditOutlined, EyeOutlined } from '@vicons/antd';
import { TableAction } from '@/components/Table';
import { BasicForm, useForm } from '@/components/Form/index';
import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
import { renderIcon } from '@/utils';
import { columns } from './columns';
import { message, confirm } from '@/utils/auth';
import { schemas } from './querySchemas';
const editDialog = defineAsyncComponent(() => import('./edit.vue'));
const detailDialog = defineAsyncComponent(() => import('./detail.vue'));
// 动态导入编辑对话框组件
import editDialog from './edit.vue';
// 动态导入详情对话框组件
import detailDialog from './detail.vue';
const currentId = ref(0);
const editVisible = ref(false);
const detailVisible = ref(false);
const selectionData = ref([]);
const tableRef = ref();
// 消息提示和对话框
const message = useMessage();
const dialog = useDialog();
const formParams = reactive({ name: '', type: '', status: '' });
// 表格引用
const basicTableRef = ref();
const editModalRef = ref();
const detailModalRef = ref();
// 响应式状态定义
const currentId = ref(0); // 当前操作的ID
const editVisible = ref(false); // 编辑对话框显示状态
const detailVisible = ref(false); // 详情对话框显示状态
const rowKeys = ref([]); // 表格选中行Key
/**
* 定义查询参数
* 用于存储搜索表单的值
*/
const formParams = reactive({
name: '',
type: '',
status: '',
});
/**
* 定义操作栏配置
* 包含编辑、详情和删除按钮
*/
const actionColumn = reactive({
width: 300,
label: '操作',
prop: 'action',
width: 280,
title: '操作',
align: 'center',
key: 'action',
fixed: 'right',
render(record) {
return h(TableAction, {
return h(TableAction as any, {
style: 'button',
actions: [
{ label: '编辑', icon: 'Edit', type: 'warning', onClick: handleEdit.bind(null, record), auth: ['sys:example:update'] },
{ label: '详情', icon: 'View', type: '', onClick: handleDetail.bind(null, record), auth: ['sys:example:detail'] },
{ label: '删除', icon: 'Delete', type: 'danger', onClick: handleDelete.bind(null, record), auth: ['sys:example:delete'] },
{
label: '编辑',
icon: renderIcon(EditOutlined),
type: 'info',
onClick: handleEdit.bind(null, record),
auth: ['sys:example:update'],
},
{
label: '详情',
icon: renderIcon(EyeOutlined),
type: 'default',
onClick: handleDetail.bind(null, record),
auth: ['sys:example:detail'],
},
{
label: '删除',
icon: renderIcon(DeleteOutlined),
type: 'error',
onClick: handleDelete.bind(null, record),
auth: ['sys:example:delete'],
},
],
});
},
});
/**
* 加载数据列表
* @param params 分页参数
* @returns 表格数据
*/
const loadDataTable = async (params: any) => {
// 清空选中行
rowKeys.value = [];
const result = await getExamplePage({ ...formParams, ...params });
return result;
};
/**
* 刷新表格数据
* @param noRefresh 是否重置页码
*/
function reloadTable(noRefresh = '') {
tableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
basicTableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
}
/**
* 注册搜索表单
* 配置表单布局和字段
*/
const [register, {}] = useForm({
gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
labelWidth: 80,
layout: 'horizontal',
colProps: { span: 6 },
submitOnReset: true,
schemas,
});
function handleSubmit(values) {
handleReset();
for (const key in values) { formParams[key] = values[key]; }
/**
* 提交搜索表单
* @param values 表单值
*/
function handleSubmit(values: Recordable) {
for (const key in formParams) {
formParams[key] = '';
}
for (const key in values) {
formParams[key] = values[key];
}
reloadTable();
}
function handleReset() {
for (const key in formParams) { formParams[key] = ''; }
/**
* 重置搜索表单
*/
function handleReset(values: Recordable) {
for (const key in formParams) {
formParams[key] = '';
}
for (const key in values) {
formParams[key] = values[key];
}
reloadTable();
}
const handleAdd = async () => { currentId.value = 0; await nextTick(); editVisible.value = true; };
const handleEdit = async (record) => { currentId.value = record.row.id; await nextTick(); editVisible.value = true; };
const handleDetail = async (record) => { currentId.value = record.row.id; await nextTick(); detailVisible.value = true; };
/**
* 表格选择项变化时的回调
* @param keys 选中的key数组
*/
function onCheckedRow(keys: (string | number)[]) {
rowKeys.value = keys;
}
async function handleDelete(record) {
/**
* 处理新增按钮点击
*/
const handleAdd = async () => {
currentId.value = 0;
editVisible.value = true;
await nextTick();
editModalRef.value?.openModal();
};
/**
* 处理编辑按钮点击
* @param record 当前行数据
*/
const handleEdit = async (record: Recordable) => {
currentId.value = record.id;
editVisible.value = true;
await nextTick();
editModalRef.value?.openModal();
};
/**
* 处理详情按钮点击
* @param record 当前行数据
*/
const handleDetail = async (record: Recordable) => {
currentId.value = record.id;
detailVisible.value = true;
await nextTick();
detailModalRef.value?.openModal();
};
/**
* 处理删除操作
* @param record 当前行数据（可选，不传时表示批量删除）
*/
async function handleDelete(record?: Recordable) {
let ids = [];
if (!record) {
ids = selectionData.value.map(({ id }) => id);
if (!ids.length) { message('请选择要删除的数据', 'warning'); return; }
// 批量删除：获取选中行的ID
ids = rowKeys.value;
if (!ids.length) {
message.warning('请选择要删除的数据');
return;
}
}
await confirm('确定要删除选中的案例吗？');
record ? await exampleDelete(record.row.id) : await exampleBatchDelete(ids);
message('删除成功');
reloadTable();
}
function onSelectionChange(value) { selectionData.value = value; }
dialog.warning({
title: '提示',
content: '确定要删除选中的案例吗？',
positiveText: '确定',
negativeText: '取消',
onPositiveClick: async () => {
try {
record ? await exampleDelete(record.id) : await exampleBatchDelete(ids);
message.success('删除成功');
reloadTable();
} catch (error) {
message.error('删除失败');
}
},
});
}
</script>
```
@@ -160,37 +322,119 @@ src/views/
```typescript
import { h } from 'vue';
import { ElAvatar, ElTag } from 'element-plus';
import { NTag, NAvatar, NImage } from 'naive-ui';
/**
* 表格列配置
* 定义表格显示的列
*/
export const columns = [
{ type: 'selection' },
{ label: 'ID', prop: 'id', fixed: 'left', width: 50 },
{ label: '案例名称', prop: 'name', minWidth: 120 },
{
label: '案例图片', prop: 'avatar', minWidth: 120,
render(record) {
return h(ElAvatar, { size: 48, src: record.row.avatar, shape: 'square', fit: 'fill' });
type: 'selection', // 多选框列
width: 50,
fixed: 'left',
},
{
title: 'ID',
key: 'id',
fixed: 'left',
width: 50,
},
{
title: '案例名称',
key: 'name',
width: 150,
// 普通文本渲染（无需额外配置）
ellipsis: {
tooltip: true,
},
},
{
label: '案例类型', prop: 'type', minWidth: 100,
title: '案例图片',
key: 'avatar',
width: 150,
// 图片渲染
render(record) {
const statusMap = { 1: { text: '类型1', type: 'success' }, 2: { text: '类型2', type: 'danger' } };
const status = statusMap[record.row.type];
return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.type });
return record.avatar
? h(NAvatar, {
src: record.avatar,
size: 48,
shape: 'square',
fit: 'cover',
style: {
borderRadius: '4px',
},
})
: h('span', '-');
},
},
{
label: '案例状态', prop: 'status', minWidth: 100,
title: '案例类型',
key: 'type',
width: 100,
// 选项标签渲染
render(record) {
const statusMap = { 1: { text: '正常', type: 'success' }, 2: { text: '禁用', type: 'danger' } };
const status = statusMap[record.row.status];
return h(ElTag, { type: status?.type || 'info' }, { default: () => status?.text || record.row.status });
const statusMap = {
1: { text: '类型1', type: 'success' },
2: { text: '类型2', type: 'error' },
3: { text: '类型3', type: 'warning' },
4: { text: '类型4', type: 'info' },
};
const status = statusMap[record.type];
return h(
NTag,
{
bordered: false,
type: status?.type || 'info',
},
{
default: () => status?.text || record.type,
},
);
},
},
{ label: '排序', prop: 'sort', minWidth: 100 },
{ label: '创建人', prop: 'createUser', minWidth: 100 },
{ label: '创建时间', prop: 'createTime', width: 180 },
{
title: '案例状态',
key: 'status',
width: 100,
// 选项标签渲染
render(record) {
const statusMap = {
1: { text: '正常', type: 'success' },
2: { text: '禁用', type: 'error' },
};
const status = statusMap[record.status];
return h(
NTag,
{
bordered: false,
type: status?.type || 'info',
},
{
default: () => status?.text || record.status,
},
);
},
},
{
title: '排序',
key: 'sort',
width: 100,
// 普通文本渲染（无需额外配置）
ellipsis: {
tooltip: true,
},
},
{
title: '创建人',
key: 'createUser',
width: 100,
},
{
title: '创建时间',
key: 'createTime',
width: 180,
},
];
```
@@ -199,28 +443,66 @@ export const columns = [
```typescript
import { FormSchema } from '@/components/Form/index';
/**
* 查询表单配置
* 定义搜索区域的表单项
*/
export const schemas: FormSchema[] = [
{
field: 'name', component: 'Input', label: '案例名称',
componentProps: { placeholder: '请输入案例名称', clearable: true },
field: 'name',
component: 'NInput',
label: '案例名称',
componentProps: {
placeholder: '请输入案例名称',
clearable: true,
filterable: false,
},
},
{
field: 'type', component: 'Select', label: '案例类型',
field: 'type',
component: 'NSelect',
label: '案例类型',
componentProps: {
placeholder: '请输入案例类型', clearable: true,
placeholder: '请输入案例类型',
clearable: true,
filterable: true,
options: [
{ label: '类型1', value: 1 },
{ label: '类型2', value: 2 },
{
label: '类型1',
value: 1,
},
{
label: '类型2',
value: 2,
},
{
label: '类型3',
value: 3,
},
{
label: '类型4',
value: 4,
},
],
},
},
{
field: 'status', component: 'Select', label: '案例状态',
field: 'status',
component: 'NSelect',
label: '案例状态',
componentProps: {
placeholder: '请输入案例状态', clearable: true,
placeholder: '请输入案例状态',
clearable: true,
filterable: true,
options: [
{ label: '正常', value: 1 },
{ label: '禁用', value: 2 },
{
label: '正常',
value: 1,
},
{
label: '禁用',
value: 2,
},
],
},
},
@@ -234,7 +516,7 @@ export const schemas: FormSchema[] = [
用户搜索 → handleSubmit → 更新 formParams → reloadTable → 重新请求
用户新增 → handleAdd → currentId=0 → editVisible=true → edit.vue 加载 → 表单填写 → 提交
用户编辑 → handleEdit → currentId=id → editVisible=true → edit.vue 加载详情 → 修改 → 提交
用户删除 → confirm → API → reloadTable
用户删除 → dialog.warning → 确认 → API → reloadTable
```
:::tip 温馨提示
@@ -243,4 +525,4 @@ export const schemas: FormSchema[] = [
## 总结
页面视图遵循 `index.vue` + `edit.vue` + `detail.vue` + `columns.ts` + `querySchemas.ts` 标准模式。列表页使用 `BasicForm` 搜索 + `BasicTable` 展示数据 + `TableAction` 操作按钮，编辑弹窗使用 `defineAsyncComponent` 懒加载 + `useLockFn` 防重复提交。
页面视图遵循 `index.vue` + `edit.vue` + `detail.vue` + `columns.ts` + `querySchemas.ts` 标准模式。列表页使用 `BasicForm` 搜索 + `BasicTable` 展示数据 + `TableAction` 操作按钮，编辑弹窗使用 `import` 直接导入 + `useLockFn` 防重复提交。消息提示使用 NaiveUI 的 `useMessage()`，确认对话框使用 `useDialog()`。
DjangoAdmin_Django_NaiveVue/zh/volume4/integration/dict-sync.md
+12 -12
View File
@@ -181,23 +181,23 @@ export function getDictItemByCode(code) {
```typescript
// src/views/system/param/columns.ts
{
label: '参数类型',
prop: 'type',
title: '参数类型',
key: 'type',
width: 100,
render(record) {
return h(ElTag,
{ type: record.row.type == 0 ? 'primary' : 'warning' },
{ default: () => record.row.type == 0 ? '系统' : '业务' });
return h(NTag,
{ bordered: false, type: record.type == 0 ? 'info' : 'warning' },
{ default: () => record.type == 0 ? '系统' : '业务' });
},
},
{
label: '状态',
prop: 'status',
title: '状态',
key: 'status',
width: 100,
render(record) {
return h(ElTag,
{ type: record.row.status == 1 ? 'success' : 'danger' },
{ default: () => record.row.status == 1 ? '正常' : '禁用' });
return h(NTag,
{ bordered: false, type: record.status == 1 ? 'success' : 'error' },
{ default: () => record.status == 1 ? '正常' : '禁用' });
},
},
```
@@ -218,8 +218,8 @@ const options = [
// 业务字段为数字
formData.type = 0;
// el-option 绑定时需要转换
<el-option :value="Number(item.value)" />
// n-select 的 options 中 value 为字符串，后端需要数字时需转换
// options: [{ label: '业务', value: 1 }] 直接使用数字
```
搜索表单中的 `options` 的 `value` 为字符串 `'0'`/`'1'`，后端筛选字段期望数字。前端 API 传参时自动转换。
DjangoAdmin_Django_NaiveVue/zh/volume4/integration/perm-sync.md
+4 -4
View File
@@ -55,13 +55,13 @@ class ExampleAddView(PermissionRequired, View):
```vue
<!-- src/views/system/position/index.vue -->
<el-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">
<n-button type="primary" @click="handleAdd" v-perm="['sys:position:add']">
添加岗位
</el-button>
<el-button type="danger" @click="handleDelete()" :disabled="!selectionData.length"
</n-button>
<n-button type="danger" @click="handleDelete()" :disabled="!selectionData.length"
v-perm="['sys:position:batchDelete']">
删除
</el-button>
</n-button>
```
### TableAction auth 属性
DjangoAdmin_Django_NaiveVue/zh/volume4/integration/proxy.md
+1 -1
View File
@@ -157,7 +157,7 @@ location /uploads/ {
```
:::tip 温馨提示
后端的文件访问地址需要与前端 `DJANGO_FILE_URL` 配置一致。开发环境为 `http://file.django.elevue`，生产环境需要配置为实际的文件服务域名。
后端的文件访问地址需要与前端 `DJANGO_FILE_URL` 配置一致。开发环境为 `http://file.django.naivevue`，生产环境需要配置为实际的文件服务域名。
:::
## 总结
DjangoAdmin_Django_NaiveVue/zh/volume4/tools/db-session.md
+1 -1
View File
@@ -15,7 +15,7 @@
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
# 数据库名称
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.naivevue')
# 数据库地址
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
DjangoAdmin_Django_NaiveVue/zh/volume4/tools/upload-guide.md
+8 -8
View File
@@ -29,7 +29,7 @@
| 变量 | 默认值 | 说明 |
|:----|:----|:----|
| `DJANGO_UPLOAD_DIR` | `{项目根目录}/public/uploads` | 上传文件存储目录 |
| `DJANGO_FILE_URL` | `http://file.django.elevue` | 文件访问域名 |
| `DJANGO_FILE_URL` | `http://file.django.naivevue` | 文件访问域名 |
| `DJANGO_TEMP_PATH` | `{DJANGO_UPLOAD_DIR}/temp` | 临时文件目录 |
## 上传接口
@@ -66,7 +66,7 @@ file: <文件>
"fileSize": 306995,
"fileName": "2025030614302512345.jpg",
"filePath": "/temp/20250306/2025030614302512345.jpg",
"fileUrl": "http://file.django.elevue/temp/20250306/2025030614302512345.jpg"
"fileUrl": "http://file.django.naivevue/temp/20250306/2025030614302512345.jpg"
},
"ok": true
}
@@ -118,7 +118,7 @@ public/uploads/
上传成功后返回的 `fileUrl` 是拼接了 `DJANGO_FILE_URL` 前缀的完整 URL：
```
http://file.django.elevue/temp/20250306/2025030614302512345.jpg
http://file.django.naivevue/temp/20250306/2025030614302512345.jpg
```
Service 层的 `get_file_url()` 会自动为文件字段补此前缀。
@@ -129,14 +129,14 @@ Service 层的 `get_file_url()` 会自动为文件字段补此前缀。
```vue
<template>
<el-upload
<n-upload
:action="uploadUrl"
:headers="headers"
:on-success="handleSuccess"
:before-upload="beforeUpload"
@finish="handleSuccess"
@before-upload="beforeUpload"
>
<el-button type="primary">上传文件</el-button>
</el-upload>
<n-button type="primary">上传文件</n-button>
</n-upload>
</template>
<script setup>
DjangoAdmin_Django_NaiveVue/zh/volume4/tools/upload.md
+2 -2
View File
@@ -26,7 +26,7 @@ DJANGO_UPLOAD_DIR = os.getenv('DJANGO_UPLOAD_DIR', os.path.join(DJANGO_ROOT_PATH
DJANGO_TEMP_PATH = DJANGO_UPLOAD_DIR + '/temp'
# 文件访问域名
DJANGO_FILE_URL = os.getenv('DJANGO_FILE_URL', 'http://file.django.elevue')
DJANGO_FILE_URL = os.getenv('DJANGO_FILE_URL', 'http://file.django.naivevue')
```
:::tip 温馨提示
@@ -70,7 +70,7 @@ Authorization: Bearer <token>
"fileSize": 306995,
"fileName": "2025030614302512345.jpg",
"filePath": "/temp/20250306/2025030614302512345.jpg",
"fileUrl": "http://file.django.elevue/temp/20250306/2025030614302512345.jpg"
"fileUrl": "http://file.django.naivevue/temp/20250306/2025030614302512345.jpg"
},
"ok": true
}
DjangoAdmin_Django_NaiveVue/zh/volume5/faq.md
+1 -1
View File
@@ -63,7 +63,7 @@ Web API 批量生成最多支持 50 个表。CLI 无限制，但建议逐表生
**解决**：确保在项目根目录（包含 `manage.py` 和 `generator.py` 的目录）执行：
```bash
cd /data/apps/DjangoAdmin_Django_EleVue
cd /data/apps/DjangoAdmin_Django_NaiveVue
python generator.py django_example
```
DjangoAdmin_Django_NaiveVue/zh/volume5/overview.md
+1 -1
View File
@@ -106,7 +106,7 @@ Jinja2 模板文件，分为后端模板（7 个）和前端模板（ui/ 6 个 +
## 使用限制
:::warning 使用前提
1. **数据库要求**：代码生成器基于 MySQL 的 `information_schema` 查询表结构，仅支持 MySQL 数据库。
1. **数据库要求**：代码生成器基于 MySQL 的 `information_schema` 查询表结构，仅支持 MySQL 数据库。其他数据库（PostgreSQL、Oracle、SQL Server 等）需手动创建模块。
2. **表结构要求**：不支持复合主键、外键关联等复杂表结构，建议使用单主键（自增 id）的标准业务表。
3. **环境要求**：需确保 Django 环境已初始化、MySQL 和 Redis 服务正常运行。
:::
DjangoAdmin_Django_NaiveVue/zh/volume5/templates.md
+5 -5
View File
@@ -162,7 +162,7 @@ public/templates/
修改 `public/templates/models.py.tpl`：
```jinja2
```jinja
{% if f.type == 'CharField' %}
{{ f.name }} = models.CharField(
max_length={{ f.max_length or 255 }},
@@ -177,7 +177,7 @@ public/templates/
修改 `public/templates/services.py.tpl`，在添加方法中添加自定义校验：
```jinja2
```jinja
def add_{{ app_name }}(request):
# ... 原有代码 ...
# 自定义校验：检查名称是否重复
@@ -190,7 +190,7 @@ def add_{{ app_name }}(request):
修改 `public/templates/ui/columns.ts.tpl`：
```jinja2
```jinja
{% for f in list_fields %}
{
label: '{{ f.label }}',
@@ -208,7 +208,7 @@ def add_{{ app_name }}(request):
在 `public/templates/` 下新建 `test.py.tpl`：
```jinja2
```jinja
# tests/test_{{ app_name }}.py
from django.test import TestCase
from application.{{ app_name }}.models import {{ model_class_name }}
@@ -247,7 +247,7 @@ backend_templates = [
## Jinja2 语法速查
```jinja2
```jinja
{# 注释 #}
{# 变量输出 #}
DjangoAdmin_Django_NaiveVue/zh/volume6/backup.md
+9 -9
View File
@@ -18,11 +18,11 @@
# 使用 mysqldump 备份单个数据库
mysqldump -h 127.0.0.1 -u root -p --single-transaction \
--routines --triggers --events \
djangoadmin.django.elevue > backup_$(date +%Y%m%d_%H%M%S).sql
djangoadmin.django.naivevue > backup_$(date +%Y%m%d_%H%M%S).sql
# 压缩备份
mysqldump -h 127.0.0.1 -u root -p --single-transaction \
djangoadmin.django.elevue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
djangoadmin.django.naivevue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
```
:::tip --single-transaction 作用
@@ -44,7 +44,7 @@ mysqlbinlog --start-datetime="2026-09-05 00:00:00" \
:::tip binlog 配置
确保 MySQL 配置中启用了 binlog：
```ini
```bash
[mysqld]
server-id = 1
log-bin = mysql-bin
@@ -76,10 +76,10 @@ Redis 用于缓存和 JWT token 黑名单，数据可从数据库重建。建议
```bash
# 打包上传目录
tar -czf uploads_$(date +%Y%m%d).tar.gz /data/apps/DjangoAdmin_Django_EleVue/public/uploads/
tar -czf uploads_$(date +%Y%m%d).tar.gz /data/apps/DjangoAdmin_Django_NaiveVue/public/uploads/
# 使用 rsync 增量同步到远程
rsync -avz --delete /data/apps/DjangoAdmin_Django_EleVue/public/uploads/ backup@10.0.2.100:/data/backup/uploads/
rsync -avz --delete /data/apps/DjangoAdmin_Django_NaiveVue/public/uploads/ backup@10.0.2.100:/data/backup/uploads/
```
## 自动化备份
@@ -100,7 +100,7 @@ mkdir -p ${BACKUP_DIR}/{mysql,redis,uploads}
# MySQL 备份
mysqldump -h 127.0.0.1 -u djangoadmin -p'<密码>' \
--single-transaction djangoadmin.django.elevue | gzip > \
--single-transaction djangoadmin.django.naivevue | gzip > \
${BACKUP_DIR}/mysql/backup_${DATE}.sql.gz
# Redis 备份
@@ -110,7 +110,7 @@ cp /var/lib/redis/dump.rdb ${BACKUP_DIR}/redis/redis_${DATE}.rdb
# 上传文件备份
tar -czf ${BACKUP_DIR}/uploads/uploads_${DATE}.tar.gz \
/data/apps/DjangoAdmin_Django_EleVue/public/uploads/
/data/apps/DjangoAdmin_Django_NaiveVue/public/uploads/
# 清理过期备份
find ${BACKUP_DIR} -type f -mtime +${RETENTION_DAYS} -delete
@@ -134,10 +134,10 @@ crontab -e
```bash
# 从 SQL 文件恢复
mysql -h 127.0.0.1 -u root -p djangoadmin.django.elevue < backup_20260905.sql
mysql -h 127.0.0.1 -u root -p djangoadmin.django.naivevue < backup_20260905.sql
# 从压缩文件恢复
gunzip < backup_20260905.sql.gz | mysql -h 127.0.0.1 -u root -p djangoadmin.django.elevue
gunzip < backup_20260905.sql.gz | mysql -h 127.0.0.1 -u root -p djangoadmin.django.naivevue
```
### Redis 恢复
DjangoAdmin_Django_NaiveVue/zh/volume6/ci-cd.md
+1 -1
View File
@@ -167,7 +167,7 @@ stages:
### pytest 配置
```ini
```bash
# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = application.settings
DjangoAdmin_Django_NaiveVue/zh/volume6/db-migrate.md
+2 -14
View File
@@ -7,7 +7,6 @@
:::tip 迁移工具链
- **结构迁移**：Django 内置迁移系统（`makemigrations` + `migrate`）
- **字段注释**：Django 4.1+ 通过 `db_comment` 参数自动添加数据库字段注释
- **自定义命令**：`python manage.py add_full_comments` 回填数据库字段注释
:::
## 全新安装初始化
@@ -24,7 +23,7 @@ python manage.py migrate
```
:::tip 初始化流程
1. 确保数据库已创建：`CREATE DATABASE djangoadmin.django.elevue DEFAULT CHARACTER SET utf8mb4;`
1. 确保数据库已创建：`CREATE DATABASE djangoadmin.django.naivevue DEFAULT CHARACTER SET utf8mb4;`
2. 确保 `.env` 中的数据库配置正确
3. 执行 `python manage.py migrate` 自动创建所有表
:::
@@ -99,7 +98,7 @@ python manage.py migrate --fake example
## 字段注释管理
Django 4.1+ 支持通过 `db_comment` 参数为数据库字段添加注释。项目中的模型已自动生成 `db_comment`：
Django 4.1+ 支持通过 `db_comment` 参数为数据库字段添加注释。项目中的模型已自动生成 `db_comment`，在执行 `migrate` 时会自动同步到数据库：
```python
class Example(BaseModel):
@@ -110,16 +109,6 @@ class Example(BaseModel):
)
```
### 回填字段注释
对于已有数据库，可使用自定义命令回填字段注释：
```bash
python manage.py add_full_comments
```
该命令会遍历所有模型，为缺少注释的字段补充 `db_comment`。
## 迁移文件结构
每个应用的迁移文件位于 `application/{app_name}/migrations/` 目录：
@@ -150,7 +139,6 @@ application/example/
| 回滚指定应用 | `python manage.py migrate <app> zero` |
| 查看迁移状态 | `python manage.py showmigrations` |
| 查看迁移 SQL | `python manage.py sqlmigrate <app> <migration>` |
| 回填字段注释 | `python manage.py add_full_comments` |
## 常见问题与排错
DjangoAdmin_Django_NaiveVue/zh/volume6/deploy-checklist.md
+3 -3
View File
@@ -29,7 +29,7 @@
**数据库**：
- [ ] 安装 MySQL 8.0+
- [ ] 创建数据库：`CREATE DATABASE djangoadmin.django.elevue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
- [ ] 创建数据库：`CREATE DATABASE djangoadmin.django.naivevue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
- [ ] 创建数据库用户并授权
- [ ] 修改 `.env` 中的数据库配置（DATABASE_ENGINE、DATABASE_NAME、DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD）
- [ ] 初始化数据库：`python manage.py migrate`
@@ -144,7 +144,7 @@ server {
### 数据库迁移
- [ ] 备份数据库：`mysqldump -uroot -p djangoadmin.django.elevue > backup.sql`
- [ ] 备份数据库：`mysqldump -uroot -p djangoadmin.django.naivevue > backup.sql`
- [ ] 执行迁移：`python manage.py makemigrations && python manage.py migrate`
- [ ] 验证迁移结果
@@ -204,7 +204,7 @@ cp -r /opt/backup/dist /opt/project/ui/dist
```bash
# 从备份恢复
mysql -uroot -p djangoadmin.django.elevue < backup.sql
mysql -uroot -p djangoadmin.django.naivevue < backup.sql
```
## 总结
DjangoAdmin_Django_NaiveVue/zh/volume6/docker.md
+1 -1
View File
@@ -151,7 +151,7 @@ services:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: djangoadmin.django.elevue
MYSQL_DATABASE: djangoadmin.django.naivevue
volumes:
- mysql_data:/var/lib/mysql
ports:
DjangoAdmin_Django_NaiveVue/zh/volume6/env-plan.md
+5 -5
View File
@@ -49,7 +49,7 @@ REDIS_PASSWORD=123456
REDIS_DB=0
# 文件配置
DJANGO_FILE_URL=http://file.django.elevue
DJANGO_FILE_URL=http://file.django.naivevue
```
### Prod 环境
@@ -91,7 +91,7 @@ DJANGO_FILE_URL=https://files.example.com
```python
# config/env.py 中的配置读取方式
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.elevue')
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.naivevue')
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
```
@@ -105,12 +105,12 @@ Docker 部署时，`docker-compose.yml` 通过 `env_file: .env` 注入环境变
| 变量名 | 说明 | 默认值 |
|:----|:----|:----|
| `DJANGO_NAME` | 应用名称（显示在浏览器标题） | Django+EleVue旗舰版 |
| `DJANGO_NAME` | 应用名称（显示在浏览器标题） | Django+NaiveUI旗舰版 |
| `DJANGO_VERSION` | 应用版本号 | v3.0.0 |
| `DJANGO_DEBUG` | 调试模式开关 | True |
| `DJANGO_DEMO` | 演示模式（限制写操作） | True |
| `DATABASE_ENGINE` | 数据库引擎 | django.db.backends.mysql |
| `DATABASE_NAME` | 数据库名称 | djangoadmin.django.elevue |
| `DATABASE_NAME` | 数据库名称 | djangoadmin.django.naivevue |
| `DATABASE_HOST` | 数据库主机 | 127.0.0.1 |
| `DATABASE_PORT` | 数据库端口 | 3306 |
| `DATABASE_USER` | 数据库用户名 | root |
@@ -120,7 +120,7 @@ Docker 部署时，`docker-compose.yml` 通过 `env_file: .env` 注入环境变
| `REDIS_PORT` | Redis 端口 | 6379 |
| `REDIS_PASSWORD` | Redis 密码 | 123456 |
| `REDIS_DB` | Redis 数据库索引 | 0 |
| `DJANGO_FILE_URL` | 文件访问域名 | http://file.django.elevue |
| `DJANGO_FILE_URL` | 文件访问域名 | http://file.django.naivevue |
| `DJANGO_UPLOAD_DIR` | 文件上传目录 | /public/uploads |
| `IP_LOCATION_SOURCE` | IP 地理位置来源 | api |
| `SITE_DOMAIN` | 站点域名 | http://127.0.0.1:8000 |
DjangoAdmin_Django_NaiveVue/zh/volume6/nginx.md
+5 -5
View File
@@ -41,7 +41,7 @@ server {
gzip_vary on;
# 前端静态资源
root /data/apps/DjangoAdmin_Django_EleVue/ui/dist;
root /data/apps/DjangoAdmin_Django_NaiveVue/ui/dist;
index index.html;
location / {
@@ -70,14 +70,14 @@ server {
# Django 静态文件
location /static/ {
alias /data/apps/DjangoAdmin_Django_EleVue/public/static/;
alias /data/apps/DjangoAdmin_Django_NaiveVue/public/static/;
expires 30d;
access_log off;
}
# 上传文件访问
location /uploads/ {
alias /data/apps/DjangoAdmin_Django_EleVue/public/uploads/;
alias /data/apps/DjangoAdmin_Django_NaiveVue/public/uploads/;
expires 7d;
access_log off;
limit_except GET { deny all; }
@@ -105,8 +105,8 @@ server {
cd ui && pnpm build
# 2. 拷贝构建产物
mkdir -p /data/apps/DjangoAdmin_Django_EleVue/ui/dist
cp -r ui/dist /data/apps/DjangoAdmin_Django_EleVue/ui/
mkdir -p /data/apps/DjangoAdmin_Django_NaiveVue/ui/dist
cp -r ui/dist /data/apps/DjangoAdmin_Django_NaiveVue/ui/
# 3. 收集 Django 静态文件
python manage.py collectstatic
DjangoAdmin_Django_NaiveVue/zh/volume6/scaling.md
+1 -1
View File
@@ -239,7 +239,7 @@ class MasterSlaveRouter:
## Supervisor 多实例配置
```ini
```bash
; /etc/supervisor/conf.d/djangoadmin.conf
[program:djangoadmin-1]
command=/opt/venv/bin/gunicorn application.wsgi:application -c gunicorn.conf.py -b 127.0.0.1:8001
DjangoAdmin_Django_NaiveVue/zh/volume6/supervisor.md
+6 -6
View File
@@ -12,7 +12,7 @@ Supervisor 是一个 Python 编写的进程管理工具，用于在 Linux 服务
## 配置文件示例
```ini
```bash
; Supervisor 进程管理配置
; 将 command / directory 替换为实际路径后复制到 /etc/supervisor/conf.d/
@@ -20,7 +20,7 @@ Supervisor 是一个 Python 编写的进程管理工具，用于在 Linux 服务
; 启动命令：使用 gunicorn 运行 Django WSGI 应用
command=/path/to/venv/bin/gunicorn application.wsgi:application --bind 127.0.0.1:8000 --workers 4 --timeout 120
; 项目根目录
directory=/data/apps/DjangoAdmin_Django_EleVue
directory=/data/apps/DjangoAdmin_Django_NaiveVue
; 自动启动
autostart=true
; 异常退出后自动重启
@@ -134,7 +134,7 @@ gunicorn application.wsgi:application \
Supervisor 内置日志轮转功能，通过以下配置控制：
```ini
```bash
; 单个日志文件最大 50MB
stdout_logfile_maxbytes=50MB
; 保留 10 个历史日志文件
@@ -153,16 +153,16 @@ stdout_logfile_backups=10
如需同时管理多个进程（如应用 + Celery Worker）：
```ini
```bash
[program:djangoadmin]
command=/path/to/venv/bin/gunicorn application.wsgi:application --bind 127.0.0.1:8000 --workers 4
directory=/data/apps/DjangoAdmin_Django_EleVue
directory=/data/apps/DjangoAdmin_Django_NaiveVue
autostart=true
autorestart=true
[program:djangoadmin-celery]
command=/path/to/venv/bin/celery -A application worker -l info
directory=/data/apps/DjangoAdmin_Django_EleVue
directory=/data/apps/DjangoAdmin_Django_NaiveVue
autostart=true
autorestart=true
numprocs=2
DjangoAdmin_Django_NaiveVue/zh/volume6/troubleshooting.md
+2 -2
View File
@@ -170,8 +170,8 @@ pip show Pillow
```bash
# 1. 检查上传目录权限
ls -la /data/apps/DjangoAdmin_Django_EleVue/public/uploads/
chmod 755 /data/apps/DjangoAdmin_Django_EleVue/public/uploads/
ls -la /data/apps/DjangoAdmin_Django_NaiveVue/public/uploads/
chmod 755 /data/apps/DjangoAdmin_Django_NaiveVue/public/uploads/
# 2. 检查磁盘空间
df -h
DjangoAdmin_Django_NaiveVue/zh/volume6/upgrade.md
+5 -5
View File
@@ -18,15 +18,15 @@
```bash
# 1. 数据库全量备份
mysqldump -h 127.0.0.1 -u root -p --single-transaction \
djangoadmin.django.elevue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
djangoadmin.django.naivevue | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
# 2. 上传文件备份
tar -czf uploads_$(date +%Y%m%d).tar.gz /data/apps/DjangoAdmin_Django_EleVue/public/uploads/
tar -czf uploads_$(date +%Y%m%d).tar.gz /data/apps/DjangoAdmin_Django_NaiveVue/public/uploads/
# 3. 应用目录备份（含 .env 和配置）
tar -czf app_$(date +%Y%m%d).tar.gz \
--exclude='uploads' --exclude='__pycache__' --exclude='.git' \
/data/apps/DjangoAdmin_Django_EleVue/
/data/apps/DjangoAdmin_Django_NaiveVue/
```
### 查看变更日志
@@ -54,7 +54,7 @@ git diff --stat HEAD~10
### 步骤一：拉取代码
```bash
cd /data/apps/DjangoAdmin_Django_EleVue
cd /data/apps/DjangoAdmin_Django_NaiveVue
# 拉取最新代码
git fetch origin
@@ -174,7 +174,7 @@ cd /data/apps/
tar -xzf app_20260905.tar.gz
# 3. 恢复数据库
gunzip < backup_20260905.sql.gz | mysql -u root -p djangoadmin.django.elevue
gunzip < backup_20260905.sql.gz | mysql -u root -p djangoadmin.django.naivevue
# 4. 恢复上传文件
tar -xzf uploads_20260905.tar.gz -C /
DjangoAdmin_Django_NaiveVue/zh/volume7/fe-component.md
+100 -75
View File
@@ -2,11 +2,11 @@
## 概述
前端基于 Vue3 + ElementPlus + 自定义组件库构建。页面统一使用 `PageWrapper` + `BasicForm` + `BasicTable` + `TableAction` 四件套，分页由 `BasicTable` 内置处理，无需单独引入分页组件。
前端基于 Vue3 + NaiveUI + 自定义组件库构建。页面统一使用 `n-card` + `BasicForm` + `BasicTable` + `TableAction` 组件组合，分页由 `BasicTable` 内置处理，无需单独引入分页组件。
:::tip 技术栈
- Vue3（Composition API + `<script setup>`）
- ElementPlus 2.x
- NaiveUI
- 自定义组件（BasicTable / BasicForm / TableAction / PageWrapper）
- Pinia 状态管理
- Vue Router 路由管理
@@ -56,7 +56,7 @@ ui/src/
├── utils/ # 工具函数
├── hooks/ # 组合式函数
├── styles/ # 全局样式
├── plugins/ # 插件注册（ElementPlus、自定义组件、指令）
├── plugins/ # 插件注册（NaiveUI、自定义组件、指令）
└── main.ts # 入口文件
```
@@ -77,48 +77,52 @@ ui/src/
```vue
<template>
<PageWrapper>
<div>
<!-- 搜索表单 -->
<el-card :bordered="false" class="pt-3 mb-3 proCard">
<n-card :bordered="false" class="pt-3 mb-3 proCard">
<BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
</el-card>
</n-card>
<!-- 数据表格 -->
<el-card :bordered="false" class="proCard">
<n-card :bordered="false" class="proCard">
<BasicTable
:columns="columns"
:request="loadDataTable"
:row-key="(row) => row.id"
ref="tableRef"
ref="basicTableRef"
:actionColumn="actionColumn"
@selection-change="onSelectionChange"
@update:checked-row-keys="onCheckedRow"
:auto-scroll-x="true"
>
<template #tableTitle>
<el-button type="primary" @click="handleAdd" v-perm="['sys:param:add']">
<el-icon><PlusOutlined /></el-icon>
添加参数
</el-button>
<el-button
type="danger"
@click="handleDelete()"
:disabled="!selectionData.length"
v-perm="['sys:param:batchDelete']"
>
<el-icon><Delete /></el-icon>
删除
</el-button>
<n-space>
<n-button type="primary" @click="handleAdd" v-perm="['sys:param:add']">
<template #icon><n-icon><PlusOutlined /></n-icon></template>
添加参数
</n-button>
<n-button
type="error"
@click="handleDelete()"
:disabled="!rowKeys.length"
v-perm="['sys:param:batchDelete']"
>
<template #icon><n-icon><DeleteOutlined /></n-icon></template>
删除
</n-button>
</n-space>
</template>
</BasicTable>
</el-card>
</n-card>
<!-- 编辑弹窗（懒加载） -->
<!-- 编辑弹窗 -->
<editDialog
ref="editModalRef"
v-if="editVisible"
:paramId="paramId"
v-model:visible="editVisible"
@success="reloadTable('noRefresh')"
/>
</PageWrapper>
</div>
</template>
```
@@ -133,37 +137,37 @@ ui/src/
```typescript
// views/data/param/columns.ts
import { h } from 'vue';
import { ElTag } from 'element-plus';
import { NTag } from 'naive-ui';
export const columns = [
{ type: 'selection' }, // 多选列
{ label: 'ID', prop: 'id', width: 50 }, // 固定列
{ label: '参数名称', prop: 'name', minWidth: 200 },
{ label: '参数编码', prop: 'code', minWidth: 250 },
{ label: '参数值', prop: 'value', minWidth: 200 },
{ type: 'selection', width: 50, fixed: 'left' }, // 多选列
{ title: 'ID', key: 'id', width: 50 }, // 固定列
{ title: '参数名称', key: 'name', width: 200 },
{ title: '参数编码', key: 'code', width: 250 },
{ title: '参数值', key: 'value', width: 200 },
{
label: '参数类型',
prop: 'type',
minWidth: 100,
title: '参数类型',
key: 'type',
width: 100,
render(record) {
return h(ElTag,
{ type: record.row.type == 0 ? 'primary' : 'warning' },
{ default: () => (record.row.type == 0 ? '系统' : '业务') }
return h(NTag,
{ bordered: false, type: record.type == 0 ? 'info' : 'warning' },
{ default: () => (record.type == 0 ? '系统' : '业务') }
);
},
},
{
label: '状态',
prop: 'status',
minWidth: 100,
title: '状态',
key: 'status',
width: 100,
render(record) {
return h(ElTag,
{ type: record.row.status == 1 ? 'success' : 'danger' },
{ default: () => (record.row.status == 1 ? '正常' : '禁用') }
return h(NTag,
{ bordered: false, type: record.status == 1 ? 'success' : 'error' },
{ default: () => (record.status == 1 ? '正常' : '禁用') }
);
},
},
{ label: '创建时间', prop: 'createTime', width: 180 },
{ title: '创建时间', key: 'createTime', width: 180 },
];
```
@@ -172,17 +176,17 @@ export const columns = [
```typescript
// 状态标签
render(record) {
return h(ElTag,
{ type: record.row.status == 1 ? 'success' : 'danger' },
{ default: () => record.row.statusText } // 使用后端 serialize_maps 返回的 xxxText
return h(NTag,
{ bordered: false, type: record.status == 1 ? 'success' : 'error' },
{ default: () => record.statusText } // 使用后端 serialize_maps 返回的 xxxText
);
}
// 链接
render(record) {
return h('a',
{ href: record.row.url, target: '_blank', class: 'text-blue-500' },
{ default: () => record.row.url }
{ href: record.url, target: '_blank', class: 'text-blue-500' },
{ default: () => record.url }
);
}
```
@@ -196,13 +200,13 @@ import { FormSchema } from '@/components/Form/index';
export const schemas: FormSchema[] = [
{
field: 'name',
component: 'Input',
component: 'NInput',
label: '参数名称',
componentProps: { placeholder: '请输入参数名称' },
},
{
field: 'type',
component: 'Select',
component: 'NSelect',
label: '参数类型',
componentProps: {
placeholder: '请选择参数类型',
@@ -215,7 +219,7 @@ export const schemas: FormSchema[] = [
},
{
field: 'status',
component: 'Select',
component: 'NSelect',
label: '状态',
componentProps: {
placeholder: '请选择状态',
@@ -232,26 +236,30 @@ export const schemas: FormSchema[] = [
## 操作栏（TableAction）
```typescript
import { FormOutlined, DeleteOutlined } from '@vicons/antd';
import { renderIcon } from '@/utils';
const actionColumn = reactive({
width: 200,
label: '操作',
prop: 'action',
title: '操作',
align: 'center',
key: 'action',
fixed: 'right',
render(record) {
return h(TableAction, {
return h(TableAction as any, {
style: 'button',
actions: [
{
label: '编辑',
icon: 'Edit',
type: 'warning',
icon: renderIcon(FormOutlined),
type: 'info',
onClick: handleEdit.bind(null, record),
auth: ['sys:param:update'],
},
{
label: '删除',
icon: 'Delete',
type: 'danger',
icon: renderIcon(DeleteOutlined),
type: 'error',
onClick: handleDelete.bind(null, record),
auth: ['sys:param:delete'],
},
@@ -325,11 +333,12 @@ function handleReset() {
## 编辑弹窗（edit.vue）
编辑弹窗通过 `defineAsyncComponent` 懒加载，使用 `v-model:visible` 控制显示：
编辑弹窗使用 `basicModal` + `useModal` 模式，通过 `v-model:visible` 控制显示：
```vue
<!-- index.vue 中引用 -->
<editDialog
ref="editModalRef"
v-if="editVisible"
:paramId="paramId"
v-model:visible="editVisible"
@@ -338,42 +347,58 @@ function handleReset() {
```
```typescript
// 懒加载编辑组件
const editDialog = defineAsyncComponent(() => import('./edit.vue'));
import editDialog from './edit.vue';
// 新增
const handleAdd = async () => {
paramId.value = 0;
await nextTick();
editVisible.value = true;
await nextTick();
editModalRef.value?.openModal();
};
// 编辑
const handleEdit = async (record: Recordable) => {
paramId.value = record.row.id;
await nextTick();
paramId.value = record.id;
editVisible.value = true;
await nextTick();
editModalRef.value?.openModal();
};
```
## 删除（单条 + 批量）
```typescript
async function handleDelete(record: Recordable) {
import { useMessage, useDialog } from 'naive-ui';
const message = useMessage();
const dialog = useDialog();
async function handleDelete(record?: Recordable) {
let ids = [];
if (!record) {
// 批量删除：取多选行的 ID
ids = selectionData.value.map(({ id }) => id);
ids = rowKeys.value;
if (!ids.length) {
message.warning('请选择要删除的数据');
return;
}
}
await confirm('确定要删除？');
record ? await paramDelete(record.row.id) : await paramBatchDelete(ids);
message('删除成功');
reloadTable();
dialog.warning({
title: '提示',
content: '确定要删除？',
positiveText: '确定',
negativeText: '取消',
onPositiveClick: async () => {
record ? await paramDelete(record.id) : await paramBatchDelete(ids);
message.success('删除成功');
reloadTable();
},
});
}
// 多选变化
function onSelectionChange(value) {
selectionData.value = value;
function onCheckedRow(keys: (string | number)[]) {
rowKeys.value = keys;
}
```
@@ -388,4 +413,4 @@ function onSelectionChange(value) {
## 总结
前端页面统一使用 `PageWrapper` + `BasicForm` + `BasicTable` + `TableAction` 四件套。分页由 `BasicTable` 内置处理，无需单独引入分页组件。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）四个文件。API 接口按模块分文件定义在 `api/` 目录下。
前端页面统一使用 `n-card` + `BasicForm` + `BasicTable` + `TableAction` 组件组合。分页由 `BasicTable` 内置处理，无需单独引入分页组件。每个模块包含 `index.vue`（列表页）、`edit.vue`（编辑弹窗）、`columns.ts`（列定义）、`querySchemas.ts`（搜索配置）四个文件。API 接口按模块分文件定义在 `api/` 目录下。
DjangoAdmin_Django_NaiveVue/zh/why.md
+3 -3
View File
@@ -91,13 +91,13 @@ class ExamplePageView(PermissionRequired, View):
这些模块不仅可以直接使用，也是学习本框架开发模式的最佳参考。
## Vue3 + ElementPlus 前端
## Vue3 + NaiveUI 前端
前端采用主流技术栈，开发体验优秀：
- **Vue3 Composition API**：更灵活的组件逻辑组织
- **TypeScript**：类型安全，减少运行时错误
- **ElementPlus**：成熟的企业级 UI 组件库
- **NaiveUI**：成熟的企业级 UI 组件库
- **Pinia**：轻量级状态管理，替代 Vuex
- **Vite**：极速的开发服务器和构建工具
- **动态路由**：菜单和路由由后端驱动，前端无需硬编码
@@ -143,7 +143,7 @@ cd ui && pnpm install && pnpm dev
项目持续迭代，紧跟技术发展：
- Django 版本持续升级至 6.0.3
- 前端从 Vue 2 升级到 Vue3 + ElementPlus
- 前端从 Vue 2 升级到 Vue3 + NaiveUI
- 代码生成器功能不断增强
- 安全机制持续完善