優秀的 CSS 註釋不僅是代碼說明,更是團隊協作的溝通橋樑、重構時的導航圖、新人入項的快速指南。本文建立從「目錄級」到「行級」的分層註釋體系,結合實戰模板,助你打造自文檔化的高質量樣式表。
| 層級 | 作用範圍 | 語法形式 | 核心內容 |
|---|---|---|---|
| 文件級 | 整個 .css 文件 | /* ===== Module Name ===== */ | 模塊名、作者、創建日期、依賴關係、版本號 |
| 區塊級 | 功能模塊/頁面區域 | /* --- Section Name --- */ | 區塊職責、適用頁面、響應式斷點策略 |
| 組件級 | 可復用 UI 組件 | /* Component: ComponentName */ | 組件結構圖、狀態變體、修飾符說明、使用示例 |
| 行級 | 關鍵/非常規聲明 | /* 說明 */ 內聯或獨行 | Hack 原因、魔法數值來源、瀏覽器兼容性備註 |
/* ==========================================================================
Module: Header Navigation (header-nav.css)
Author: Zhang San
Date: 2024-01-15
Version: 2.1.0
Dependencies: variables.css, mixins.css
========================================================================== */
/* --- 1. Reset & Base --- */
/* 針對導航區域的專用重置,避免全局污染 */
.header-nav { /* ... */ }
/* --- 2. Layout Structure --- */
/* Header: 頂部導航容器 */
.header-nav__container {
display: flex;
justify-content: space-between;
align-items: center;
height: var(--header-height);
padding: 0 var(--spacing-lg);
}
/* Logo 區域 */
.header-nav__logo { /* ... */ }
/* 主導航菜單 */
.header-nav__menu { /* ... */ }
/* --- 3. Components --- */
/* Component: NavItem 導航項 */
.nav-item {
position: relative;
display: inline-block;
padding: var(--spacing-sm) var(--spacing-md);
color: var(--color-text-primary);
font-size: var(--font-size-base);
transition: color var(--transition-fast);
}
/* Modifier: .nav-item--active 當前態 */
.nav-item--active {
color: var(--color-brand-primary);
font-weight: 600;
}
/* State: .nav-item:hover 懸浮態 */
.nav-item:hover {
color: var(--color-brand-primary);
}
/* --- 4. Responsive --- */
@media (max-width: 768px) {
.header-nav__menu { display: none; }
.header-nav__toggle { display: block; }
}
/* --- 5. Browser Hacks & Fixes --- */
/* [IE11] Flex 最小寬度錯誤修復 */
@media all and (-ms-high-contrast: none), (-ms-high-contrast: active) {
.header-nav__menu { min-width: 0; }
}
/* ----------------------------------------------------------------
TABLE OF CONTENTS
1. Reset & Base
2. Layout Structure
2.1 Container
2.2 Logo
2.3 Menu
3. Components
3.1 NavItem
3.2 Dropdown
3.3 SearchBox
4. Responsive
5. Browser Hacks
---------------------------------------------------------------- */
配合編輯器「折疊區域」功能,實現一鍵導航。
/* Component: Dropdown 下拉菜單
*
* 結構:
* .dropdown (容器)
* ├── .dropdown__trigger (觸發器)
* │ └── .dropdown__icon (箭頭圖標)
* └── .dropdown__panel (面板)
* ├── .dropdown__header (標題)
* ├── .dropdown__list (列表)
* │ └── .dropdown__item (選項)
* └── .dropdown__footer (底部操作)
*
* 狀態:.dropdown--open, .dropdown--disabled
* 修飾:.dropdown--right, .dropdown--large
*/
.sticky-header {
position: sticky; /* [關鍵] 粘性定位實現吸頂 */
top: 0; /* [關鍵] 必須設置,否則不生效 */
z-index: 1000; /* [層級] 高於內容區,低於彈窗 */
will-change: transform; /* [性能] 提示瀏覽器優化動畫 */
/* [Hack] iOS Safari 需 -webkit-sticky 前綴,由 Autoprefixer 自動處理 */
}
stylelint-comment-standard 或自定義規則,CI 中強制校驗註釋完整性。CSS 註釋是「寫給未來的自己和隊友看的文檔」。建立分層規範、使用結構化模板、配合工具鏈強制執行,能將樣式表從「寫時只讀、改時崩潰」轉化為「結構清晰、意圖明確、維護無憂」的工程資產。從今天開始,為每個模塊寫下第一行目錄註釋吧。