方法 Site.Pages 詳解:獲取當(dāng)前語言全部頁面的集合)
開發(fā)工具前端CLI【免費(fèi)下載鏈接】hugoThe world’s fastest framework for building websites.項(xiàng)目地址https://gitcode.com/gh_mirrors/hu/hugo點(diǎn)擊查看免費(fèi)下載Site.Pages是 Hugo 模板中用于獲取站點(diǎn)頁面集合的核心方法它返回當(dāng)前語言下所有頁面包括主頁、section 頁、taxonomy 頁、term 頁與常規(guī)頁面并按照 Hugo 內(nèi)置的“默認(rèn)排序規(guī)則”排列。本文以 Pages 方法文檔 為主線結(jié)合 Hugo 源碼hugolib/site.go、resources/page/pages_sort.go講解其行為邊界、默認(rèn)排序規(guī)則、與RegularPages的取舍以及排序/分組等實(shí)戰(zhàn)用法幫助你寫出正確、高效的列表模板。方法簽名與返回類型Pages是定義在Site對象上的方法模板中通過SITE.Pages調(diào)用在頁面模板中通常寫作.Site.Pages。其返回類型為page.Pages即[]page.Page的切片類型見 resources/page/pages.go可直接用于range遍歷也可繼續(xù)調(diào)用排序、篩選、分組等方法鏈。Front matter 中的元信息如下returnType: page.Pages signatures: [SITE.Pages]在源碼層面hugolib/site.go 中的實(shí)現(xiàn)如下// Pages returns all pages. // This is for the current language only. func (s *Site) Pages() page.Pages { s.CheckReady() return s.pageMap.getPagesInSection( pageMapQueryPagesInSection{ Path: , KeyPart: global, Include: pagePredicates.ShouldListGlobal.BoolFunc(), Recursive: true, IncludeSelf: true, }, ) }從中可以看出三個(gè)關(guān)鍵行為僅限當(dāng)前語言注釋明確寫有 “This is for the current language only”多語言站點(diǎn)中它不會(huì)跨語言返回頁面遞歸 包含自身Recursive: true表示遍歷整個(gè)內(nèi)容樹的全部層級(jí)IncludeSelf: true表示連“根節(jié)點(diǎn)”本身即主頁也包含在內(nèi)由謂詞過濾Include使用pagePredicates.ShouldListGlobal只有通過該謂詞的頁面才會(huì)進(jìn)入結(jié)果集。ShouldListGlobal 謂詞做了什么ShouldListGlobal定義在 hugolib/content_map_page.go其實(shí)現(xiàn)為ShouldListGlobal: func(p *pageState) predicate.Match { return predicate.BoolMatch(p.m.shouldList(true)) },它調(diào)用頁面元數(shù)據(jù)上的shouldList(true)來判斷頁面是否應(yīng)被“全局列出”。從源碼結(jié)構(gòu)可以推斷該謂詞綜合了頁面類型、發(fā)布狀態(tài)draft / future / expired、build配置等多項(xiàng)條件——這意味著處于草稿、未發(fā)布或已過期狀態(tài)的頁面默認(rèn)不會(huì)出現(xiàn)在.Site.Pages的結(jié)果中除非在構(gòu)建時(shí)顯式啟用對應(yīng)狀態(tài)。Site.Pages 到底包含哪些頁面根據(jù) Pages 方法文檔返回集合包含以下全部頁面種類頁面種類說明主頁home page站點(diǎn)根_index.md對應(yīng)的頁面Section 頁面各內(nèi)容分區(qū)如content/books/對應(yīng)的_index.md頁面Taxonomy 頁面分類頁如標(biāo)簽、類別Term 頁面具體的分類條目頁常規(guī)頁面regular pages普通內(nèi)容頁如博客文章?lián)Q言之Site.Pages是整個(gè)站點(diǎn)頁面樹的扁平化全集按當(dāng)前語言過濾后而不是某個(gè) section 的子集。如果你只想遍歷博客文章這類常規(guī)頁面官方文檔明確指出In most cases you should use theRegularPagesmethod instead.這是因?yàn)椴┛?、新聞流等最常見的列表場景只需要“常?guī)頁面”而Site.Pages會(huì)把主頁、section 索引頁等結(jié)構(gòu)型頁面一并帶出需要額外過濾。與 RegularPages / Sections / AllPages 的對比同一組方法都定義在 hugolib/site.go 中方便對照RegularPages 方法文檔只返回常規(guī)頁面且同樣按默認(rèn)排序。其實(shí)現(xiàn)hugolib/site.go在ShouldListGlobal基礎(chǔ)上額外疊加了KindPage謂詞即ShouldListGlobal.And(pagePredicates.KindPage)Sections 方法文檔只返回頂級(jí)section 頁面AllPages見 AllPages 方法文檔返回所有語言的頁面已在 v0.156.0 中標(biāo)記為 deprecated官方建議改用其他方式源碼中通過hugo.Deprecate打印棄用提示見 hugolib/site.goAllRegularPages返回所有語言的常規(guī)頁面未棄用。默認(rèn)排序規(guī)則DefaultPageSortSite.Pages返回的集合“按默認(rèn)排序順序排列”。什么是默認(rèn)排序源碼 resources/page/pages_sort.go 給出了精確答案// DefaultPageSort is the default sort func for pages in Hugo: // Order by Ordinal, Weight, Date, LinkTitle and then full file path. DefaultPageSort func(p1, p2 Page) bool { o1, o2 : getOrdinals(p1, p2) if o1 ! o2 o1 ! -1 o2 ! -1 { return o1 o2 } // Weight0, as by the weight of the taxonomy entrie in the front matter. w01, w02 : getWeight0s(p1, p2) if w01 ! w02 w01 ! -1 w02 ! -1 { return w01 w02 } // ... 依次比較 Weight、Date、LinkTitle、完整路徑 }默認(rèn)排序的完整優(yōu)先級(jí)注釋總結(jié)為 “Order by Ordinal, Weight, Date, LinkTitle and then full file path”O(jiān)rdinal序號(hào)頁面在內(nèi)容中的出現(xiàn)順序兩個(gè)頁面都有明確序號(hào)時(shí)優(yōu)先按此比較Weight0taxonomy 條目在 front matter 中的權(quán)重Weight權(quán)重front matter 中手動(dòng)指定的weight權(quán)重為 0 的頁面排在帶權(quán)重頁面之前Date日期按日期倒序新的在前見p1.Date().Unix() p2.Date().Unix()LinkTitle鏈接標(biāo)題按LinkTitle使用語言感知的 collator 排序完整文件路徑以上都相同時(shí)按規(guī)范化完整路徑排序保證結(jié)果確定性。需要特別注意的是由于Site.Pages的默認(rèn)排序中Date 是關(guān)鍵因子其返回順序并不等同于目錄結(jié)構(gòu)的層級(jí)順序也不保證與你在模板中看到的一致——因此依賴排序結(jié)果時(shí)最好顯式調(diào)用排序方法而不是依賴默認(rèn)行為。模板中的實(shí)戰(zhàn)用法基礎(chǔ)遍歷渲染全部頁面的標(biāo)題與鏈接Pages 方法文檔 給出的最小示例{{ range .Site.Pages }} h2a href{{ .RelPermalink }}{{ .LinkTitle }}/a/h2 {{ end }}.RelPermalink頁面的相對永久鏈接.LinkTitle優(yōu)先取 front matter 中的linkTitle未設(shè)置時(shí)回退到title。顯式排序使用 Pages 的排序方法page.Pages提供了一整套排序方法定義在 resources/page/pages_sort.go常用如下方法行為ByWeight()按 front matterweight升序ByTitle()按標(biāo)題語言感知 collator排序ByLinkTitle()按鏈接標(biāo)題排序ByDate()/ByPublishDate()按日期排序日期字段不同ByExpiryDate()/ByLastmod()按過期日期 / 最后修改時(shí)間排序ByLength()按內(nèi)容長度排序ByLanguage()按語言排序ByParam按自定義 front matter 參數(shù)排序Reverse()反轉(zhuǎn)當(dāng)前順序Limit(n)只保留前 n 個(gè)見 pages_sort.go例如按標(biāo)題排序輸出{{ range .Site.Pages.ByTitle }} h2a href{{ .RelPermalink }}{{ .Title }}/a/h2 {{ end }}取最新 5 篇文章的經(jīng)典寫法RegularPagesByDateLimit{{ range first 5 (where .Site.RegularPages Type posts).ByDate.Reverse }} a href{{ .RelPermalink }}{{ .Title }}/a {{ end }}分組GroupBy 系列方法如果需要按參數(shù)、日期等維度分組輸出可以使用 resources/page/pagegroup.go 中的GroupBy系列方法例如按年份分組歸檔{{ range .Site.Pages.GroupByDate 2006 }} h3{{ .Key }}/h3 {{ range .Pages }} a href{{ .RelPermalink }}{{ .Title }}/a {{ end }} {{ end }}GroupByDate、GroupByPublishDate、GroupByLastmod、GroupByParam、GroupByParamDate等方法簽名均位于 pagegroup.go均支持傳入排序方向asc/desc作為可選參數(shù)。最佳實(shí)踐與常見誤區(qū)列表頁優(yōu)先用RegularPages博客文章、新聞列表等場景應(yīng)使用.Site.RegularPages見 RegularPages 方法文檔避免混入主頁、section 與 taxonomy 頁面也避免額外的類型過濾不要依賴默認(rèn)排序默認(rèn)排序Ordinal → Weight → Date → LinkTitle → 路徑較復(fù)雜且日期參與排序建議根據(jù)場景顯式調(diào)用ByTitle、ByDate等方法保證輸出可控多語言站點(diǎn)注意作用域.Site.Pages只返回當(dāng)前語言頁面跨語言場景請勿依賴AllPages已廢棄見 AllPages 方法文檔結(jié)果受發(fā)布狀態(tài)影響draft、future、expired 頁面默認(rèn)不會(huì)出現(xiàn)在結(jié)果中調(diào)試時(shí)注意檢查構(gòu)建時(shí)的--buildDrafts等選項(xiàng)性能Site.Pages是全站級(jí)遍歷查詢Recursive: true在頁面量極大的站點(diǎn)中應(yīng)盡量避免在每次渲染中重復(fù)做重排序可考慮在緩存層或 section 范圍內(nèi)縮小數(shù)據(jù)面。小結(jié)Site.Pages是理解 Hugo 頁面集合模型的入口它回答“當(dāng)前語言下站點(diǎn)有哪些頁面”返回按默認(rèn)排序的全量集合。通過結(jié)合源碼可以確認(rèn)其行為邊界僅當(dāng)前語言、遞歸包含全部層級(jí)、受發(fā)布狀態(tài)過濾并通過page.Pages豐富的排序與分組方法實(shí)現(xiàn)各種列表需求。對于大多數(shù)內(nèi)容列表場景請優(yōu)先使用RegularPages如需頂級(jí)分區(qū)導(dǎo)航則可參考 Sections 方法文檔。相關(guān)實(shí)現(xiàn)可進(jìn)一步閱讀 hugolib/site.go 與 resources/page/pages_sort.go。贊分享開發(fā)工具前端CLI【免費(fèi)下載鏈接】hugoThe world’s fastest framework for building websites.項(xiàng)目地址https://gitcode.com/gh_mirrors/hu/hugo點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Hugo 模板中 PAGER.Pages 方法詳解分頁器當(dāng)前頁頁面集合的獲取與實(shí)戰(zhàn)Hugo 模板中 PAGER.Pages 方法詳解分頁器當(dāng)前頁頁面集合的獲取與實(shí)戰(zhàn) 導(dǎo)讀 PAGER.Pages 是 Hugo 模板系統(tǒng)中分頁P(yáng)aginat開發(fā)工具前端CLIHugo 多語言站點(diǎn) AllTranslations 方法詳解獲取全部語言翻譯頁面并按語言權(quán)重排序Hugo 多語言站點(diǎn) AllTranslations 方法詳解獲取全部語言翻譯頁面并按語言權(quán)重排序 導(dǎo)讀 AllTranslations 是 Hugo 頁面開發(fā)工具前端CLIHugo Page 方法詳解RegularPagesRecursive 遞歸獲取當(dāng)前 Section 及全部子孫 Section 的常規(guī)頁面Hugo Page 方法詳解RegularPagesRecursive 遞歸獲取當(dāng)前 Section 及全部子孫 Section 的常規(guī)頁面 RegularP開發(fā)工具前端CLI創(chuàng)作聲明:本文部分內(nèi)容由AI輔助生成(AIGC),僅供參考