 time.Duration 完整指南：以時間單位與數(shù)值構(gòu)造時長并調(diào)用 Duration 方法)
Hugo 模板函數(shù) time.Duration 完整指南以時間單位與數(shù)值構(gòu)造時長并調(diào)用 Duration 方法【免費(fèi)下載鏈接】hugoThe world’s fastest framework for building websites.項(xiàng)目地址: https://gitcode.com/gh_mirrors/hu/hugotime.Duration是 Hugo 模板系統(tǒng)time命名空間下的核心函數(shù)它接收一個時間單位如hour、second和一個數(shù)值返回 Go 標(biāo)準(zhǔn)的time.Duration值隨后即可調(diào)用Seconds、Minutes、Hours等Duration方法進(jìn)行換算與格式化。本文基于 Hugo 當(dāng)前源碼實(shí)現(xiàn)位于 tpl/time/time.go與該函數(shù)的官方文檔docs/content/en/functions/time/Duration.md完整講解其簽名、單位取值、源碼實(shí)現(xiàn)原理、與time.ParseDuration的差異以及在實(shí)際模板中的典型用法。函數(shù)簽名與返回值根據(jù)文檔中聲明的簽名time.Duration TIME_UNIT NUMBERTIME_UNIT字符串表示時間單位支持全稱與縮寫見下文單位表NUMBER數(shù)值表示該單位的數(shù)量可以是整數(shù)或可轉(zhuǎn)換為整數(shù)的字符串返回值time.Duration即 Go 標(biāo)準(zhǔn)庫time包中的時長類型。同時該函數(shù)注冊了別名duration因此time.Duration與duration兩種寫法等價。別名注冊位于 tpl/time/init.go其中還給出了管道用法示例{{ mul 60 60 | duration second }} → 1h0m0s即先計(jì)算60 * 60 3600再以second為單位構(gòu)造時長得到1h0m0s。支持的合法時間單位time.Duration的第二個參數(shù)時間單位必須是下表所列取值之一包含全稱與縮寫DurationValid time unitshourshour、hminutesminute、msecondssecond、smillisecondsmillisecond、msmicrosecondsmicrosecond、us、μsnanosecondsnanosecond、ns其中微秒同時支持 ASCII 縮寫us與希臘字母μs兩種寫法毫秒、納秒等則各有一個全稱與一個縮寫。超出該表的單位例如復(fù)數(shù)形式hours、minutes會被判定為非法觸發(fā)錯誤詳見下文源碼解析。基礎(chǔ)用法示例文檔給出的標(biāo)準(zhǔn)示例——用time.Duration計(jì)算一天包含多少秒{{ $duration : time.Duration hour 24 }} {{ printf There are %.0f seconds in one day. $duration.Seconds }}渲染結(jié)果為There are 86400 seconds in one day.這里time.Duration hour 24構(gòu)造了 24 小時的時長隨后調(diào)用Duration方法Seconds將其換算為秒數(shù)86400再通過printf以%.0f格式化輸出避免浮點(diǎn)數(shù)小數(shù)點(diǎn)后的尾零。源碼實(shí)現(xiàn)原理time.Duration的底層實(shí)現(xiàn)在 tpl/time/time.go邏輯非常清晰共分三步單位字符串轉(zhuǎn)換與校驗(yàn)函數(shù)內(nèi)部維護(hù)了一張單位查找表durationUnits將每個合法單位全稱與縮寫映射到 Go 標(biāo)準(zhǔn)庫的時長常量var durationUnits map[string]time.Duration{ nanosecond: time.Nanosecond, ns: time.Nanosecond, microsecond: time.Microsecond, us: time.Microsecond, μs: time.Microsecond, millisecond: time.Millisecond, ms: time.Millisecond, second: time.Second, s: time.Second, minute: time.Minute, m: time.Minute, hour: time.Hour, h: time.Hour, }數(shù)值轉(zhuǎn)換通過cast.ToStringE與cast.ToInt64E完成參數(shù)類型轉(zhuǎn)換。這意味著數(shù)值參數(shù)既可以直接傳整數(shù)也可以傳數(shù)字字符串如30Hugo 會將其轉(zhuǎn)為int64。乘法構(gòu)造時長最終結(jié)果由time.Duration(n) * unitDuration計(jì)算得出即數(shù)值乘以單位對應(yīng)的時長常量。從源碼結(jié)構(gòu)看time.Duration本質(zhì)上是「單位查表 數(shù)值轉(zhuǎn)換 標(biāo)量乘法」的封裝不涉及任何時間基準(zhǔn)如當(dāng)前時刻或時區(qū)因此它是一個純函數(shù)式的換算工具。錯誤處理與邊界當(dāng)傳入非法單位時函數(shù)返回錯誤%q is not a valid duration unit例如傳入復(fù)數(shù)形式hours不在表中就會觸發(fā)該錯誤tpl/time/time_test.go中的TestDuration用例tpl/time/time_test.go明確驗(yàn)證了這一行為其中{hours, 20, false}一項(xiàng)斷言了非法單位必須返回 error。同一測試還覆蓋了全稱/縮寫/μs變體與字符串?dāng)?shù)值{hour, 30, 30 * time.Hour}等 15 組場景可作為理解函數(shù)行為的參考。與 time.ParseDuration 的對比time命名空間還提供另一個構(gòu)造時長的函數(shù)time.ParseDuration文檔見 docs/content/en/functions/time/ParseDuration.md實(shí)現(xiàn)見 tpl/time/time.go。二者都返回time.Duration但適用場景不同維度time.Durationtime.ParseDuration入?yún)⑿问姜?dú)立的單位參數(shù) 數(shù)值參數(shù)單個時長字符串如300ms、-1.5h、2h45m是否支持組合不支持一次只能指定一種單位支持可混合多種單位如2h45m是否支持負(fù)數(shù)/小數(shù)數(shù)值可為負(fù)源碼未限制但單位單一支持帶符號與小數(shù)如-1.5h實(shí)現(xiàn)方式查表乘法直接調(diào)用 Go 標(biāo)準(zhǔn)庫time.ParseDuration典型場景若數(shù)據(jù)源分別給出「單位」和「數(shù)量」兩個字段例如配置項(xiàng)拆分為unit: hour與value: 24用time.Duration更自然若數(shù)據(jù)源直接給出一段可讀時長字符串則用time.ParseDuration更直接。Duration 方法讓返回值發(fā)揮作用time.Duration的返回值可以調(diào)用Duration命名空間下的全部方法方法清單見 docs/content/en/methods/duration/_index.md包括Seconds返回以秒計(jì)的浮點(diǎn)數(shù)float64示例見 docs/content/en/methods/duration/Seconds.md例如time.ParseDuration 3.5h2.5m1.5s的.Seconds結(jié)果為12751.5Minutes、Hours分別返回以分鐘、小時計(jì)的浮點(diǎn)數(shù)Milliseconds、Microseconds、Nanoseconds返回對應(yīng)粒度的整數(shù)值A(chǔ)bs返回絕對值的time.DurationRound、Truncate按指定時長粒度進(jìn)行舍入與截斷。這些方法同樣適用于time.Duration的返回值例如開篇示例中的$duration.Seconds。實(shí)際應(yīng)用模板中的典型場景在真實(shí)站點(diǎn)模板中time.Duration常用于把「數(shù)值 單位」形式的配置轉(zhuǎn)換為可讀時長或進(jìn)行跨單位換算。例如從站點(diǎn)參數(shù)讀取緩存過期時長并格式化為秒{{ $ttlValue : site.Params.cacheTTL.value | default 30 }} {{ $ttlUnit : site.Params.cacheTTL.unit | default minute }} {{ $ttl : time.Duration $ttlUnit $ttlValue }} {{ printf Cache TTL is %.0f seconds (%v). $ttl.Seconds $ttl }}或?qū)r長精確格式化到小時{{ $d : time.Duration minute 90 }} {{ printf %v $d }} !-- 1h30m0s -- {{ printf %.1f hours $d.Hours }} !-- 1.5 hours --需要強(qiáng)調(diào)的是time.Duration只負(fù)責(zé)「構(gòu)造時長」不涉及具體時間點(diǎn)若需要結(jié)合當(dāng)前時刻或特定時區(qū)做日期運(yùn)算應(yīng)搭配time.Now、time.AsTime、time.In實(shí)現(xiàn)同見 tpl/time/time.go等函數(shù)使用。小結(jié)time.Duration以極簡的「單位 數(shù)值」二元入?yún)?fù)用了 Go 標(biāo)準(zhǔn)庫的時長體系為 Hugo 模板提供了清晰、可讀的時長構(gòu)造方式。理解其單位表含μs變體、非法單位報錯行為以及與time.ParseDuration的分工能幫助你在模板中寫出既準(zhǔn)確又易維護(hù)的時間換算代碼。【免費(fèi)下載鏈接】hugoThe world’s fastest framework for building websites.項(xiàng)目地址: https://gitcode.com/gh_mirrors/hu/hugo創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Hugo 模板函數(shù) time.Duration 完整指南：以時間單位與數(shù)值構(gòu)造時長并調(diào)用 Duration 方法
Hugo 模板函數(shù) time.Duration 完整指南以時間單位與數(shù)值構(gòu)造時長并調(diào)用 Duration 方法【免費(fèi)下載鏈接】hugoThe world’s fastest framework for building websites.項(xiàng)目地址: https://gitcode.com/gh_mirrors/hu/hugotime.Duration是 Hugo 模板系統(tǒng)time命名空間下的核心函數(shù)它接收一個時間單位如hour、second和一個數(shù)值返回 Go 標(biāo)準(zhǔn)的time.Duration值隨后即可調(diào)用Seconds、Minutes、Hours等Duration方法進(jìn)行換算與格式化。本文基于 Hugo 當(dāng)前源碼實(shí)現(xiàn)位于 tpl/time/time.go與該函數(shù)的官方文檔docs/content/en/functions/time/Duration.md完整講解其簽名、單位取值、源碼實(shí)現(xiàn)原理、與time.ParseDuration的差異以及在實(shí)際模板中的典型用法。函數(shù)簽名與返回值根據(jù)文檔中聲明的簽名time.Duration TIME_UNIT NUMBERTIME_UNIT字符串表示時間單位支持全稱與縮寫見下文單位表NUMBER數(shù)值表示該單位的數(shù)量可以是整數(shù)或可轉(zhuǎn)換為整數(shù)的字符串返回值time.Duration即 Go 標(biāo)準(zhǔn)庫time包中的時長類型。同時該函數(shù)注冊了別名duration因此time.Duration與duration兩種寫法等價。別名注冊位于 tpl/time/init.go其中還給出了管道用法示例{{ mul 60 60 | duration second }} → 1h0m0s即先計(jì)算60 * 60 3600再以second為單位構(gòu)造時長得到1h0m0s。支持的合法時間單位time.Duration的第二個參數(shù)時間單位必須是下表所列取值之一包含全稱與縮寫DurationValid time unitshourshour、hminutesminute、msecondssecond、smillisecondsmillisecond、msmicrosecondsmicrosecond、us、μsnanosecondsnanosecond、ns其中微秒同時支持 ASCII 縮寫us與希臘字母μs兩種寫法毫秒、納秒等則各有一個全稱與一個縮寫。超出該表的單位例如復(fù)數(shù)形式hours、minutes會被判定為非法觸發(fā)錯誤詳見下文源碼解析。基礎(chǔ)用法示例文檔給出的標(biāo)準(zhǔn)示例——用time.Duration計(jì)算一天包含多少秒{{ $duration : time.Duration hour 24 }} {{ printf There are %.0f seconds in one day. $duration.Seconds }}渲染結(jié)果為There are 86400 seconds in one day.這里time.Duration hour 24構(gòu)造了 24 小時的時長隨后調(diào)用Duration方法Seconds將其換算為秒數(shù)86400再通過printf以%.0f格式化輸出避免浮點(diǎn)數(shù)小數(shù)點(diǎn)后的尾零。源碼實(shí)現(xiàn)原理time.Duration的底層實(shí)現(xiàn)在 tpl/time/time.go邏輯非常清晰共分三步單位字符串轉(zhuǎn)換與校驗(yàn)函數(shù)內(nèi)部維護(hù)了一張單位查找表durationUnits將每個合法單位全稱與縮寫映射到 Go 標(biāo)準(zhǔn)庫的時長常量var durationUnits map[string]time.Duration{ nanosecond: time.Nanosecond, ns: time.Nanosecond, microsecond: time.Microsecond, us: time.Microsecond, μs: time.Microsecond, millisecond: time.Millisecond, ms: time.Millisecond, second: time.Second, s: time.Second, minute: time.Minute, m: time.Minute, hour: time.Hour, h: time.Hour, }數(shù)值轉(zhuǎn)換通過cast.ToStringE與cast.ToInt64E完成參數(shù)類型轉(zhuǎn)換。這意味著數(shù)值參數(shù)既可以直接傳整數(shù)也可以傳數(shù)字字符串如30Hugo 會將其轉(zhuǎn)為int64。乘法構(gòu)造時長最終結(jié)果由time.Duration(n) * unitDuration計(jì)算得出即數(shù)值乘以單位對應(yīng)的時長常量。從源碼結(jié)構(gòu)看time.Duration本質(zhì)上是「單位查表 數(shù)值轉(zhuǎn)換 標(biāo)量乘法」的封裝不涉及任何時間基準(zhǔn)如當(dāng)前時刻或時區(qū)因此它是一個純函數(shù)式的換算工具。錯誤處理與邊界當(dāng)傳入非法單位時函數(shù)返回錯誤%q is not a valid duration unit例如傳入復(fù)數(shù)形式hours不在表中就會觸發(fā)該錯誤tpl/time/time_test.go中的TestDuration用例tpl/time/time_test.go明確驗(yàn)證了這一行為其中{hours, 20, false}一項(xiàng)斷言了非法單位必須返回 error。同一測試還覆蓋了全稱/縮寫/μs變體與字符串?dāng)?shù)值{hour, 30, 30 * time.Hour}等 15 組場景可作為理解函數(shù)行為的參考。與 time.ParseDuration 的對比time命名空間還提供另一個構(gòu)造時長的函數(shù)time.ParseDuration文檔見 docs/content/en/functions/time/ParseDuration.md實(shí)現(xiàn)見 tpl/time/time.go。二者都返回time.Duration但適用場景不同維度time.Durationtime.ParseDuration入?yún)⑿问姜?dú)立的單位參數(shù) 數(shù)值參數(shù)單個時長字符串如300ms、-1.5h、2h45m是否支持組合不支持一次只能指定一種單位支持可混合多種單位如2h45m是否支持負(fù)數(shù)/小數(shù)數(shù)值可為負(fù)源碼未限制但單位單一支持帶符號與小數(shù)如-1.5h實(shí)現(xiàn)方式查表乘法直接調(diào)用 Go 標(biāo)準(zhǔn)庫time.ParseDuration典型場景若數(shù)據(jù)源分別給出「單位」和「數(shù)量」兩個字段例如配置項(xiàng)拆分為unit: hour與value: 24用time.Duration更自然若數(shù)據(jù)源直接給出一段可讀時長字符串則用time.ParseDuration更直接。Duration 方法讓返回值發(fā)揮作用time.Duration的返回值可以調(diào)用Duration命名空間下的全部方法方法清單見 docs/content/en/methods/duration/_index.md包括Seconds返回以秒計(jì)的浮點(diǎn)數(shù)float64示例見 docs/content/en/methods/duration/Seconds.md例如time.ParseDuration 3.5h2.5m1.5s的.Seconds結(jié)果為12751.5Minutes、Hours分別返回以分鐘、小時計(jì)的浮點(diǎn)數(shù)Milliseconds、Microseconds、Nanoseconds返回對應(yīng)粒度的整數(shù)值A(chǔ)bs返回絕對值的time.DurationRound、Truncate按指定時長粒度進(jìn)行舍入與截斷。這些方法同樣適用于time.Duration的返回值例如開篇示例中的$duration.Seconds。實(shí)際應(yīng)用模板中的典型場景在真實(shí)站點(diǎn)模板中time.Duration常用于把「數(shù)值 單位」形式的配置轉(zhuǎn)換為可讀時長或進(jìn)行跨單位換算。例如從站點(diǎn)參數(shù)讀取緩存過期時長并格式化為秒{{ $ttlValue : site.Params.cacheTTL.value | default 30 }} {{ $ttlUnit : site.Params.cacheTTL.unit | default minute }} {{ $ttl : time.Duration $ttlUnit $ttlValue }} {{ printf Cache TTL is %.0f seconds (%v). $ttl.Seconds $ttl }}或?qū)r長精確格式化到小時{{ $d : time.Duration minute 90 }} {{ printf %v $d }} !-- 1h30m0s -- {{ printf %.1f hours $d.Hours }} !-- 1.5 hours --需要強(qiáng)調(diào)的是time.Duration只負(fù)責(zé)「構(gòu)造時長」不涉及具體時間點(diǎn)若需要結(jié)合當(dāng)前時刻或特定時區(qū)做日期運(yùn)算應(yīng)搭配time.Now、time.AsTime、time.In實(shí)現(xiàn)同見 tpl/time/time.go等函數(shù)使用。小結(jié)time.Duration以極簡的「單位 數(shù)值」二元入?yún)?fù)用了 Go 標(biāo)準(zhǔn)庫的時長體系為 Hugo 模板提供了清晰、可讀的時長構(gòu)造方式。理解其單位表含μs變體、非法單位報錯行為以及與time.ParseDuration的分工能幫助你在模板中寫出既準(zhǔn)確又易維護(hù)的時間換算代碼。【免費(fèi)下載鏈接】hugoThe world’s fastest framework for building websites.項(xiàng)目地址: https://gitcode.com/gh_mirrors/hu/hugo創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考