本文轉載自https://github.com/fex-team/styleguide
1 前言
2 代碼風格
2.1 縮進與換行
2.2 命名
2.3 标簽
2.4 屬性
3 通用
3.1 DOCTYPE
3.2 編碼
3.3 CSS和JavaScript引入
4 head
4.1 title
4.2 favicon
4.3 viewport
5 圖檔
6 表單
6.1 控件标題
6.2 按鈕
6.3 可通路性 (A11Y)
7 多媒體
8 模闆中的 HTML
HTML作為描述網頁結構的超文本标記語言,在百度一直有着廣泛的應用。本文檔的目标是使HTML代碼風格保持一緻,容易被了解和被維護。
示例:
解釋:
過長的代碼不容易閱讀與維護。但是考慮到 HTML 的特殊性,不做硬性要求。
同一個頁面中,不同的元素包含相同的 id,不符合 id 的屬性含義。并且使用 document.getElementById 時可能導緻難以追查的問題。
不允許 class 隻用于讓 JavaScript 選擇某些元素,class 應該具有明确的語義和樣式。否則容易導緻 css class 泛濫。
使用 id、屬性選擇作為 hook 是更好的方式。
IE 浏覽器會混淆元素的 id 和 name 屬性, document.getElementById 可能獲得不期望的元素。是以在對元素的 id 與 name 屬性的命名需要非常小心。
一個比較好的實踐是,為 id 和 name 使用不同的命名法。
常見無需自閉合标簽有input、br、img、hr等。
對代碼體積要求非常嚴苛的場景,可以例外。比如:第三方頁面使用的投放系統。
比如 div 不得置于 p 中,tbody 必須置于 table 中。
詳細的标簽嵌套規則參見HTML DTD中的 <code>Elements</code> 定義部分。
下面是常見标簽語義
p - 段落
h1,h2,h3,h4,h5,h6 - 層級标題
strong,em - 強調
ins - 插入
del - 删除
abbr - 縮寫
code - 代碼辨別
cite - 引述來源作品的标題
q - 引用
blockquote - 一段或長篇引用
ul - 無序清單
ol - 有序清單
dl,dt,dd - 定義清單
在相容性允許的情況下應盡量保持語義正确性。對網格對齊和拉伸性有嚴格要求的場景允許例外,如多列複雜表單。
不允許使用單引号,不允許不使用引号。
使用字首有助于區分自定義屬性和标準定義的屬性。
有助于提高頁面的可通路性,如:讓語音合成工具确定其所應該采用的發音,令翻譯工具确定其翻譯語言等。
見 HTML5 Charset能用嗎 一文。
UTF-8 編碼具有更廣泛的适應性。BOM 在使用程式或工具處理檔案時可能造成不必要的幹擾。
<code>text/css</code> 和 <code>text/javascript</code> 是 type 的預設值。
結構-樣式-行為的代碼分離,對于提高代碼的可閱讀性和維護性都有好處。
在頁面渲染的過程中,新的CSS可能導緻元素的樣式重新計算和繪制,頁面閃爍。
将 script 放在頁面中間将阻斷頁面的渲染。出于性能方面的考慮,如非必要,請遵守此條建議。
使用 <code>protocol-relative URL</code> 引入 CSS,在 <code>IE7/8</code> 下,會發兩次請求。是否使用 <code>protocol-relative URL</code> 應充分考慮頁面針對的環境。
title 中如果包含 ascii 之外的字元,浏覽器需要知道字元編碼類型才能進行解碼,否則可能導緻亂碼。
在未指定 favicon 時,大多數浏覽器會請求 Web Server 根目錄下的 favicon.ico 。為了保證favicon可通路,避免404,必須遵循以下兩種方法之一:
在 Web Server 根目錄放置 favicon.ico 檔案。
使用 link 指定 favicon。
viewport meta tag可以設定可視區域的寬度和初始縮放大小,避免在移動裝置上出現頁面展示不正常。
比如,在頁面寬度小于 980px 時,若需 iOS 裝置友好,應當設定 viewport 的 width 值來适應你的頁面寬度。同時因為不同移動裝置分辨率不同,在設定時,應當使用 device-width 和 device-height 變量。
另外,為了使 viewport 正常工作,在頁面内容樣式布局設計上也要做相應調整,如避免絕對定位等。關于 viewport 的更多介紹,可以參見 Safari Web Content Guide的介紹
src 取值為空,會導緻部分浏覽器重新加載一次目前頁面,參考:<https://developer.yahoo.com/performance/rules.html#emptysrc>;
多餘的 title 影響看圖體驗,并且增加了頁面尺寸。
可以提高圖檔加載失敗時的使用者體驗。
産品 logo、使用者頭像、使用者産生的圖檔等有潛在下載下傳需求的圖檔,以 img 形式實作,能友善使用者下載下傳。
無下載下傳需求的圖檔,比如:icon、背景、代碼使用的圖檔等,盡可能采用 css 背景圖實作。
有兩種方式:
将控件置于 label 内。
label 的 for 屬性指向控件的 id。
推薦使用第一種,減少不必要的 id。如果 DOM 結構不允許直接嵌套,則應使用第二種。
button 元素的預設 type 為 submit,如果被置于 form 元素中,點選後将導緻表單送出。為顯示區分其作用友善了解,必須給出 type 屬性。
由于浏覽器相容性問題,使用按鈕的 name 屬性會帶來許多難以發現的問題。具體情況可參考此文。
負責主要功能的按鈕應相對靠前,以提高可通路性。如果在 CSS 中指定了 <code>float: right</code> 則可能導緻視覺上主按鈕在前,而 DOM 中主按鈕靠後的情況。
當浏覽器 JS 運作錯誤或關閉 JS 時,送出功能将無法工作。如果正确指定了 form 元素的 action 屬性和表單控件的 name 屬性時,送出仍可繼續進行。
根據内容類型指定輸入框類型,能獲得能友好的輸入體驗。
音頻應盡可能覆寫到如下格式:
MP3
WAV
Ogg
視訊應盡可能覆寫到如下格式:
MP4
WebM