一、Entity字段渲染的起点VonaJS的渲染配置从Entity开始。每个字段的渲染元数据直接写在字段定义旁边一目了然。EntityIEntityOptionsStudent(demoStudent) export class EntityStudent extends EntityBase { Api.field( v.title($locale(Name)), v.required(), v.min(2), ZovaRender.order(1), ZovaRender.cell(basic-table:actionView), ) name: string; Api.field( v.title($locale(Description)), v.optional(), ZovaRender.order(2), ZovaRender.field(basic-select:formFieldSelect, { placeholder: Please Select, items: [ { title: Male, value: 1 }, { title: Female, value: 2 }, ], }), ZovaRender.cell(basic-select:select, { items: [ { title: Male, value: 1 }, { title: Female, value: 2 }, ], }), ) description?: string; }逐行看关键的渲染配置配置含义ZovaRender.order(1)字段排在第 1 位ZovaRender.visible(false)隐藏该字段不渲染ZovaRender.cell(basic-table:actionView)表格中渲染为可点击查看的链接ZovaRender.cell(basic-date:date)表格中渲染为日期格式ZovaRender.field(basic-select:formFieldSelect, {...})表单中渲染为下拉选择框并传入选项数据ZovaRender.field(basic-date:formFieldDate)表单中渲染为日期选择器核心思路 渲染配置紧跟字段定义改一个字段时校验规则和渲染行为一起调整不用再去前端组件里翻找对应位置。ZovaRender.cell() 控制表格列怎么显示ZovaRender.field() 控制表单用什么控件。配置格式统一为 模块名:组件名并可通过第二个参数传入组件 props比如下拉框的选项列表、class、style 等。二、DTO 组装页面声明式定义页面结构Entity定义了字段级的渲染元数据DTO则负责把这些字段组装成完整的页面。 一个 DTO 就是一个页面页面结构通过 blocks 声明式定义。1. 列表页DtoIDtoOptionsStudentSelectResItem({ blocks: [ ZovaRender.block(basic-page:blockPage, { blocks: [ ZovaRender.block(basic-page:blockFilter), ZovaRender.block(basic-page:blockToolbarBulk, { actions: [ZovaRender.tableActionBulk(basic-table:actionCreate)], }), ZovaRender.block(basic-page:blockTable), ZovaRender.block(basic-page:blockPager), ], }), ], }) export class DtoStudentSelectResItem extends $Dto.get(() ModelStudent) { Api.field( v.title($locale(Operations)), ZovaRender.order(1, max), ZovaRender.cell(basic-table:actionOperationsRow, { actions: [ ZovaRender.tableActionRow(basic-table:actionUpdate), ZovaRender.tableActionRow(basic-table:actionDelete), ], }), ) _operationsRow?: unknown; }这个列表页由四个 block 组成 搜索区 - 批量操作栏 - 数据表格 - 分页器从上到下依次排列。操作栏里放了一个新建按钮表格行末尾自动追加编辑和删除操作列。DTO 继承自 $Dto.get(() ModelStudent)这意味着列表的字段直接从 Model进而从 Entity继承不需要重复定义。2. 搜索条件DtoIDtoOptionsStudentSelectReq({ openapi: { filter: { table: demoStudent } }, fields: { name: $makeSchema(v.optional(), z.string()), createdAt: $makeSchema( ZovaRender.field(basic-date:formFieldDateRange), v.filterTransform(a-web:dateRange), v.optional(), z.string(), ), }, }) export class DtoStudentSelectReq extends $Dto.queryPage(EntityStudent, [name, createdAt]) {}搜索条件的 DTO 独立于列表数据。这里 name 是普通文本搜索createdAt 渲染为日期范围选择器formFieldDateRange并通过 v.filterTransform 自动将前端选择的日期范围转换为后端查询格式。3. 新建/编辑页DtoIDtoOptionsStudentCreate({ blocks: [ ZovaRender.block(basic-pageentry:blockPageEntry, { blocks: [ ZovaRender.block(basic-pageentry:blockForm), ZovaRender.block(basic-pageentry:blockToolbarRow, { actions: [ ZovaRender.formActionRow(basic-form:actionSubmit, { permission: { actionInherit: update, formScene: [create, edit] }, }), ZovaRender.formActionRow(basic-form:actionBack, { permission: { public: true } }), ], }), ], }), ], }) export class DtoStudentCreate extends $Dto.create(() ModelStudent) {}新建页和编辑页结构相同 表单区 操作栏提交/返回。$Dto.create 和 $Dto.update 分别继承自 Model自动带上 Entity 中定义的字段渲染配置。区别在于 formScene 控制提交按钮的权限----创建和编辑时显示查看时隐藏。4. 详情页DtoIDtoOptionsStudentView({ blocks: [ ZovaRender.block(basic-pageentry:blockPageEntry, { blocks: [ ZovaRender.block(basic-pageentry:blockForm), ZovaRender.block(basic-pageentry:blockToolbarRow, { actions: [ ZovaRender.formActionRow(basic-form:actionBack, { permission: { public: true } }), ], }), ], }), ], }) export class DtoStudentView extends $Dto.get(() ModelStudent) {}详情页只比编辑页少了一个提交按钮继承自 $Dto.get表单自动为只读模式。总结一下 DTO 的页面组装模式 用 blocks 声明页面由哪些区域组成用 actions 声明操作按钮字段渲染则自动继承 Entity 的配置。整个过程不需要写 Vue 组件、不需要拼模板一个 DTO 文件就是一个完整的 CRUD 页面。三、与 Django Admin 对比为什么值得换特性VonaJSDjango Admin后端技术栈NodeJS TypeScriptPython 服务端模板语言前端技术栈Vue3 Vite8 TypeScriptHTML CSS JS渲染机制同构 SSR服务端模板渲染双层页签导航支持不支持界面定制自由定制组件级可控定制成本高需覆盖模板SSR支持含侧边栏、主题等不支持Django Admin 的核心问题是它用服务端模板渲染页面前端技术栈停留在传统 HTML/CSS/JS 时代。想定制一个下拉框的样式、加一个自定义交互就得去覆盖模板文件维护成本随业务复杂度急剧上升。VonaJS 采用前后端分离架构前端是完整的 Vue3 应用渲染配置通过 DTO 声明、组件按需替换定制一个字段控件只需要换一个 ZovaRender.field() 的组件名。同时Admin 中后台也支持 SSR刷新页面时侧边栏、多语言、主题等不会闪烁跳动。四、与 NestJS 对比DTO 不再只是校验在 NestJS 中DTO 的职责比较单一----参数校验。你需要用 class-validator 装饰器定义校验规则再用 class-transformer 或手动方式生成 Swagger 文档。至于前端页面怎么渲染那是另一个项目的事。VonaJS 基于 Zod4 的统一 Schema让 DTO 同时承担四项职责参数校验Zod 原生能力OpenAPI 文档自动从 Schema 生成 Swagger 文档渲染配置通过 ZovaRender 声明字段在 Table/Form 中的渲染方式数据序列化Response 的脱敏处理、字段过滤一份 Schema 定义四处复用从根源上消除了前后端字段定义不一致的问题。