团队前端编码规范

团队前端编码规范 (HTML/CSS)

1. 总则

1.1 目标

  • 提高代码可读性和可维护性
  • 保证跨浏览器兼容性和响应式支持
  • 确保无障碍访问和SEO友好
  • 优化性能与加载速度

1.2 基本原则

  • 语义化优先：使用最合适的HTML元素
  • 移动优先：从小屏幕开始设计
  • 渐进增强：基础功能广泛兼容，高级特性增强体验
  • DRY原则：避免重复代码

2. HTML规范

2.1 文档结构

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="description" content="页面描述">
  <title>页面标题 - 网站名称</title>
  
  <!-- 预加载关键资源 -->
  <link rel="preload" href="styles/main.css" as="style">
  <link rel="preconnect" href="https://fonts.gstatic.com">
  
  <!-- 主样式表 -->
  <link rel="stylesheet" href="styles/main.css">
  
  <!-- Favicon (现代格式) -->
  <link rel="icon" href="favicon.ico" sizes="any">
  <link rel="icon" href="icon.svg" type="image/svg+xml">
  <link rel="apple-touch-icon" href="apple-touch-icon.png">
</head>
<body>
  <!-- 使用WAI-ARIA地标角色 -->
  <header role="banner">...</header>
  
  <main role="main" id="main-content">
    <!-- 页面主要内容 -->
  </main>
  
  <footer role="contentinfo">...</footer>
  
  <!-- 脚本放在body末尾 -->
  <script src="scripts/main.js" defer></script>
</body>
</html>

2.2 语义化标签

场景 推荐标签
主导航 <nav>
文章内容 <article>
独立内容区块 <section>
侧边栏 <aside>
标题组 <hgroup>
时间日期 <time datetime="">
按钮 <button>
表单分组 <fieldset> + <legend>

2.3 属性书写规范

  1. 属性顺序：

    • class
    • id
    • data-*
    • src, href, value
    • title, alt
    • role, aria-*
    • tabindex

  2. 布尔属性省略值：

    <!-- 推荐 -->
<input type="text" disabled>
<input type="checkbox" checked>

<!-- 避免 -->
<input type="text" disabled="disabled">

2.4 注释规范

<!-- 区块注释 -->
<section class="product-grid">
  <!-- 产品卡片组件 -->
  <article class="product-card">...</article>
  
  <!-- 分页组件 -->
  <nav class="pagination">...</nav>
</section>

3. CSS规范

3.1 文件组织

styles/
├── base/
│   ├── _reset.css       # 重置样式
│   ├── _variables.css   # 全局变量
│   ├── _typography.css  # 字体排版
│   └── _global.css      # 全局基础样式
├── components/
│   ├── _buttons.css
│   ├── _cards.css
│   ├── _navigation.css
│   └── _forms.css
├── layouts/
│   ├── _grid.css
│   ├── _header.css
│   ├── _footer.css
│   └── _sidebar.css
├── utilities/
│   ├── _spacing.css
│   ├── _display.css
│   └── _helpers.css
├── themes/
│   ├── _dark.css        # 暗黑主题
│   └── _high-contrast.css # 高对比主题
└── main.css             # 主入口文件

3.2 命名规范（BEM）

/* Block */
.search-form {}

/* Element */
.search-form__input {}
.search-form__button {}

/* Modifier */
.search-form--compact {}
.search-form__button--disabled {}

3.3 样式声明顺序

  1. 布局属性：display, position, float, clear, flex, grid...
  2. 盒模型：width, height, margin, padding, border...
  3. 视觉属性：background, color, box-shadow, opacity...
  4. 排版：font, line-height, text-align, white-space...
  5. 变换与动画：transform, transition, animation...
  6. 其他：cursor, overflow, z-index...

3.4 响应式实现

/* 移动优先 - 默认移动端样式 */
.card {
  width: 100%;
  margin-bottom: 1rem;
}

/* 平板 (≥768px) */
@media (min-width: 768px) {
  .card {
    width: calc(50% - 1rem);
    float: left;
    margin-right: 1rem;
  }
}

/* 桌面 (≥1024px) */
@media (min-width: 1024px) {
  .card {
    width: calc(33.333% - 1rem);
  }
}

/* 大屏 (≥1440px) */
@media (min-width: 1440px) {
  .card {
    width: calc(25% - 1rem);
  }
}

3.5 暗黑模式适配

/* 基础变量定义 */
:root {
  /* 色彩系统 */
  --color-primary: #2563eb;
  --color-text: #1e293b;
  --color-bg: #ffffff;
  --color-surface: #f8fafc;
  --color-border: #e2e8f0;
  
  /* 间距系统 */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  
  /* 过渡效果 */
  --transition-base: all 0.3s ease;
}

/* 暗黑主题变量 */
@media (prefers-color-scheme: dark) {
  :root {
    --color-text: #e2e8f0;
    --color-bg: #0f172a;
    --color-surface: #1e293b;
    --color-border: #334155;
  }
}

/* 高对比度主题 */
@media (prefers-contrast: more) {
  :root {
    --color-text: #000;
    --color-bg: #fff;
    --color-border: #000;
  }
}

/* 组件样式 */
.card {
  background-color: var(--color-surface);
  border: 1px solid var(--color-border);
  color: var(--color-text);
  padding: var(--spacing-md);
  border-radius: 8px;
  transition: var(--transition-base);
}

3.6 性能优化实践

/* 使用CSS变量 */
:root {
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.1);
}

.card {
  box-shadow: var(--shadow-sm);
}

/* 避免昂贵选择器 */
/* 不推荐 */
header nav ul li a {}

/* 推荐 */
.nav-link {}

/* 使用will-change优化动画 */
.animated-element {
  will-change: transform, opacity;
}

/* 减少重排属性 */
/* 优先使用transform/opacity */
.slide-in {
  transform: translateX(0);
  transition: transform 0.3s ease;
}

4. 最佳实践

4.1 HTML最佳实践

  1. 图片优化：

    <img 
  src="image.jpg" 
  srcset="image-480.jpg 480w, image-800.jpg 800w"
  sizes="(max-width: 600px) 480px, 800px"
  alt="描述性文本"
  loading="lazy"
  width="800"
  height="600">

  2. 视频嵌入：

    <video controls width="640" poster="preview.jpg">
  <source src="video.mp4" type="video/mp4">
  <source src="video.webm" type="video/webm">
  <track label="中文" kind="subtitles" srclang="zh" src="captions.vtt">
</video>

4.2 CSS最佳实践

  1. 现代布局技术：

    /* Flexbox */
.flex-container {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
  justify-content: space-between;
}

/* CSS Grid */
.grid-container {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  gap: 1.5rem;
}

/* 多列布局 */
.multi-column {
  column-count: 3;
  column-gap: 2rem;
}

  2. 实用工具类：

    /* 间距工具 */
.mt-0 { margin-top: 0 !important; }
.mt-1 { margin-top: 0.25rem; }
.mt-2 { margin-top: 0.5rem; }

/* 响应式显示工具 */
.mobile-only { display: block; }
@media (min-width: 768px) {
  .mobile-only { display: none; }
}

5. 工作流程规范

5.1 代码提交

  1. 功能分支命名：feature/描述性名称

  2. 提交信息格式：

    [类型] 简要描述

详细说明（可选）

- 变更点1
- 变更点2

    类型示例：feat, fix, docs, style, refactor, perf

5.2 代码审查

  1. 必须通过Pull Request合并代码
  2. 审查重点：
    • 是否符合本规范
    • 是否影响性能
    • 是否考虑无障碍访问
    • 响应式是否正常
    • 是否添加适当注释

5.3 工具链

// .prettierrc
{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "avoid"
}

// .stylelintrc
{
  "extends": "stylelint-config-standard",
  "rules": {
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]*(-[a-zA-Z0-9]+)*$",
    "max-nesting-depth": 3,
    "no-descending-specificity": null,
    "declaration-block-no-redundant-longhand-properties": true
  }
}

6. 附录：无障碍要求

6.1 关键要求

  1. 色彩对比度：文本4.5:1，大文本3:1
  2. 键盘导航：所有功能可通过键盘访问
  3. 焦点管理：可见焦点指示器
  4. 语义结构：正确使用标题层级 (h1-h6)
  5. 表单标签：所有表单元素必须有<label>

6.2 ARIA使用指南

<!-- 当原生语义不足时使用ARIA -->
<nav aria-label="主菜单">
  <ul role="menu">
    <li role="menuitem"><a href="/">首页</a></li>
  </ul>
</nav>

<!-- 动态区域 -->
<div aria-live="polite" aria-atomic="true">
  动态更新的内容
</div>

版本控制
本文档版本：1.2
最后更新：2025年8月1日
维护团队：前端架构组
生效日期：即日起

posted @ 2025-07-31 11:22  华腾智算  阅读(28)  评论(0)    收藏  举报
https://damo.alibaba.com/ https://tianchi.aliyun.com/course?spm=5176.21206777.J_3941670930.5.87dc17c9BZNvLL