Skip to main content

原型实现与设计稿还原规范

进行原型实现或设计稿还原时，需要遵守以下准则：

设计稿处理​

  1. Figma 设计稿获取：当存在 Figma 链接时，使用 Figma MCP 工具获取设计信息。保证实现代码尽可能符合设计稿：
    • Figma Dev Mode MCP 服务器提供一个可提供图像和 SVG 资产的资产端点。
    • IMPORTANT：如果 Figma Dev Mode MCP 服务器为图像或 SVG 返回一个 localhost 源，请直接使用该图像或 SVG 源。
    • IMPORTANT：不要导入或添加新的图标包，所有资产都应在 Figma 负载中，或者 Lucide 图标库（已安装）。
    • IMPORTANT：如果提供了 localhost 源，则不要使用或创建占位符。
  2. 设计与开发平衡：在保持设计一致性的前提下，优先考虑代码的可维护性和性能。

样式实现规范​

基础样式规则​

  1. 样式系统：所有样式必须使用 Tailwind CSS，禁止在 <style> 或 <style scoped> 中设置样式。
  2. 尺寸处理策略：
    • 禁止使用固定宽度或长度，优先使用相对宽度或长度（如 w-3/4、h-screen）
    • 当必须使用固定尺寸时，选择 Tailwind CSS 预设的 rem 值，保持一致性与响应性
    • 避免使用 w-[123px] 等任意值，优先使用预设值如 w-32、w-64

视觉样式规范​

  1. 颜色与视觉效果：颜色、背景、边框、渐变、阴影、字体颜色等样式应尽可能符合设计稿，使用项目中预定义的 CSS 变量。

布局实现规范​

布局系统​

  1. 布局实现方式：
    • 必须使用 flex 或 grid 布局，实现响应式布局
    • 严禁使用绝对布局（absolute、fixed）定位元素，除非确实需要层叠效果

间距处理​

  1. 元素间距：
    • 优先使用：gap-、space-x-、space-y- 类
    • 尽量避免：mt-、mb-、ml-、mr- 类
    • 推荐模式：父容器设置 gap，子元素不设置外边距

组件化开发​

组件抽象原则​

  1. 模块化思维：
    • 识别重复的 UI 模式，将其抽象为独立的 Vue 组件
    • 页面组件应尽可能少包含原生 HTML 元素，多使用组件化元素
    • 单个组件职责单一，功能内聚

组件库优先级​

  1. 组件选择策略：
    • 第一优先级：使用 Shadcn Vue 组件库
    • 第二优先级：使用项目现有的自定义组件
    • 最后选择：实现新的自定义组件

组件设计原则​

  1. 组件动态性：
    • 组件的具体内容（标题、图片、图标、文本等）应作为 props 传入
    • 避免在组件内硬编码具体内容
    • 提供合理的默认值和类型定义

图标与资源​

  1. 图标使用：优先使用 lucide-vue-next 图标库，保持图标风格统一性。

响应式设计​

断点系统​

  1. 响应式实现：
    • 使用 Tailwind CSS 响应式前缀：tablet:、desktop:、screen:
    • 三种设备适配：
      • 平板电脑：768px-1536px (tablet:)
      • 桌面显示器：1536px-2304px (desktop:)
      • 超大屏幕：2304px及以上 (screen:)
    • 实现样例：mt-2 tablet:mt-4 desktop:mt-6 screen:mt-8

响应式最佳实践​

  1. 移动优先：从最小屏幕开始设计，逐步增强到大屏幕。

国际化处理​

  1. 多语言支持：

    • 文本内容从 dictionary.json 字典获取
    • 更新字典后运行 npm run i18n 生成类型
    • 使用方式：import I18N from '@/utils/i18n.base'; + {{ I18N.xxx }}

  2. 时间格式处理：

    • 时间国际化或格式化使用 @internationalized/date 库，禁止随意使用自定义的时间格式化函数
    • 标准用法：new DateFormatter(I18N.locale, options).format(date)
    • 支持的格式选项：year、month、day、hour、minute、second 等
    • 示例：

数据可视化​

图表组件规范​

  1. 可视化图表：
    • 优先使用 vue-echarts 库
    • 避免直接使用原生 echarts（除特殊情况）
    • 图表组件放置在 components/echarts 目录
    • 必须提供 props：标题、tooltip、坐标轴名称、数据
    • 支持三种响应式尺寸：tablet、desktop、screen

图表最佳实践​

  1. 图表性能优化：
    • 大数据量时考虑数据采样
    • 使用 vue-echarts 的懒加载特性
    • 合理设置图表的 resize 行为

性能优化​

  1. 组件性能：

    • 使用 defineAsyncComponent 进行组件懒加载
    • 大列表使用虚拟滚动
    • 图片使用懒加载和适当的格式（WebP）

  2. 渲染优化：

    • 合理使用 v-memo 和 v-once
    • 避免在模板中进行复杂计算
    • 使用 computed 缓存计算结果

开发环境​

  1. 本地开发：本地开发服务器运行在 http://localhost:5173/，无需手动启动。

文档获取与参考​

第三方依赖文档​

  1. Context7 MCP 工具使用：
    • 当需要查阅第三方依赖的官方文档时，使用 Context7 MCP 工具获取最新、准确的文档信息
    • 优先获取文档的依赖：
      • Shadcn Vue：组件库使用方法、API 参考、最佳实践
      • Vue-ECharts：图表配置、事件处理、响应式设计
      • Pinia：状态管理模式、store 设计、数据持久化
      • Vue Router：路由配置、导航守卫、动态路由
      • Tailwind CSS：样式类参考、响应式设计、自定义配置
      • Lucide：图标使用方法、图标列表、自定义图标

文档查阅策略​

  1. 文档优先级：
    • 第一优先级：使用 Context7 MCP 工具获取官方文档
    • 第二优先级：参考项目内现有的实现示例
    • 第三优先级：基于经验进行合理推断

文档应用原则​

  1. 文档实践应用：
    • 在使用新的 API 或组件前，先通过 Context7 MCP 工具查阅相关文档
    • 确保 API 使用方式与官方文档一致，避免过时或错误的用法
    • 参考文档中的最佳实践和性能优化建议
    • 遵循文档中的命名约定和代码风格

代码质量​

注释规范​

  1. 注释策略：
    • 必须：为每个类、函数添加 JSDoc 格式的块级注释
    • 适度：仅在代码关键部分与逻辑复杂部分添加行级注释
    • 避免：过度注释显而易见的代码

代码结构​

  1. 文件组织：
    • 组件文件使用 PascalCase 命名
    • 工具函数使用 camelCase 命名
    • 常量使用 UPPER_SNAKE_CASE 命名

错误处理与边界情况​

  1. 错误处理：

    • API 调用必须包含错误处理
    • 组件 props 提供类型检查和默认值
    • 使用 try-catch 处理可能的运行时错误

  2. 边界情况：

    • 考虑空数据状态的 UI 展示
    • 处理加载状态和错误状态
    • 提供合理的 loading 和 error 组件

代码检查清单​

在提交代码前，请确认：

  • 所有样式都使用 Tailwind CSS
  • 没有使用固定宽高（除非必要）
  • 布局使用 flex/grid，避免绝对定位
  • 重复的 UI 已抽象为组件
  • 组件内容通过 props 传入
  • 添加了必要的 JSDoc 注释
  • 考虑了响应式设计
  • 处理了错误和边界情况
  • 进行了基本的性能优化
  • 使用 Context7 MCP 工具查阅了相关第三方依赖文档
  • API 使用方式与官方文档一致
  • 遵循了文档中的最佳实践和命名约定