vue-mc Model 完全指南：defaults、mutations、validation 三大核心概念详解

vue-mc Model 完全指南：defaults、mutations、validation 三大核心概念详解

【免费下载链接】vue-mcModels and Collections for Vue项目地址: https://gitcode.com/gh_mirrors/vu/vue-mc

vue-mc是一款为 Vue 提供 Models 和 Collections 的轻量级数据管理库。它的 Model 类通过三大核心概念组织前端数据：defaults()（默认属性）、mutations()（属性转换）和validation()（验证规则）。只需重写这三个方法，你就能看到数据从初始化、类型转换到表单验证的完整闭环，非常适合刚接触 Vue 数据流的新手。

一分钟理解：Model 的三种属性状态

在深入三大概念之前，先认识图中这三个状态（见 官方文档 的 Attribute states 一节）：

• defaults()把 EMPTY 填充进 ACTIVE —— 这就是为什么每个属性都应该在defaults()中声明默认值，否则它在 Vue 中不会响应式。
• sync()把 ACTIVE 写入 SAVED（保存成功时自动执行）。
• clear()回到 EMPTY，reset()则回到 SAVED —— 表单"取消"按钮只需一行reset()代码。

核心概念 1：用 defaults() 定义默认属性

defaults()定义了模型的空状态，相当于"表单的初始值"。以任务模型为例（参考 basic-usage 文档）：

class Task extends Model { defaults() { return { id: null, name: '', done: false, } } }

三个关键行为：

1. 构建时自动填充：new Task({name: 'Tests'})后，task.name是'Tests'，而task.done自动为false，task.id自动为null—— 即使你没有传这些值。
2. 保证响应式：Vue 只能追踪提前声明的属性。defaults()声明了哪些字段，哪些字段才能安全地v-model绑定。
3. 清除与重置：clearAttributes()会把 ACTIVE 和 SAVED 一起回滚到defaults()的副本（见 Model.ts 第 367-372 行）。

💡 记忆技巧：defaults()= 表单没填时的样子。

核心概念 2：用 mutations() 做属性类型转换

浏览器里几乎所有输入都是字符串。用户勾选框给你true，输入框给你"123"。mutations()就是每个属性的"数据清洗管道"，在属性写入模型前自动转换：

mutations() { return { id: (id) => Number(id) || null, // 字符串 → 数字 name: String, // 强制转字符串 done: Boolean, // 强制转布尔值 } }

进阶技巧 —— 使用数组定义管道，多个函数按顺序执行（见 Model.ts 第 309-311 行 的compileMutators()实现）：

name: [String, (v) => v.trim()] // 先转字符串，再去除首尾空格

模型通过以下选项控制"何时"执行转换：

• mutateBeforeSync（默认true）：同步到 SAVED 状态前转换
• mutateBeforeSave（默认true）：发起保存请求前转换
• mutateOnChange（默认false）：用户输入过程中实时转换（会打断输入，一般关闭）

核心概念 3：用 validation() 写内置验证规则

vue-mc 自带一套可链式的验证规则（实现位于 Validation/index.ts），让你不必再为前端验证引入额外依赖。规则通过and/or自由组合：

import { boolean, equal, integer, min, required, string } from 'vue-mc/validation' validation() { return { id: integer.and(min(1)).or(equal(null)), // 必须是 ≥1 的整数，或为 null name: required.and(string), // 必填且为字符串 done: boolean, // 必须是布尔值 } }

规则求值的运算顺序是：

1. 先检查基础规则，失败则立即返回错误消息
2. 按链式顺序检查所有and规则
3. 再按链式顺序检查所有or规则

验证结果统一挂在model.errors上，模板里一行v-for就能渲染：

<input v-model="task.name"> <span v-for="error in task.errors.name">{{ error }}</span>

常用选项速查：

vue-mc 内置 30+ 规则：email、length(2, 8)、url、match(/^[a-z]+$/)、before/after（日期）、same('otherField')等，完整清单可查阅 models.md 的 Available rules 表格。你还能用validation.rule({...})自定义规则，并用validation.messages.set()定制错误文案、切换多语言。

三大概念如何协作：一个完整的 Task 示例

把三者放在一起，就是一个生产级模型的骨架（完整示例见 basic-usage 文档）：

class Task extends Model { defaults() { // 1️⃣ 空状态 return { id: null, name: '', done: false } } mutations() { // 2️⃣ 类型清洗 return { id: (id) => Number(id) || null, name: String, done: Boolean } } validation() { // 3️⃣ 表单验证 return { id: integer.and(min(1)).or(equal(null)), name: string.and(required), done: boolean, } } routes() { return { fetch: '/task/{id}', save: '/task' } } }

一次保存的完整生命周期：

1. 表单v-model修改ACTIVE状态
2. mutateBeforeSave触发mutations，字符串变为正确类型
3. validation全部通过，请求发出
4. 服务端返回 422？错误自动写进model.errors，模板即时标红
5. 保存成功 →sync()更新SAVED→ 模型自动加入所属 Collection

总结

• ⚙️defaults()—— 为每个属性声明初始值，保证响应式与可重置
• 🔀mutations()—— 属性入库前的类型转换管道
• ✅validation()—— 可链式组合的前端验证，错误即model.errors

掌握这三件套，你就掌握了 vue-mc Model 的核心。接下来可以继续阅读 Collection 文档，了解如何把多个模型组织成带路由、批量保存的集合。

【免费下载链接】vue-mcModels and Collections for Vue项目地址: https://gitcode.com/gh_mirrors/vu/vue-mc