宏¶

• 目录
• 宏
  • 在格式化文本中调用宏
  • 添加自定义宏

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

作为编写您自己的宏的起点，您可以查看内置宏定义： 源代码：/tags/2.1.0/lib/redmine/wiki_formatting/macros.rb#L162