萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網頁製作 >> Div CSS 教學

CSS 註釋高級用法:準修飾選擇器、代碼標簽、繼承標記三大文檔化模式

超越普通註釋:結構化文檔化 CSS

優秀的 CSS 註釋不僅是說明,更是架構文檔,幫助團隊理解設計意圖、快速定位、維護擴展。

模式一:準修飾選擇器

問題:避免過度限定選擇器(ul.nav),但想文檔化預期 HTML 結構。

解決:將類型選擇器註釋化,保留 class 選擇器:

/*html*/.page-header { }      /* 預期用於 html 標籤 */
 /*ol*/.breadcrumb { }       /* 預期用於 ol 列表 */
 /*p*/.lead { }              /* 預期用於段落 */
/*ul*/.media-list { }       /* 預期用於 ul 列表 */
  • 不影響選擇器優先級/性能(實際為 .page-header)
  • 清晰傳達語義預期,便於重構

模式二:代碼標簽(組件索引)

為組件/模塊打標籤,支援全局搜索跳轉:

/**
 * ^navigation ^header ^global
 */
.site-header { }

/**
 * ^grid ^layout ^responsive
 */
.grid { }
  • 統一前綴 ^,編輯器可直接搜索 ^navigation 定位所有導航相關代碼
  • 標籤體系建議:^component、^layout、^utility、^theme、^vendor

模式三:繼承標記(跨文件關聯)

解決基礎樣式與擴展樣式分離維護的關聯追蹤問題:

基礎文件 (base.css)

/**
 * @extend .btn-primary in theme.css
 */
.btn {
    padding: 8px 16px;
    border-radius: 4px;
    font-weight: 500;
}

擴展文件 (theme.css)

/**
 * @extends .btn in base.css
 */
.btn-primary {
    background: #007bff;
    color: #fff;
}
  • 雙向標記建立強關聯,IDE 可跳轉
  • 適用於:主題覆蓋、響應式擴展、組件變體

其他實用註釋模式

區塊分隔標題

/* ===================================
   Layout / Grid System
   =================================== */

狀態/修飾符說明

.btn {
    /* @state hover - 背景亮化 10% */
    /* @state active - 內陰影 + 下沉 1px */
    /* @state disabled - opacity 0.6, not-allowed */
}

瀏覽器 Hack 標記

.fix-ie-flex {
    display: flex;
    /* [IE10-] 使用舊語法 */
    display: -ms-flexbox;
}

TODO/FIXME 標準化

/* TODO: 支援 RTL 佈局 */
/* FIXME: Safari 下 flex-gap 渲染異常 */
/* REVIEW: 此處 z-index 可能衝突 */

工具鏈整合

  • Stylelint:規範註釋格式、強制區塊標題
  • PostCSS:提取註釋生成文檔站點(postcss-doc)
  • VS Code:// @ts-check 風格的 JSDoc 註釋支援 CSS

相關延伸閱讀

CSS 編碼規範指南:避免過度約束、後代選擇器、合併聲明、格式化

copyright © 萬盛學電腦網 all rights reserved