SuperAPI AI 工具集

dido-frontend-nuxt

前端与建站

查看项目

更新于 11-05 18:19

技能介绍

该技能定义了 Dido 前端 Nuxt 项目的开发方法,适用于每次编写、修改、审查或创建 Nuxt 前端代码(包括组件或样式的微调)时使用。技能的前提是已掌握 dido-code-style 的通用原则,此处仅描述前端 Nuxt 特有的规范。

参考实现为 Dido 的 Nuxt 4 boilerplate(GitHub 仓库 DidoMarchet/starter-kit-nuxt-webapp),新站点从该模板起步,composable、插件与配置代码可在此查阅。boilerplate 的既有事实(已接好的模块、渲染方式、SCSS 系统)记录在 docs/project-architecture.md 与 docs/scss-system.md。由该模板生成的项目中,同一方法也写在 docs/code-style.md;若项目文档与本技能不一致,以项目为准,并需在报告中标注差异,因为其中一方需要修正。对于约定不同的旧项目,应贴合周边代码。

主要能力与规范涵盖:设计系统组合方式(间距使用 utility 类、gap 用 token、宽度用 .row-*);务实的 token 使用(仅重复值成为 token);数值纪律(整数或 5 的倍数,字体为 2 或 4 的倍数,偏离时取最近值);文本与可见分隔线保持最小 padding;缺失数据或配置降级为受控状态(fallback、提示、区块缺失),SSR 中读取可能缺失的对象时使用安全值。

JavaScript 与 Vue 方面:一律使用箭头函数;始终使用 <script setup>,用 defineOptions 声明组件名;DOM、滚动、动画效果放入 composable,纯逻辑放入 app/utils/ 并配测试;查询与调用放在专用目录,不写在组件内;命名使用完整 camelCase;禁止遗留 console.log,eslint-disable 须附原因;模板中不写静态文本,品牌来自配置(siteName),标签来自 i18n,内容来自 CMS。

命名规范:文件与目录 kebab-case;模板标签 PascalCase;composable useX、util 用动作名、插件按环境加后缀;BEM 类名,变体按区块或品牌命名而非颜色;单一数字排版量表;颜色按家族数字量表;id 仅在需要时使用且 kebab-case;大写用 text-transform。

组件规范:每个组件是 components/<area>/<name>/ 目录,含 index.vue、style.scss 及资源,按领域分组;widget/ 仅放无状态、可复用组件,接收 prop 并暴露 slot;.vue 内顺序为 template、script setup、style;样式不用 scoped;组件只使用自身块与设计系统的类,通过 prop、事件、slot 或 store 通信;资源放 app/assets/img/ 并使用描述性 kebab-case 命名。

SCSS 规范:每个 style.scss 和 partial 顶部 @use 工具箱;新增 vars/ 或 mixins/ 文件需加入 _index.scss;流体尺寸用 slamp(min, max),字体与大间距使用流体;控件和卡片随视口缩放;侧边距不固定;媒体查询用 @include react("key");hover 放在 react("pointer-and-hover") 内;可点击元素均有 hover 与过渡,:active 同样有反馈;图片混合模式不得有 opacity/filter/transform 动画;文本操作紧邻标题并基线对齐;面板、抽屉、模态重新打开时从初始状态开始;移动端选择卡片使用全宽纵向列表;token 生成数字类而非 mixin;动效使用单一站点缓动与 token 时长。

i18n 方面:文本通过 $t;字典按区域分文件、按语言分目录,导入文件区域需使用 ~~ 别名;各语言镜像,新字符串在所有语言同键同区域添加;本地化 slug 在 i18n 配置(pages)中声明,否则不进 sitemap;动态 slug 需设置各语言参数以保证 hreflang 与 canonical 正确。

配置方面:nuxt.config.ts 仅展开 configuration/ 的各区域 slice,修改设置在其 slice 中进行;env 与密钥通过 runtimeConfig 从 process.env 读取,public 仅放公开值;robots 与 noindex 按环境区分,仅生产环境索引。

数据与第三方:CMS 只通过 useGraphql() 读取,查询与 fragment 在 app/graphql/<cms>/;REST 调用通过 useApiFetch();页面不直接使用 Apollo 或 HTTP 客户端;CMS 错误返回 500,仅内容缺失时 404;SEO 与 hreflang 用 useSeo();useLenis() 每个应用只初始化一次,独立滚动容器各用 Lenis;第三方按作用范围选择 plugin 或 composable+组件;第三方库仅由其 plugin 或 composable 导入;嵌入内容用设计系统装扮,iframe 无法装扮;使用前测量域名与 cookie;服务端动态源(如 sitemap)不使用客户端 SDK,失败不中断构建;CMS schema 仅通过版本化 migration 修改。

动画方面:动画使用 GSAP(进出场、模态、抽屉、下拉、标签页、滚动出现、序列、微交互);仅按钮与链接的 hover、按压保留在 CSS;重复动效只在 composable 或 widget 中实现一次;动画在 gsap.context() 内创建并以组件元素为作用域,卸载时 revert();仅客户端从 onMounted 开始;打开与关闭使用同一 timeline 的 play()/reverse();单一站点缓动与 token 时长,JS 通过 SCSS 模块读取;滚动关联动效用 ScrollTrigger 挂接 Lenis;动画只改变 transform 与 opacity,高度仅用于需推动下方内容的小块;不变值先用 gsap.set 固定;GSAP 主线程需保持空闲,先读后写;will-change 仅用于运动表面;模态遮罩与表面在同一 timeline,因为 GSAP 不动画 ::backdrop。

限制与约束:所有规范以资料原文为准,未提及的收费、价格、平台、效果或使用步骤暂未提供。