# 輔助函數（Helpers） 輔助函數幫助您在模版中快速插入內容。輔助函數不能在源文件中使用。 ## 網址 ### url_for 在路徑前加上根路徑，從 Hexo 2.7 開始您應該使用此函數而不是 `config.root + path`。 ``` <%- url_for(path) %> ``` ### relative_url 取得與 `from` 相對的 `to` 路徑。 ``` <%- relative_url(from, to) %> ``` ### gravatar 插入 Gravatar 圖片。 如果你不指定 `options` 參數，將會應用默認參數。否則，你可以將其設置為一個數字，這個數字將會作為 Gravatar 的大小參數。最后，如果你設置它一個對象，它將會被轉換為 Gravatar 的一個查詢字符串參數。 ``` <%- gravatar(email, [options]); ``` **示例：** ``` <%- gravatar('a@abc.com' // http://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787 <%- gravatar('a@abc.com'40 // http://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40 <%- gravatar('a@abc.com'40'http://example.com/image.png' // http://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40&d=http%3A%2F%2Fexample.com%2Fimage.png ``` ## HTML 標簽 ### css 載入 CSS 文件。`path` 可以是數組或字符串，如果 `path` 開頭不是 `/` 或任何協議，則會自動加上根路徑；如果后面沒有加上 `.css` 擴展名的話，也會自動加上。 ``` <%- css(path, ...) %> ``` **示例：** ``` <%- css('style.css' // <link rel="stylesheet" href="/style.css" type="text/css"> <%- css(['style.css''screen.css' // <link rel="stylesheet" href="/style.css" type="text/css"> // <link rel="stylesheet" href="/screen.css" type="text/css"> ``` ### js 載入 JavaScript 文件。`path` 可以是數組或字符串，如果 `path` 開頭不是 `/` 或任何協議，則會自動加上根路徑；如果后面沒有加上 `.js` 擴展名的話，也會自動加上。 ``` <%- js(path, ...) %> ``` **示例：** ``` <%- js('script.js' // <script type="text/javascript" src="/script.js"></script> <%- js(['script.js''gallery.js' // <script type="text/javascript" src="/script.js"></script> // <script type="text/javascript" src="/gallery.js"></script> ``` ### link_to 插入鏈接。 ``` <%- link_to(path, [text], [options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `external` | 在新視窗打開鏈接 | false | | `class` | Class 名稱 | | `id` | ID | **示例：** ``` <%- link_to('http://www.google.com' // <a href="http://www.google.com" title="http://www.google.com">http://www.google.com</a> <%- link_to('http://www.google.com''Google' // <a href="http://www.google.com" title="Google">Google</a> <%- link_to('http://www.google.com''Google'true // <a href="http://www.google.com" title="Google" target="_blank" rel="external">Google</a> ``` ### mail_to 插入電子郵箱鏈接。 ``` <%- mail_to(path, [text], [options]) %> ``` | 參數 | 描述 | | --- | --- | | `class` | Class 名稱 | | `id` | ID | | `subject` | 郵件主題 | | `cc` | 抄送（CC） | | `bcc` | 密送（BCC） | | `body` | 郵件內容 | **示例：** ``` <%- mail_to('a@abc.com' // <a href="mailto:a@abc.com" title="a@abc.com">a@abc.com</a> <%- mail_to('a@abc.com''Email' // <a href="mailto:a@abc.com" title="Email">Email</a> ``` ### image_tag 插入圖片。 ``` <%- image_tag(path, [options]) %> ``` | 參數 | 描述 | | --- | --- | | `alt` | 圖片的替代文字 | | `class` | Class 名稱 | | `id` | ID | | `width` | 圖片寬度 | | `height` | 圖片高度 | ### favicon_tag 插入 favicon。 ``` <%- favicon_tag(path) %> ``` ### feed_tag 插入 feed 鏈接。 ``` <%- feed_tag(path, [options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `title` | Feed 標題 | | `type` | Feed 類型 | atom | ## 條件函數 ### is_current 檢查 `path` 是否符合目前頁面的網址。開啟 `strict` 選項啟用嚴格比對。 ``` <%- is_current(path, [strict]) %> ``` ### is_home 檢查目前是否為首頁。 ``` <%- is_home() %> ``` ### is_post 檢查目前是否為文章。 ``` <%- is_post() %> ``` ### is_archive 檢查目前是否為存檔頁面。 ``` <%- is_archive() %> ``` ### is_year 檢查目前是否為年度歸檔頁面。 ``` <%- is_year() %> ``` ### is_month 檢查目前是否為月度歸檔頁面。 ``` <%- is_month() %> ``` ### is_category 檢查目前是否為分類歸檔頁面。 如果給定一個字符串作為參數，將會檢查目前是否為指定分類。 ``` <%- is_category() %><%-is_categoryhobby ``` ### is_tag 檢查目前是否為標簽歸檔頁面。 如果給定一個字符串作為參數，將會檢查目前是否為指定標簽。 ``` <%- is_tag() %><%-is_taghobby ``` ## 字符串處理 ### trim 清除字符串開頭和結尾的空格。 ``` <%- trim(string) %> ``` ### strip_html 清除字符串中的 HTML 標簽。 ``` <%- strip_html(string) %> ``` **示例：** ``` <%- strip_html('It's not <b>important</b> anymore!') %>// It's not important anymore! ``` ### titlecase 把字符串轉換為正確的 Title case。 ``` <%- titlecase(string) %> ``` **示例：** ``` <%- titlecase('this is an apple') %># This is an Apple ``` ### markdown 使用 Markdown 解析字符串。 ``` <%- markdown(str) %> ``` **示例：** ``` <%- markdown('make me **strong**' // make me <strong>strong</strong> ``` ### render 解析字符串。 ``` <%- render(str, engine, [options]) %> ``` ### word_wrap 使每行的字符串長度不超過 `length`。`length` 預設為 80。 ``` <%- word_wrap(str, [length]) %> ``` **示例：** ``` <%- word_wrap('Once upon a time'8 // Once upon\n a time ``` ### truncate 移除超過 `length` 長度的字符串。 ``` <%- truncate(text, length) %> ``` **示例：** ``` <%- truncate('Once upon a time in a world far far away'17 // Once upon a ti... <%- truncate('Once upon a time in a world far far away'17' ' // Once upon a... <%- truncate('And they found that many people were sleeping better.'25'... (continued)' // And they f... (continued) ``` ## 模板 ### partial 載入其他模板文件，您可在 `locals` 設定區域變量。 ``` <%- partial(layout, [locals], [options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `cache` | 緩存（使用 Fragment cache） | `false` | | `only` | 限制局部變量。在模板中只能使用 `locals` 中設定的變量。 | `false` | ### fragment_cache 局部緩存。它儲存局部內容，下次使用時就能直接使用緩存。 ``` <%- fragment_cache(id, fn); ``` **示例：** ``` <%- fragment_cache('header'function{ return'<header></header>' }) %> ``` ## 日期與時間 ### date 插入格式化的日期。`date` 可以是 UNIX 時間、ISO 字符串、Date 對象或 [Moment.js](http://momentjs.com/) 對象。`format` 默認為 `date_format` 配置信息。 ``` <%- date(date, [format]) %> ``` **示例：** ``` <%- date(Date // 2013-01-01 <%- date(Date'YYYY/M/D' // Jan 1 2013 ``` ### date_xml 插入 XML 格式的日期。`date` 可以是 UNIX 時間、ISO 字符串、Date 對象或 [Moment.js](http://momentjs.com/) 對象。 ``` <%- date_xml(date) %> ``` **示例：** ``` <%- date_xml(Date // 2013-01-01T00:00:00.000Z ``` ### time 插入格式化的時間。`date` 可以是 UNIX 時間、ISO 字符串、Date 對象或 [Moment.js](http://momentjs.com/) 對象。`format` 默認為 `time_format` 配置信息。 ``` <%- time(date, [format]) %> ``` **示例：** ``` <%- time(Date // 13:05:12 <%- time(Date'h:mm:ss a' // 1:05:12 pm ``` ### full_date 插入格式化的日期和時間。`date` 可以是 UNIX 時間、ISO 字符串、Date 對象或 [Moment.js](http://momentjs.com/) 對象。`format` 默認為 `date_format + time_format`。 ``` <%- full_date(date, [format]) %> ``` **示例：** ``` <%- full_date(newDate // Jan 1, 2013 0:00:00 <%- full_date(newDate'dddd, MMMM Do YYYY, h:mm:ss a' // Tuesday, January 1st 2013, 12:00:00 am ``` ### moment [Moment.js](http://momentjs.com/) 函數庫。 ## 列表 ### list_categories 插入分類列表。 ``` <%- list_categories([options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `orderby` | 分類排列方式 | name | | `order` | 分類排列順序。`1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | | `show_count` | 顯示每個分類的文章總數 | true | | `style` | 分類列表的顯示方式。使用 `list` 以無序列表（unordered list）方式顯示。 | list | | `separator` | 分類間的分隔符號。只有在 `style` 不是 `list` 時有用。 | , | | `depth` | 要顯示的分類層級。`0` 顯示所有層級的分類；`-1` 和 `0` 很類似，但是顯示不分層級；`1` 只顯示第一層的分類。 | 0 | | `class` | 分類列表的 class 名稱。 | category | | `transform` | 改變分類名稱顯示方法的函數 | ### list_tags 插入標簽列表。 ``` <%- list_tags([options]) %> ``` | 選項 | 描述 | 預設值 | | --- | --- | --- | | `orderby` | 標簽排列方式 | name | | `order` | 標簽排列順序。`1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | | `show_count` | 顯示每個標簽的文章總數 | true | | `style` | 標簽列表的顯示方式。使用 `list` 以無序列表（unordered list）方式顯示。 | list | | `separator` | 標簽間的分隔符號。只有在 `style` 不是 `list` 時有用。 | , | | `class` | 標簽列表的 class 名稱。 | tag | | `transform` | 改變標簽名稱顯示方法的函數 | | `amount` | 要顯示的標簽數量（0 = 無限制） | 0 | ### list_archives 插入歸檔列表。 ``` <%- list_archives([options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `type` | 類型。此設定可為 `yearly` 或 `monthly`。 | monthly | | `order` | 排列順序。`1`, `asc` 升序；`-1`, `desc` 降序。 | 1 | | `show_count` | 顯示每個歸檔的文章總數 | true | | `format` | 日期格式 | MMMM YYYY | | `style` | 歸檔列表的顯示方式。使用 `list` 以無序列表（unordered list）方式顯示。 | list | | `separator` | 歸檔間的分隔符號。只有在 `style` 不是 `list` 時有用。 | , | | `class` | 歸檔列表的 class 名稱。 | archive | | `transform` | 改變歸檔名稱顯示方法的函數 | ### list_posts 插入文章列表。 ``` <%- list_posts([options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `orderby` | 文章排列方式 | date | | `order` | 文章排列順序。`1`, `asc` 升序；`-1`, `desc` 降序。 | -1 | | `style` | 文章列表的顯示方式。使用 `list` 以無序列表（unordered list）方式顯示。 | list | | `separator` | 文章間的分隔符號。只有在 `style` 不是 `list` 時有用。 | , | | `class` | 文章列表的 class 名稱。 | post | | `amount` | 要顯示的文章數量（0 = 無限制） | 6 | | `transform` | 改變文章名稱顯示方法的函數 | ### tagcloud 插入標簽云。 ``` <%- tagcloud([tags], [options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `min_font` | 最小字體尺寸 | 10 | | `max_font` | 最大字體尺寸 | 20 | | `unit` | 字體尺寸的單位 | px | | `amount` | 標簽總量 | 40 | | `orderby` | 標簽排列方式 | name | | `order` | 標簽排列順序。`1`, `sac` 升序；`-1`, `desc` 降序 | 1 | | `color` | 使用顏色 | false | | `start_color` | 開始的顏色。您可使用十六進位值（`#b700ff`），rgba（`rgba(183, 0, 255, 1)`），hsla（`hsla(283, 100%, 50%, 1)`）或 [顏色關鍵字](http://www.w3.org/TR/css3-color/#svg-color)。此變量僅在 `color` 參數開啟時才有用。 | | `end_color` | 結束的顏色。您可使用十六進位值（`#b700ff`），rgba（`rgba(183, 0, 255, 1)`），hsla（`hsla(283, 100%, 50%, 1)`）或 [顏色關鍵字](http://www.w3.org/TR/css3-color/#svg-color)。此變量僅在 `color` 參數開啟時才有用。 | ## 其他 ### paginator 插入分頁鏈接。 ``` <%- paginator(options) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `base` | 基礎網址 | / | | `format` | 網址格式 | page/%d/ | | `total` | 分頁總數 | 1 | | `current` | 目前頁數 | 0 | | `prev_text` | 上一頁鏈接的文字。僅在 `prev_next` 設定開啟時才有用。 | Prev | | `next_text` | 下一頁鏈接的文字。僅在 `prev_next` 設定開啟時才有用。 | Next | | `space` | 空白文字 | &hellp; | | `prev_next` | 顯示上一頁和下一頁的鏈接 | true | | `end_size` | 顯示于兩側的頁數 | 1 | | `mid_size` | 顯示于中間的頁數 | 2 | | `show_all` | 顯示所有頁數。如果開啟此參數的話，`end_size` 和 `mid_size` 就沒用了。 | false | ### search_form 插入 Google 搜索框。 ``` <%- search_form(options) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `class` | 表單的 class name | search-form | | `text` | 搜索提示文字 | Search | | `button` | 顯示搜索按鈕。此參數可為布爾值（boolean）或字符串，當設定是字符串的時候，即為搜索按鈕的文字。 | false | ### number_format 格式化數字。 ``` <%- number_format(number, [options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `precision` | 數字精度。此選項可為 `false` 或非負整數。 | false | | `delimiter` | 千位數分隔符號 | , | | `separator` | 整數和小數之間的分隔符號 | . | **示例：** ``` <%- number_format(12345.671 // 12,345.68 <%- number_format(12345.674 // 12,345.6700 <%- number_format(12345.670 // 12,345 <%- number_format(12345.67'' // 12345.67 <%- number_format(12345.67'/' // 12,345/67 ``` ### open_graph 插入 open graph 資源。 ``` <%- open_graph([options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `title` | 頁面標題 (`og:title`) | `page.title` | | `type` | 頁面類型 (`og:type`) | blog | | `url` | 頁面網址 (`og:url`) | `url` | | `image` | 頁面圖片 (`og:image`) | 內容中的圖片 | | `site_name` | 網站名稱 (`og:site_name`) | `config.title` | | `description` | 頁面描述 (`og:desription`) | 內容摘要或前 200 字 | | `twitter_card` | Twitter 卡片類型 (`twitter:card`) | summary | | `twitter_id` | Twitter ID (`twitter:creator`) | | `twitter_site` | Twitter 網站 (`twitter:site`) | | `google_plus` | Google+ 個人資料鏈接 | | `fb_admins` | Facebook 管理者 ID | | `fb_app_id` | Facebook 應用程序 ID | ### toc 解析內容中的標題標簽 (h1~h6) 并插入目錄。 ``` <%- toc(str, [options]) %> ``` | 參數 | 描述 | 默認值 | | --- | --- | --- | | `class` | Class 名稱 | toc | | `list_number` | 顯示編號 | true | **示例：** ``` <%- toc(page.content) %> ```