巨集¶

• 目錄
• 巨集
  • 在格式化文字中呼叫巨集
  • 新增自訂巨集

Redmine 包含一個巨集系統，可讓您新增自訂函數，以便在格式化文字中插入動態內容。

在格式化文字中呼叫巨集¶

使用雙重大括號呼叫巨集。如果有任何參數，則必須將其括在括號中。巨集名稱或參數後的新行會啟動要傳遞至巨集的文字區塊（使用某些文字呼叫不接受文字區塊的巨集將會失敗）。

範例

No arguments:
{{my_macro}}

With arguments:
{{my_macro(arg1, arg2)}}

With a block of text:
{{my_macro
multiple lines
of text
}}

With arguments and a block of text
{{my_macro(arg1, arg2)
multiple lines
of text
}}

如果給定了文字區塊，則結束標籤 }} 必須位於新行的開頭。

新增自訂巨集¶

可以使用以下語法從 Redmine 外掛新增自訂巨集

Redmine::WikiFormatting::Macros.macro(name, options={}, &block)

選項

• :desc - 巨集的描述
• :parse_args => false - 停用參數解析（整個參數字串會傳遞至巨集）

巨集區塊接受 2 或 3 個參數

• obj - 正在渲染的物件（例如：議題、Wiki 內容...）
• args - 巨集參數
• text - 提供給巨集的文字區塊（僅當巨集接受文字區塊時才應存在）。 text 是 String 或 nil（如果在沒有文字區塊的情況下呼叫巨集）。

每次在格式化文字中呼叫巨集時都會呼叫該區塊，並將其回傳值插入最終輸出中。此回傳值必須是已轉義 HTML 的字串。

範例

根據預設，當呼叫巨集時，以逗號分隔的參數清單會被分割並以陣列形式傳遞至巨集區塊。如果未提供參數，則會使用空陣列呼叫巨集

macro :my_macro, :desc => 'This is a custom macro' do |obj, args|
  # args is an array
  # and this macro does not accept a block of text
end

您可以使用 :parse_args => false 選項停用參數分割。在此情況下，完整的參數字串會傳遞至巨集

macro :my_macro, :parse_args => false do |obj, args|
  # args is a string
end

巨集可以選擇接受文字區塊作為第三個參數

macro :my_macro do |obj, args, text|
  # this macro accepts a block of text
  # text is a String that represent the whole text passed to the macro
end

作為編寫您自己的巨集的起點，您可以查看內建的巨集定義：source:/tags/2.1.0/lib/redmine/wiki_formatting/macros.rb#L162