{"id":46523925,"url":"https://github.com/mhaibaraai/movk-nuxt","last_synced_at":"2026-03-06T20:02:17.914Z","repository":{"id":306046473,"uuid":"1024297939","full_name":"mhaibaraai/movk-nuxt","owner":"mhaibaraai","description":"`@movk/nuxt` 是一个为 Nuxt 4 设计的模块化工程套件,提供 Schema 驱动的自动表单生成、独立 UI 组件和通用工具函数。","archived":false,"fork":false,"pushed_at":"2026-03-03T13:17:12.000Z","size":4652,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T13:35:30.489Z","etag":null,"topics":["auto-form","autoform","movk","movk-nuxt","movk-nuxt-docs","nuxt-ui","nuxt4","zod-v4"],"latest_commit_sha":null,"homepage":"https://nuxt.mhaibaraai.cn","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mhaibaraai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-22T13:34:26.000Z","updated_at":"2026-03-03T01:27:29.000Z","dependencies_parsed_at":"2026-01-19T05:26:05.290Z","dependency_job_id":"677110ca-def9-4163-a47d-2bba444188ec","html_url":"https://github.com/mhaibaraai/movk-nuxt","commit_stats":null,"previous_names":["mhaibaraai/movk-nuxt"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/mhaibaraai/movk-nuxt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhaibaraai%2Fmovk-nuxt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhaibaraai%2Fmovk-nuxt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhaibaraai%2Fmovk-nuxt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhaibaraai%2Fmovk-nuxt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhaibaraai","download_url":"https://codeload.github.com/mhaibaraai/movk-nuxt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhaibaraai%2Fmovk-nuxt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30195544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auto-form","autoform","movk","movk-nuxt","movk-nuxt-docs","nuxt-ui","nuxt4","zod-v4"],"created_at":"2026-03-06T20:02:17.086Z","updated_at":"2026-03-06T20:02:17.888Z","avatar_url":"https://github.com/mhaibaraai.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Movk Nuxt](https://nuxt.mhaibaraai.cn/og-image.png)](https://nuxt.mhaibaraai.cn/)\n\n\u003e Nuxt 4 模块化工程套件 — 基于 Zod v4 的 Schema 驱动自动表单、带认证与进度追踪的 API 集成系统、10+ 独立 UI 组件和通用 Composables。\n\n[![Install MCP in Cursor](https://nuxt.mhaibaraai.cn/mcp/badge.svg)](https://nuxt.mhaibaraai.cn/mcp/deeplink)\n[![Install MCP in VS Code](https://nuxt.mhaibaraai.cn/mcp/badge.svg?ide=vscode)](https://nuxt.mhaibaraai.cn/mcp/deeplink?ide=vscode)\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![Nuxt](https://img.shields.io/badge/Nuxt-4-00DC82.svg)](https://nuxt.com/)\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![License][license-src]][license-href]\n[![Nuxt UI][nuxt-ui-src]][nuxt-ui-href]\n\n- 📖 [在线文档](https://nuxt.mhaibaraai.cn)\n\n## ✨ 特性\n\n- **Schema 驱动** - 基于 Zod v4 的声明式表单定义，一份 Schema 同时定义数据结构、验证规则和 UI 配置。\n- **自动化系统** - AutoForm 通过 Schema 自动生成完整表单界面，支持 15+ 种控件类型。\n- **API 集成** - 内置 useApiFetch、useUploadWithProgress、useDownloadWithProgress，提供多端点支持、自动认证、业务状态码检查、Toast 提示和进度监控。\n- **模块化设计** - 采用分层架构，按需使用 UI 组件、工具函数或全套自动化系统。\n- **独立组件库** - 内置 DatePicker、StarRating、WithCopy 等 10+ 个通用 UI 组件。\n- **类型安全** - 完整的 TypeScript 类型推断，从 Schema 到表单数据。\n- **可扩展** - 支持自定义控件、布局系统、条件渲染等高级特性。\n\n## 🚀 快速开始\n\n### 安装\n\n```bash\n# pnpm\npnpm add @movk/nuxt @nuxt/ui zod\n\n# yarn\nyarn add @movk/nuxt @nuxt/ui zod\n\n# npm\nnpm install @movk/nuxt @nuxt/ui zod\n```\n\n### 配置\n\n在 `nuxt.config.ts` 中注册模块:\n\n```ts\nexport default defineNuxtConfig({\n  modules: ['@movk/nuxt']\n})\n```\n\n可选配置项:\n\n```ts\nexport default defineNuxtConfig({\n  modules: ['@movk/nuxt'],\n  movk: {\n    prefix: 'M' // 组件前缀,默认为 'M'\n  }\n})\n```\n\n### 基础示例\n\n创建一个简单的用户注册表单:\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport type { FormSubmitEvent } from '@nuxt/ui'\nimport type { z } from 'zod'\n\nconst { afz } = useAutoForm()\n\n// 定义 Schema\nconst schema = afz.object({\n  username: afz.string().min(3).meta({ label: '用户名' }),\n  email: afz.email().meta({ label: '邮箱' }),\n  age: afz.number().min(18).meta({ label: '年龄' })\n})\n\n// 类型推导\ntype Schema = z.output\u003ctypeof schema\u003e\n\n// 表单状态\nconst form = ref\u003cPartial\u003cSchema\u003e\u003e({})\n\n// 提交处理\nasync function onSubmit(event: FormSubmitEvent\u003cSchema\u003e) {\n  console.log('提交数据:', event.data)\n}\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cMAutoForm :schema=\"schema\" :state=\"form\" @submit=\"onSubmit\" /\u003e\n\u003c/template\u003e\n```\n\n## 📦 核心功能\n\n### AutoForm - Schema 驱动的表单系统\n\n基于 Zod Schema 的\"定义即渲染\"表单解决方案:\n\n```ts\nconst { afz } = useAutoForm()\n\nconst schema = afz.object({\n  // 基础类型\n  username: afz.string().min(3),\n  age: afz.number().min(18),\n  isActive: afz.boolean(),\n\n  // 高级类型\n  email: afz.email(),\n  birthdate: afz.calendarDate(),\n  role: afz.enum(['admin', 'user']),\n  avatar: afz.file(),\n\n  // 嵌套对象\n  profile: afz.object({\n    bio: afz.string(),\n    website: afz.url()\n  }),\n\n  // 数组\n  tags: afz.array(afz.string())\n})\n```\n\n**支持的控件类型**:\n- 基础输入: `UInput`、`UInputNumber`、`UCheckbox`、`USwitch`\n- 选择器: `USelect`、`USelectMenu`、`URadioGroup`、`UCheckboxGroup`\n- 高级输入: `UTextarea`、`USlider`、`UPinInput`、`UInputTags`\n- 自定义组件: `DatePicker`、`ColorChooser`、`StarRating`\n- 文件上传: `UFileUpload`\n- 增强输入: `WithCopy`、`WithClear`、`WithPasswordToggle`、`WithCharacterLimit`\n\n### 独立组件\n\n无需依赖 AutoForm,可直接使用的高质量 UI 组件:\n\n#### 日期选择器\n\n```vue\n\u003ctemplate\u003e\n  \u003cMDatePicker v-model=\"selectedDate\" label-format=\"iso\" /\u003e\n\u003c/template\u003e\n```\n\n#### 输入增强组件\n\n```vue\n\u003ctemplate\u003e\n  \u003c!-- 带复制功能 --\u003e\n  \u003cMWithCopy v-model=\"apiKey\" /\u003e\n\n  \u003c!-- 带清除按钮 --\u003e\n  \u003cMWithClear v-model=\"searchText\" /\u003e\n\n  \u003c!-- 密码显隐切换 --\u003e\n  \u003cMWithPasswordToggle v-model=\"password\" /\u003e\n\n  \u003c!-- 字符数限制 --\u003e\n  \u003cMWithCharacterLimit v-model=\"bio\" :max-length=\"200\" /\u003e\n\u003c/template\u003e\n```\n\n#### 交互组件\n\n```vue\n\u003ctemplate\u003e\n  \u003c!-- 星级评分 --\u003e\n  \u003cMStarRating v-model=\"rating\" :max=\"5\" /\u003e\n\n  \u003c!-- 颜色选择器 --\u003e\n  \u003cMColorChooser v-model=\"color\" /\u003e\n\u003c/template\u003e\n```\n\n### Composables\n\n#### useDateFormatter\n\n强大的日期格式化、解析、范围处理工具:\n\n```ts\nconst { format, parse, isDateValue, formatRange } = useDateFormatter()\n\n// 格式化日期\nconst formatted = format(new Date(), 'iso') // \"2024-01-01\"\n\n// 解析日期字符串\nconst date = parse('2024-01-01', 'iso')\n\n// 格式化日期范围\nconst range = formatRange({ start: date1, end: date2 }, 'iso')\n```\n\n#### useAutoForm\n\nAutoForm 的核心逻辑封装:\n\n```ts\nconst { afz, defineControl, getAutoFormMetadata } = useAutoForm()\n\n// 创建 Schema\nconst schema = afz.object({\n  username: afz.string()\n})\n\n// 定义自定义控件\nconst customControl = defineControl({\n  component: MyCustomInput,\n  controlProps: { class: 'w-full' }\n})\n\n// 获取字段元数据\nconst meta = getAutoFormMetadata(schema)\n```\n\n#### useApiFetch\n\n基于 Nuxt useFetch 封装的 API 请求：\n\n```ts\n// 基础用法\nconst { data, pending, error } = await useApiFetch\u003cUser[]\u003e('/users')\n\n// POST 请求\nconst { data } = await useApiFetch\u003cUser\u003e('/users', {\n  method: 'POST',\n  body: { name: 'test' },\n  toast: { successMessage: '创建成功' }\n})\n\n// 使用其他端点\nconst { data } = await useApiFetch('/users', { endpoint: 'v2' })\n```\n\n#### useUploadWithProgress\n\n带进度监控的文件上传：\n\n```ts\nconst { progress, uploading, upload, abort } = useUploadWithProgress()\n\n// 上传文件\nawait upload('/api/upload', file, {\n  fieldName: 'avatar',\n  onSuccess: (response) =\u003e console.log('上传成功:', response)\n})\n```\n\n#### useDownloadWithProgress\n\n带进度监控的文件下载：\n\n```ts\nconst { progress, downloading, download, abort } = useDownloadWithProgress()\n\n// 下载文件\nawait download('/api/export/report', {\n  filename: 'report.pdf',\n  onSuccess: (filename) =\u003e console.log('下载完成:', filename)\n})\n```\n\n## 🏗️ 架构分层\n\nMovk Nuxt 采用清晰的分层架构:\n\n- **Core Systems** - AutoForm(已发布)\n- **API System** - useApiFetch、useUploadWithProgress、useDownloadWithProgress，提供完整的 API 请求方案\n- **Standalone Components** - DatePicker、StarRating、WithCopy 等独立 UI 组件\n- **Composables** - useDateFormatter、useAutoForm 等通用组合式函数\n- **Foundation** - 基于 [Nuxt UI](https://ui.nuxt.com)、[Zod v4](https://zod.dev)、[VueUse](https://vueuse.org)\n\n## ⚡ 技术栈\n\n- [Nuxt 4](https://nuxt.com/) - The Intuitive Vue Framework\n- [Nuxt UI](https://ui.nuxt.com/) - A UI Library for Modern Web Apps\n- [Zod v4](https://zod.dev/) - TypeScript-first schema validation\n- [TypeScript](https://www.typescriptlang.org/) - JavaScript with syntax for types\n- [VueUse](https://vueuse.org/) - Collection of Vue Composition Utilities\n- [Vitest](https://vitest.dev/) - Next Generation Testing Framework\n\n## 🗺️ 开发路线图\n\n- ✅ **AutoForm** - Schema 驱动的表单系统（已发布）\n- ✅ **API System** - API 请求封装（已发布）\n  - useApiFetch、useClientApiFetch - API 请求\n  - useUploadWithProgress、useDownloadWithProgress - 进度监控\n- ✅ **独立组件库** - DatePicker、StarRating、WithCopy 等组件（已发布）\n\n## 📄 许可证\n\n[MIT](./LICENSE) License © 2024-PRESENT [YiXuan](https://github.com/mhaibaraai)\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/@movk/nuxt?style=flat\u0026colorA=080f12\u0026colorB=1fa669\n[npm-version-href]: https://npmjs.com/package/@movk/nuxt\n\n[npm-downloads-src]: https://img.shields.io/npm/dm/@movk/nuxt?style=flat\u0026colorA=080f12\u0026colorB=1fa669\n[npm-downloads-href]: https://npmjs.com/package/@movk/nuxt\n\n[license-src]: https://img.shields.io/github/license/mhaibaraai/movk-nuxt.svg?style=flat\u0026colorA=080f12\u0026colorB=1fa669\n[license-href]: https://github.com/mhaibaraai/movk-nuxt/blob/main/LICENSE\n\n[nuxt-ui-src]: https://img.shields.io/badge/Nuxt%20UI-4-00DC82?style=flat\u0026colorA=080f12\n[nuxt-ui-href]: https://ui.nuxt.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhaibaraai%2Fmovk-nuxt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhaibaraai%2Fmovk-nuxt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhaibaraai%2Fmovk-nuxt/lists"}