Vue3 on 404_@林达

Vue3 图片上传与本地预览的常见写法

Wed, 18 Mar 2026 00:00:00 +0000

图片上传通常不只是把文件传到接口：用户还需要在提交前看到预览图，前端需要拦住错误格式和过大的文件，替换图片或离开页面时也要释放浏览器临时创建的地址。

下面用 el-upload 做一个单图上传的基础版本。

先在选择文件时做校验

把校验抽成一个函数，既可以在选择文件时调用，也可以在真正请求前再执行一次。前端校验主要是避免用户走到无效的提交步骤。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


import { ElMessage } from 'element-plus'
import type { UploadRawFile } from 'element-plus'

const validateImage = (rawFile: UploadRawFile) => {
 const allowedTypes = ['image/jpeg', 'image/png', 'image/webp']
 const isImage = allowedTypes.includes(rawFile.type)
 const isLt2M = rawFile.size / 1024 / 1024 < 2

 if (!isImage) {
 ElMessage.error('请上传 JPG、PNG 或 WebP 图片')
 return false
 }

 if (!isLt2M) {
 ElMessage.error('图片大小不能超过 2MB')
 return false
 }

 return true
}

前端校验只是体验层。后端仍然要校验文件类型、大小和实际内容，不能只相信文件扩展名。

用 Object URL 做本地预览

URL.createObjectURL 可以在不上传文件的情况下生成浏览器可访问的临时地址。替换图片时先释放旧地址，避免长时间操作后积累无用的内存引用。选择无效文件时，同时清空上传列表。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'
import type { UploadFile, UploadRawFile, UploadUserFile } from 'element-plus'

const previewUrl = ref('')
const fileList = ref<UploadUserFile[]>([])
let objectUrl = ''

const revokePreviewUrl = () => {
 if (!objectUrl) return
 URL.revokeObjectURL(objectUrl)
 objectUrl = ''
}

const handleChange = (uploadFile: UploadFile) => {
 const file = uploadFile.raw
 if (!file) return

 if (!validateImage(file)) {
 fileList.value = []
 previewUrl.value = ''
 return
 }

 revokePreviewUrl()
 objectUrl = URL.createObjectURL(file)
 previewUrl.value = objectUrl
}

onBeforeUnmount(revokePreviewUrl)
</script>

<template>
 <el-upload
 :auto-upload="false"
 :limit="1"
 v-model:file-list="fileList"
 accept="image/jpeg,image/png,image/webp"
 :on-change="handleChange"
 >
 <el-button type="primary">选择图片</el-button>
 </el-upload>

 <img v-if="previewUrl" :src="previewUrl" alt="上传图片预览" class="preview" />
</template>

<style scoped>
.preview {
 display: block;
 width: 160px;
 height: 160px;
 margin-top: 16px;
 object-fit: cover;
 border-radius: 8px;
}
</style>

如果页面只需要展示已有的远程头像，直接赋值接口返回的 URL 即可；只有本地刚选择的文件才需要 createObjectURL。

用 FormData 提交文件

当表单同时包含文本和文件时，使用 FormData。浏览器会自动补充 multipart/form-data 的边界，因此不要手动给请求头设置 Content-Type。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


const submitAvatar = async (file: File) => {
 const formData = new FormData()
 formData.append('avatar', file)
 formData.append('nickname', '林达')

 const response = await fetch('/api/profile/avatar', {
 method: 'POST',
 body: formData,
 })

 if (!response.ok) {
 throw new Error('上传失败，请稍后重试')
 }

 return response.json()
}

接口成功后，应使用服务端返回的正式图片地址替换本地预览地址。这样刷新页面后，用户仍然能看到已保存的图片。

容易忽略的细节

用 accept 限制文件选择器，但不要把它当成安全校验。
单图上传要设置 limit="1"，替换时同步清理旧预览。
预览图建议设置固定宽高和 object-fit: cover，避免不同尺寸图片撑坏布局。
上传过程中禁用重复提交，接口失败时给出明确提示。

小结

一个稳定的图片上传流程，至少包括选择前校验、选择后预览、提交时使用 FormData、成功后替换正式 URL，以及离开页面时释放临时地址。把这些细节补齐后，头像、封面图和后台图片字段都可以复用同一套思路。

Element Plus 表格分页、序号与请求状态整理

Sat, 07 Feb 2026 00:00:00 +0000

列表页是后台项目最常见的页面之一。表格、分页、筛选、加载状态一起出现后，问题往往不是“表格能不能显示”，而是换页后序号不连续、重复请求、页码没有重置，或者前端排序和服务端分页混在一起。

跨页连续序号怎么算

el-table-column 的 type="index" 默认会从 1 开始重新编号。要显示跨页连续序号，可以给它传一个函数：

1

<el-table-column type="index" label="序号" :index="getIndex" width="72" />

1
2
3


const getIndex = (index: number) => {
 return (currentPage.value - 1) * pageSize.value + index + 1
}

例如当前是第 3 页、每页 20 条，当前页第一行的 index 是 0，最终序号就是 41。

一个可复用的分页列表

下面的例子把页码、每页数量、总数和加载状态放在一起管理。筛选条件变化后回到第 1 页，再重新请求数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77


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

interface User {
 id: number
 name: string
 status: 'enabled' | 'disabled'
}

const rows = ref<User[]>([])
const total = ref(0)
const currentPage = ref(1)
const pageSize = ref(20)
const keyword = ref('')
const loading = ref(false)

const getIndex = (index: number) => {
 return (currentPage.value - 1) * pageSize.value + index + 1
}

const loadUsers = async () => {
 loading.value = true

 try {
 const params = new URLSearchParams({
 page: String(currentPage.value),
 pageSize: String(pageSize.value),
 keyword: keyword.value,
 })
 const response = await fetch(`/api/users?${params}`)
 const data = await response.json()

 rows.value = data.list
 total.value = data.total
 } finally {
 loading.value = false
 }
}

const search = () => {
 currentPage.value = 1
 loadUsers()
}

const changePageSize = () => {
 currentPage.value = 1
 loadUsers()
}

onMounted(loadUsers)
</script>

<template>
 <el-input
 v-model="keyword"
 clearable
 placeholder="按用户名搜索"
 @keyup.enter="search"
 />

 <el-table v-loading="loading" :data="rows" row-key="id">
 <el-table-column type="index" label="序号" :index="getIndex" width="72" />
 <el-table-column prop="name" label="用户名" min-width="160" />
 <el-table-column prop="status" label="状态" width="120" />
 </el-table>

 <el-pagination
 v-model:current-page="currentPage"
 v-model:page-size="pageSize"
 :page-sizes="[10, 20, 50, 100]"
 :total="total"
 background
 layout="total, sizes, prev, pager, next"
 @current-change="loadUsers"
 @size-change="changePageSize"
 />
</template>

loading 要在 finally 中关闭。无论请求成功还是失败，页面都不会一直停在加载状态。

筛选后为什么要重置页码

用户本来在第 8 页，搜索条件一变，新的结果可能只有 1 页。如果继续带着第 8 页请求，列表就会空掉。因此所有会改变结果集的筛选项，都应该先执行：

1
2


currentPage.value = 1
loadUsers()

服务端分页时，排序也交给服务端

如果表格数据来自分页接口，前端只拿到当前页的 20 条数据。此时直接在前端对这 20 条排序，得到的并不是全量排序结果。

可以监听 sort-change，把字段名和顺序传回接口：

1
2
3


<el-table @sort-change="handleSortChange">
 <el-table-column prop="createdAt" label="创建时间" sortable="custom" />
</el-table>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const sortBy = ref('createdAt')
const sortOrder = ref<'ascending' | 'descending' | ''>('descending')

const handleSortChange = ({ prop, order }: {
 prop: string
 order: 'ascending' | 'descending' | null
}) => {
 sortBy.value = prop
 sortOrder.value = order ?? ''
 currentPage.value = 1
 loadUsers()
}

小结

表格页真正需要统一管理的是请求参数和页面状态：页码、每页数量、筛选条件、排序条件、总数与加载状态。把这些状态放在同一处后，分页和表格才不会各自运行、互相打架。

Element Plus 表单校验常见写法

Tue, 06 May 2025 00:00:00 +0000

后台项目里，新增和编辑弹窗大多离不开 el-form。表单校验看起来简单，真正容易出问题的地方通常是 model、prop、rules 三者没有对齐，或者弹窗复用后遗留了上一次的校验状态。

最小可用的表单结构

el-form 的 :model 指向表单数据；每个 el-form-item 的 prop 必须与数据字段、规则字段一致。下面的 name 和 email 三处都对应同一个字段名。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


<script setup lang="ts">
import { reactive, ref } from 'vue'
import type { FormInstance, FormRules } from 'element-plus'

interface UserForm {
 name: string
 email: string
}

const formRef = ref<FormInstance>()
const form = reactive<UserForm>({
 name: '',
 email: '',
})

const rules: FormRules<UserForm> = {
 name: [
 { required: true, message: '请输入用户名', trigger: 'blur' },
 { min: 2, max: 20, message: '长度为 2 到 20 个字符', trigger: 'blur' },
 ],
 email: [
 { required: true, message: '请输入邮箱', trigger: 'blur' },
 { type: 'email', message: '邮箱格式不正确', trigger: ['blur', 'change'] },
 ],
}
</script>

<template>
 <el-form ref="formRef" :model="form" :rules="rules" label-width="80px">
 <el-form-item label="用户名" prop="name">
 <el-input v-model="form.name" placeholder="请输入用户名" />
 </el-form-item>

 <el-form-item label="邮箱" prop="email">
 <el-input v-model="form.email" placeholder="name@example.com" />
 </el-form-item>
 </el-form>
</template>

如果 prop="userName"，而 form 写的是 name，规则不会生效。这是排查校验问题时最先该看的地方。

提交前统一校验

不要只依赖输入框失焦时的提示。提交按钮仍然要执行一次 validate，确认所有字段都通过后再调接口。

1
2
3
4
5
6
7


const submit = async () => {
 const valid = await formRef.value?.validate().catch(() => false)

 if (!valid) return

 await saveUser({ ...form })
}

validate 校验失败时会抛出异常，所以这里用 catch 转成 false。通过后再复制一份数据提交，可以避免接口函数直接修改响应式对象。

编辑弹窗要清掉旧提示

一个弹窗既用于新增又用于编辑时，切换数据后经常会看到上一位用户留下的红色提示。可以在弹窗打开后清掉校验状态。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import { nextTick } from 'vue'

const openCreate = async () => {
 Object.assign(form, { name: '', email: '' })
 await nextTick()
 formRef.value?.clearValidate()
}

const openEdit = async (user: UserForm) => {
 Object.assign(form, user)
 await nextTick()
 formRef.value?.clearValidate()
}

如果表单初始值始终不变，也可以使用 formRef.value?.resetFields()。它会把数据还原为组件初始化时的值，更适合单纯的“清空新增表单”。

只校验一个字段

分步表单或者发送验证码前，往往只需要校验邮箱或手机号。这时用 validateField，不必校验整张表单。

1
2
3
4
5
6


const sendCode = async () => {
 const valid = await formRef.value?.validateField('email').catch(() => false)

 if (!valid) return
 await requestEmailCode(form.email)
}

自定义规则适合什么场景

确认密码、日期范围、业务编号唯一性等情况，内置规则不够用时可以增加 validator。校验函数只负责给出结果，不要在里面请求大量无关数据。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


const passwordForm = reactive({
 password: '',
 confirmPassword: '',
})

const validateConfirmPassword = (
 _rule: unknown,
 value: string,
 callback: (error?: Error) => void,
) => {
 if (value !== passwordForm.password) {
 callback(new Error('两次输入的密码不一致'))
 return
 }

 callback()
}

小结

我现在处理 Element Plus 表单时，先保证字段名完全对齐，再把提交校验、弹窗清理和局部校验补齐。这样新增、编辑、分步操作放在同一个页面里，表单状态也不会越用越乱。

Vue3 组件通信常见方式整理

Thu, 17 Apr 2025 00:00:00 +0000

组件通信没有唯一标准答案，关键是看数据属于谁、要经过几层、是否要跨页面共享。日常 Vue3 项目里，父子组件优先用 props 和 emit；层级较深但作用范围有限时用 provide/inject；真正跨页面的公共状态再交给 Pinia。

父组件传给子组件：props

用户信息由父组件管理，子组件只负责展示时，直接传 props 最合适。数据流是从上到下的，阅读起来也最直接。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


<!-- UserCard.vue -->
<script setup lang="ts">
interface User {
 id: number
 name: string
 role: string
}

defineProps<{ user: User }>()
</script>

<template>
 <article>
 <strong>{{ user.name }}</strong>
 <span>{{ user.role }}</span>
 </article>
</template>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<!-- UserList.vue -->
<script setup lang="ts">
import UserCard from './UserCard.vue'

const currentUser = {
 id: 1,
 name: '林达',
 role: '管理员',
}
</script>

<template>
 <UserCard :user="currentUser" />
</template>

子组件不要直接修改 props。这会破坏单向数据流，也容易在控制台出现警告。

子组件通知父组件：emit

删除、保存、切换状态这类动作，由子组件触发、父组件决定怎么处理，适合用事件回传。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


<!-- UserCard.vue -->
<script setup lang="ts">
const emit = defineEmits<{
 remove: [id: number]
}>()

const props = defineProps<{ id: number; name: string }>()
</script>

<template>
 <button type="button" @click="emit('remove', props.id)">
 删除 {{ props.name }}
 </button>
</template>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


<!-- UserList.vue -->
<script setup lang="ts">
import { ref } from 'vue'

const users = ref([
 { id: 1, name: '林达' },
 { id: 2, name: '小王' },
])

const removeUser = (id: number) => {
 users.value = users.value.filter((user) => user.id !== id)
}
</script>

<template>
 <UserCard
 v-for="user in users"
 :key="user.id"
 v-bind="user"
 @remove="removeUser"
 />
</template>

事件名最好描述行为，例如 save、remove、change-status。不要用 callback 这种看不出意图的名字。

需要双向绑定时：v-model

表单组件最常见。Vue3 的 v-model 本质上是一个 modelValue 属性和一个 update:modelValue 事件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<!-- SearchInput.vue -->
<script setup lang="ts">
const props = defineProps<{ modelValue: string }>()
const emit = defineEmits<{
 'update:modelValue': [value: string]
}>()
</script>

<template>
 <input
 :value="props.modelValue"
 placeholder="搜索用户"
 @input="emit('update:modelValue', ($event.target as HTMLInputElement).value)"
 />
</template>

父组件就可以像使用原生输入框一样使用它：

1

<SearchInput v-model="keyword" />

跨多层但只在局部使用：provide / inject

主题配置、表单上下文、页面级权限等数据，经过多层组件逐级传递会很麻烦。这时可以由页面根组件提供，再由后代组件取用。

1
2
3
4
5


// 页面根组件
import { provide, ref } from 'vue'

const readonly = ref(false)
provide('formReadonly', readonly)

1
2
3
4


// 深层子组件
import { inject, type Ref } from 'vue'

const readonly = inject<Ref<boolean>>('formReadonly')

这适合“局部共享”，不建议把所有数据都塞进去。过多的注入会让数据来源变得不清楚。

跨页面共享：Pinia

登录用户、权限、全局主题、购物车这类状态需要多个页面共用，才值得放进 Pinia。页面临时的弹窗开关、单个表单字段仍然留在组件内更轻。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
 state: () => ({
 name: '',
 token: '',
 }),
 actions: {
 setUser(name: string, token: string) {
 this.name = name
 this.token = token
 },
 },
})

选择建议

一层父子：props + emit。
表单值双向同步：v-model。
多层组件的局部上下文：provide/inject。
跨路由、跨模块的共享状态：Pinia。

先从最简单的方案开始。通信方式越重，维护成本越高；数据范围越小，代码通常越容易整理。

Vue3 中 watch、watchEffect、computed 怎么选

Sat, 16 Nov 2024 00:00:00 +0000

刚开始写 Vue3 时，这三个 API 很容易混着用。它们都和响应式数据有关，但处理的问题其实不同：computed 用来推导数据，watch 用来处理明确的变化，watchEffect 适合自动收集依赖的副作用。

先记住这个选择方式

页面上需要一个由已有数据计算出来的新值，用 computed。
某个值变化后需要请求接口、保存草稿或同步第三方状态，用 watch。
一开始不确定依赖有哪些，并且希望代码立即执行一次，用 watchEffect。

不要为了“监听数据”而一律使用 watch。如果只是把数量和单价相乘得到金额，直接计算更清晰。

用 computed 推导页面数据

下面这个小计只依赖数量和单价。它没有请求接口，也没有修改外部状态，因此最适合用 computed。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


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

const count = ref(2)
const unitPrice = ref(39.9)

const totalPrice = computed(() => {
 return Number((count.value * unitPrice.value).toFixed(2))
})
</script>

<template>
 <p>商品数量：{{ count }}</p>
 <p>订单小计：{{ totalPrice }} 元</p>
</template>

computed 会缓存结果。只有 count 或 unitPrice 改变时，totalPrice 才会重新计算。模板里可以直接使用 totalPrice，不需要 .value。

用 watch 处理可控的副作用

搜索关键词变化后请求列表，是典型的 watch 场景。它的好处是监听来源明确，也能在新请求开始前清理旧请求。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import { ref, watch } from 'vue'

const keyword = ref('')
const list = ref<string[]>([])

watch(keyword, async (value, _oldValue, onCleanup) => {
 const controller = new AbortController()

 onCleanup(() => controller.abort())

 try {
 const response = await fetch(
 `/api/users?keyword=${encodeURIComponent(value)}`,
 { signal: controller.signal },
 )

 if (!response.ok) return
 list.value = await response.json()
 } catch (error) {
 if ((error as Error).name !== 'AbortError') throw error
 }
})

用户连续输入时，前一次请求可能比后一次更晚返回。上面的 AbortController 会在关键词再次变化时取消旧请求，避免旧结果覆盖新结果。

如果页面打开时也要先加载一次，可以传入第三个配置参数：

1

watch(keyword, loadUsers, { immediate: true })

用 watchEffect 快速同步依赖

watchEffect 会立即运行，并在执行过程中自动收集它读到的响应式数据。比如把编辑状态保存到本地草稿：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import { reactive, watchEffect } from 'vue'

const draft = reactive({
 title: '',
 content: '',
})

watchEffect(() => {
 localStorage.setItem('article-draft', JSON.stringify(draft))
})

这里不需要手动写 [draft.title, draft.content]。不过依赖来源越隐蔽，后期越难排查，因此涉及请求、路由跳转或复杂业务时，我更倾向于用 watch 写清监听对象。

常见误区

computed 不适合写异步请求。它应该保持纯粹，只返回由现有状态推导出的结果。

watchEffect 不适合替代所有 watch。它会自动追踪执行期间访问过的响应式数据，代码稍复杂时可能会触发比预期更多的更新。

监听对象时也要注意层级。watch(user, callback) 监听 reactive 对象会触发深层变化；如果只关心用户名，就写成 watch(() => user.name, callback)，范围更准确。

小结

把三者分开后，代码会更好读：页面展示值交给 computed，明确的业务变化交给 watch，简单的自动同步交给 watchEffect。这也是我在 Vue3 项目里判断响应式逻辑该放在哪里的第一步。