签入版本

2026-10-11 19:06:33 +08:00
parent 17d28de8b7
commit 4084c6bd17
674 changed files with 58855 additions and 1892 deletions
@@ -141,14 +141,11 @@ export function getDictItemByCode(code) {

 ```vue
 <template>
-  <el-select v-model="formData.status" placeholder="请选择状态">
-    <el-option
-      v-for="item in statusOptions"
-      :key="item.value"
-      :label="item.name"
-      :value="item.value"
-    />
-  </el-select>
+  <n-select
+    v-model:value="formData.status"
+    :options="statusOptions"
+    placeholder="请选择状态"
+  />
 </template>

 <script setup>
@@ -158,7 +155,9 @@ import { getDictItemByCode } from '@/api/common/index';
 const statusOptions = ref([]);

 onMounted(async () => {
-  statusOptions.value = await getDictItemByCode('example_status');
+  const list = await getDictItemByCode('example_status');
+  // n-select 的 options 需要 { label, value } 结构
+  statusOptions.value = list.map((item) => ({ label: item.name, value: item.value }));
 });
 </script>
 ```
@@ -86,7 +86,11 @@
 ## 前端错误处理

 ```typescript
-// Axios 响应拦截器
+// Axios 响应拦截器（ui/src/utils/http/axios/index.ts）
+import { useMessage } from '@/hooks/web/useMessage';
+
+const $message = useMessage();
+
 axios.interceptors.response.use(response => {
    const { code, msg, data } = response.data;

@@ -101,12 +105,12 @@ axios.interceptors.response.use(response => {
    }

    if (code === 403 || response.status === 403) {
-        ElMessage.error(msg || '无权限');
+        $message.error(msg || '无权限');
        return;
    }

    // 其他错误
-    ElMessage.error(msg || '操作失败');
+    $message.error(msg || '操作失败');
    return Promise.reject(new Error(msg));
 });
 ```
@@ -267,6 +267,9 @@ Result::validateError(['name' => ['名称不能为空']]);

 ```typescript
 // ui/src/utils/http/axios/index.ts
+import { useMessage } from '@/hooks/web/useMessage';
+
+const $message = useMessage();

 axios.interceptors.response.use(
    response => {
@@ -286,16 +289,16 @@ axios.interceptors.response.use(

        // 权限不足
        if (code === 403 || response.status === 403) {
-            ElMessage.error(msg || '无访问权限');
+            $message.error(msg || '无访问权限');
            return Promise.reject(new Error(msg));
        }

        // 其他业务错误
-        ElMessage.error(msg || '操作失败');
+        $message.error(msg || '操作失败');
        return Promise.reject(new Error(msg));
    },
    error => {
-        ElMessage.error('网络错误');
+        $message.error('网络错误');
        return Promise.reject(error);
    }
 );
@@ -316,13 +319,17 @@ const fetchData = async () => {
 ### 处理导入结果

 ```typescript
+import { useMessage } from '@/hooks/web/useMessage';
+
+const $message = useMessage();
+
 const handleImport = async (file) => {
    const res = await importUsers(file);
    // res = { count: 8, errors: [{ row: 3, name: "...", reason: "..." }] }
    if (res.errors.length === 0) {
-        ElMessage.success(`成功导入 ${res.count} 条`);
+        $message.success(`成功导入 ${res.count} 条`);
    } else {
-        ElMessage.warning(`成功 ${res.count} 条，失败 ${res.errors.length} 条`);
+        $message.warning(`成功 ${res.count} 条，失败 ${res.errors.length} 条`);
    }
 };
 ```
@@ -164,11 +164,11 @@ Authorization: Bearer <access_token>

 ```bash
 # curl
-curl http://localhost:8000/api/user/page \
+curl http://admin.laravel13.naivevue/api/user/page \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

 # curl（带分页参数）
-curl "http://localhost:8000/api/user/page?pageNo=1&pageSize=10" \
+curl "http://admin.laravel13.naivevue/api/user/page?pageNo=1&pageSize=10" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
 ```

@@ -400,17 +400,26 @@ config.headers['Authorization'] = `Bearer ${token}`;
 ### 响应拦截器（401 处理，摘自 `ui/src/utils/http/axios/index.ts`）

 ```typescript
+import { useDialog } from '@/hooks/web/useDialog';
+
+const $dialog = useDialog();
+
 // code === 401（ResultEnum.TIMEOUT）
 case ResultEnum.TIMEOUT:
  if (router.currentRoute.value?.name === PageEnum.BASE_LOGIN_NAME) return;
-  ElMessageBox.confirm('登录身份已失效，请重新登录!', '提示', {
-    type: 'warning',
-  })
-    .then(() => {
+  $dialog.warning({
+    title: '提示',
+    content: '登录身份已失效，请重新登录!',
+    positiveText: '确定',
+    //negativeText: '取消',
+    closable: false,
+    maskClosable: false,
+    onPositiveClick: () => {
      storage.clear();
      window.location.href = PageEnum.BASE_LOGIN;   // '/login'
-    })
-    .catch(() => {});
+    },
+    onNegativeClick: () => {},
+  });
  break;
 ```

@@ -32,7 +32,7 @@
    "ok": true,
    "msg": "上传成功",
    "data": {
-        "fileUrl": "http://localhost:8000/uploads/temp/20261002/123456_a1b2c3d4e5f6.jpg",
+        "fileUrl": "http://admin.laravel13.naivevue/uploads/temp/20261002/123456_a1b2c3d4e5f6.jpg",
        "filePath": "temp/20261002/123456_a1b2c3d4e5f6.jpg",
        "originalName": "photo.jpg",
        "fileSize": 102400,
@@ -47,7 +47,7 @@

 | 字段 | 类型 | 说明 | 示例 |
 |------|------|------|------|
-| `fileUrl` | string | 可访问 URL（`FILE_DOMAIN_URL` 为空时等于相对路径） | `http://localhost:8000/uploads/temp/...` |
+| `fileUrl` | string | 可访问 URL（`FILE_DOMAIN_URL` 为空时等于相对路径） | `http://admin.laravel13.naivevue/uploads/temp/...` |
 | `filePath` | string | 相对存储路径（**提交表单建议用此字段**） | `temp/20261002/123456_a1b2....jpg` |
 | `originalName` | string | 原始文件名 | `photo.jpg` |
 | `fileSize` | number | 文件大小（字节） | `102400` |
@@ -102,57 +102,70 @@ gif, jpg, jpeg, png, bmp, webp

 ## 前端使用

-### Element Plus Upload 组件
+### NaiveUI 上传组件（n-upload）

 ```vue
 <template>
  <!-- 上传文件（默认 type=file） -->
-  <el-upload
+  <n-upload
    :action="'/api/upload/uploadFile'"
-    :headers="{ Authorization: `Bearer ${token}` }"
-    :on-success="handleUploadSuccess"
-    :before-upload="beforeUpload"
+    :headers="uploadHeaders"
+    @before-upload="beforeUpload"
+    @finish="handleUploadFinish"
  >
-    <el-button type="primary">上传文件</el-button>
-  </el-upload>
+    <n-button type="primary">上传文件</n-button>
+  </n-upload>

  <!-- 上传图片（指定 type=image） -->
-  <el-upload
+  <n-upload
    :action="'/api/upload/uploadFile?type=image'"
-    :data="{ type: 'image' }"
-    :headers="{ Authorization: `Bearer ${token}` }"
-    :on-success="handleImageSuccess"
+    :headers="uploadHeaders"
    accept="image/*"
+    @finish="handleImageFinish"
  >
-    <el-button type="primary">上传图片</el-button>
-  </el-upload>
+    <n-button type="primary">上传图片</n-button>
+  </n-upload>
 </template>

 <script setup>
+import { useMessage } from '@/hooks/web/useMessage';
+
+const $message = useMessage();
 const token = localStorage.getItem('access_token');
+const uploadHeaders = { Authorization: `Bearer ${token}` };

-const beforeUpload = (file) => {
-  const isLt10M = file.size / 1024 / 1024 < 10;
+// n-upload 的 before-upload 参数为 { file }，原生文件对象在 file.file
+const beforeUpload = ({ file }) => {
+  const isLt10M = file.file.size / 1024 / 1024 < 10;
  if (!isLt10M) {
-    ElMessage.error('文件大小不能超过 10MB');
+    $message.error('文件大小不能超过 10MB');
+    return false;
  }
-  return isLt10M;
+  return true;
 };

-const handleUploadSuccess = (response) => {
-  if (response.code === 0) {
-    form.value.file = response.data.filePath;   // 建议存相对路径
+// 上传结束，解析原始响应（n-upload 的 finish 事件拿到 event）
+const parseResponse = (event) => {
+  const data = JSON.parse(event.target.response);
+  if (data.code === 0) {
+    return data.data.filePath;   // 建议存相对路径
  }
+  $message.error(data.msg || '上传失败');
+  return null;
 };

-const handleImageSuccess = (response) => {
-  if (response.code === 0) {
-    form.value.avatar = response.data.filePath;
-  }
+const handleUploadFinish = ({ event }) => {
+  form.value.file = parseResponse(event);
+};
+
+const handleImageFinish = ({ event }) => {
+  form.value.avatar = parseResponse(event);
 };
 </script>
 ```

+项目内也可直接使用封装组件 `BasicUpload`（`ui/src/components/Upload/`，内嵌 `n-upload`，自带大小/类型校验与 `useMessage` 错误提示），图片字段用 `UploadImg`（`ui/src/components/Upload/Image.vue`）。
+
 ### 手动上传

 ```typescript
@@ -167,7 +180,7 @@ const res = await http.request({
    headers: { 'Content-Type': 'multipart/form-data' },
 });
 // res.filePath = "temp/20261002/123456_a1b2....jpg"
-// res.fileUrl  = "http://localhost:8000/uploads/temp/20261002/..."
+// res.fileUrl  = "http://admin.laravel13.naivevue/uploads/temp/20261002/..."

 // 上传图片（指定 type=image）
 const res2 = await http.request({
@@ -199,27 +212,21 @@ await exampleAdd({
 ```vue
 <template>
  <div class="avatar-upload">
-    <el-avatar :src="form.avatar" :size="80" />
-    <el-upload
-      :action="'/api/upload/uploadFile?type=image'"
-      :headers="{ Authorization: `Bearer ${token}` }"
-      :show-file-list="false"
-      :on-success="handleAvatarSuccess"
-      accept="image/*"
+    <n-avatar :src="form.avatar" :size="80" />
+    <UploadImg
+      v-model:image-url="form.avatar"
+      :fileType="['image/jpeg', 'image/png', 'image/jpg', 'image/gif', 'image/webp']"
+      :fileSize="10"
    >
-      <el-button size="small">更换头像</el-button>
-    </el-upload>
+      <template #tip>支持扩展名: jpg png jpeg gif webp; 文件大小不超过10M</template>
+    </UploadImg>
  </div>
 </template>

 <script setup>
-const form = ref({ avatar: '' });
+import UploadImg from '@/components/Upload/Image.vue';

-const handleAvatarSuccess = (response) => {
-  if (response.code === 0) {
-    form.value.avatar = response.data.filePath;
-  }
-};
+const form = ref({ avatar: '' });
 </script>
 ```