包含宏正文和参数，下面的 Confluence 对象在宏中可用： $body 宏的正文（如果宏有正文的话） String $paramfoo, $parambar, ...$param<name> 传递到你宏中被命名的参数（"foo", "bar"） String $config BootstrapManager 对象被用来获取 Confluence 属性。 BootstrapManager $renderContext PageContext 对象，针对其他事情会比较有用，请查看 $renderContext.outputType PageContext $space Space 对象，包含有相对的页面，博客页面等对象内容。 Space $content 当前的 ContentEntity 对象是当前宏包含的（如果有的话）。 ContentEntityObject 宏也可以访问 Velocity 默认可以访问的对象，例如下面开发文档中描述的：as described in the developer documentation。   https://www.cwiki.us/display/CONFLUENCEWIKI/User+Macro+Template+Syntax

你可以为你的用户宏指定参数。这样的话，用户可以使用参数来决定 Confluence 页面的显示情况。 如何在 Confluence 页面中使用你的宏参数 当添加一个宏到 Confluence 页面中的时候，宏浏览器将会为每一个选择的宏显示输入字段，这个输入字段就是你需要指定的参数。 定义参数 在模板中的参数定义为： @param 参数的名称 一系列属性（可行）。 格式： ## @param MYNAME:title=MY TITLE|type=MY TYPE|desc=MY DESCRIPTION|required=true|multiple=true|default=MY DEFAULT VALUE 其他说明： 在模板中参数的排序决定了参数在宏浏览器中显示的顺序。 我们推荐你在模板的顶部定义你的所有参数。 有可能有一些附加的属性，这个基于你的参数类型。 下面的表格说明了描述了每一个属性的详细信息。 (an unnamed, first attribute) 参数的独一无二的名称。这个参数名称在所有参数属性列表中的第一位。这个名字属性本身是没有名字的。请单击 name 查看详细信息。 必须（Required） title 在宏浏览器中显示的参数标题。如果你没有指定一个标题的话，Confluence 将会使用参数名称 推荐（Recommended） type 参数的类型字段。请单击  type 获得允许的类型 推荐（Recommended） desc 在宏浏览器中显示的参数描述 可选（Optional） required 指定用户是否必须为这个参数输入值（默认：否） 可选（Optional） multiple 指定参数是否接受多变量值（默认：否） 可选（Optional） default 参数的默认变量值 可选（Optional） 参数名称（Parameter name） 参数的独一无二的名称。这个参数名称在所有参数属性列表中的第一位。这个名字属性本身是没有名字的。 示例：下面的代码定义了 2 个参数，名字为 'foo' 和 'bar'： ## @param foo ## @param bar 参数类型（Parameter type） 这个字段定义了参数的类型。如果你没有指定一个类型，那么默认的类型为  string。 boolean 显示选择框（checkbox ）允许用户进行选择和取消选择。这个将会向宏传递 'true' 或 'false'。请注意宏接受到的是字符串。 enum 通常列出可以供选择的列表。你可以指定显示的一系列值，然后将会在宏浏览器中通过下拉选择进行选择。例如，你指定了下面的枚举类型变量： ## @param colour:title=Colour|type=enum|enumValues=Grey,Red,Yellow,Green 注意 i18n：Confluence 并不支持国际化的枚举变量类型。用户可以看到的变量就是实际传递过去的变量，同时变量将首字母大写。在这里，用户将会看到 'Grey', 'Red', 等。 string 文本字符类型。这是默认的类型。例如一个需要的字段： ## @param status:title=Status|type=string|required=true|desc=Status to display confluence-content 为用户提供一个控制器允许用户在页面和博客页面中进行查找。例如： ## @param page:title=Page|type=confluence-content|required=true|desc=Select a page do use username 查找用户 ## @param user:title=Username|type=username|desc=Select username to display spacekey 提供空间选择的列表。请输入空间的 Key 到用户宏。例如： ## @param space:title=Space|type=spacekey date Confluence 能够接受这个参数类型，但是这个参数将会按照字符串进行处理。例如： ## @param fromDate:title=From Date|type=date|desc=Date to start from. Format: dd/mm/YYYY 日期类型说明：用户可以输入任何格式的日期类型，你应该在你用户宏中校验日期格式。 int Confluence 能够接受这个参数类型，但是这个参数将会按照字符串进行处理。例如下面一个默认的变量： ## @param numPosts:title=Number of Posts|type=int|default=15|desc=Number of posts to display percentage Confluence 能够接受这个参数类型，但是这个参数将会按照字符串进行处理。例如： ## @param pcent:title=Percentage|type=percentage|desc=Number of posts to display 在你的宏代码中使用参数 参数在你的模板中可以使用 $paramfoo, $parambar 进行调用  "foo" 和 "bar" 参数名。 通常情况下，一个参数像 $paramfoo 如果丢失，或者没有定义的话，那么页面将会输出显示为 '$paramfoo' 。如果你不希望输出成这样，而是希望完全不输出，你可以使用感叹号标记，如下所示 $!paramfoo 使用无参数 如果你的宏不接受参数，那么你应该在你的模板中使用 @noparams 。 如果用户宏包含无参数，同时也没有指定 @noparams，那么宏浏览器将会显示一个无格式的文本输入框，允许用户输入没有定义的参数。这个可能会与宏不接受参数相混淆。 例如：添加下面的行到你的模板中： ## @noparams   https://www.cwiki.us/display/CONFLUENCEWIKI/User+Macro+Template+Syntax

请查看 Writing User Macros 页面获得有关如何写用户宏的介绍。 这个页面介绍你可以在用户宏中可以使用的的代码信息。 访问你的宏正文（body） 在你用户宏模板中的 $body 对象可以访问访问到传递到你宏正文中的内容。 当你的宏有指定的正文的时候，$body 对象是可用的（换句话说，如果你没有选择 No macro body 的话）。 示例：让我们假定你的宏的名称为  helloworld。 在下面的模板中输入下面的内容： Hello World: $body 当编辑 Confluence 页面的一个用户，在宏浏览器中选择你的这个用户宏，然后在宏的正文中输入了下面的内容，下面显示的是编辑页面的样子： From Matthew WIKI 页面最终将会显示成下面的样子： Hello World: From Matthew https://www.cwiki.us/display/CONFLUENCEWIKI/User+Macro+Template+Syntax

下面的用演示了如果还写一个用户宏，并在这个宏中创建一个格式化的面板，并且指定颜色。将会创建下面的面板： (Title) 注意：这个面板的标题为空，如果你没有给这个面板标题参数的话。 Macro name formpanel Visibility Visible to all users in the Macro Browser Macro Title Formatted Panel Description Creates a panel preformatted with specific colors Categories Formatting Icon URL 可以设置为空 Documentation URL 可以设置为空 Macro body processing Escaped Template 在下面的模板字段中输入代码。请查看下面获得更多有关细节的解释。 ## @param Title:title=Title|type=string|desc=Title <ac:structured-macro ac:name="panel">         <ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>         <ac:parameter ac:name="borderStyle">solid</ac:parameter>         <ac:parameter ac:name="borderColor">#6699CC</ac:parameter>         <ac:parameter ac:name="borderWidth">2</ac:parameter>         <ac:parameter ac:name="titleColor">#000000</ac:parameter>     <ac:parameter ac:name="title">$!paramTitle</ac:parameter>     <ac:rich-text-body>$body</ac:rich-text-body> </ac:structured-macro> 有关宏模板代码中的细节解释 下面为使用宏模板代码的的一些细节说明。 ## @param Title:title=Title|type=string|desc=Title @param 为你的宏参数定义了元数据。 @param Title 这个参数被称为 "Title"。 title=Title 定义了参数标题，这个标题将会在宏浏览器中显示为 "Title"。 type=string 为参数文本字段定义了字段类型。 desc=Title 为宏浏览器定义了描述的参数。 <ac:structured-macro ac:name="panel"> 这个被称为 Confluence Panel Macro 宏。 最容易找到 Confluence 宏名称的的方法是通过查看在页面中包含有宏的存储格式。你将会需要 Confluence 管理员权限来查看存储的格式。 <ac:parameter ac:name="titleBGColor">#ccc</ac:parameter> <ac:parameter ac:name="borderStyle">solid</ac:parameter> <ac:parameter ac:name="borderColor">#6699CC</ac:parameter> <ac:parameter ac:name="borderWidth">2</ac:parameter> <ac:parameter ac:name="titleColor">#000000</ac:parameter> 为这个宏设置参数：背景颜色，边界样式，边界颜色，边界宽度和标题颜色。 希望在 Confluence 宏发现擦书的名称，请查看上面描述的中存储的格式。 <ac:parameter ac:name="title">$!paramTitle</ac:parameter> 输入存储在 'Title' 参数中变量，这个部分将会显示为宏的标题。 ! 标记告诉宏这部分显示为空，当 "Title" 参数中没有数据的话。 <ac:rich-text-body>$body</ac:rich-text-body> 用户可以输入保存在宏内容中的数据。这行将会启用宏方法存储在内容中的数据。 </ac:structured-macro> 这个标记标记宏的结束。   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

这个示例定义了如何向你宏中传递参数。我们将会创建一个字体样式宏，在这个宏中有 2 个参数，允许用户在这 2 个参数中指定宏中包含的字体的颜色大小。 Macro name stylish Visibility Visible to all users in the Macro Browser Macro Title Stylish Description Applies colour and size to text. Categories Confluence Content Icon URL 可以设置为空 Documentation URL 可以设置为空 Macro body processing Rendered Template 在模板字段中输入下面的代码。如果你的宏要求一个或者多个参数的话，你可以使用变量 $param0 到 $param9 来调用它们。 ## @param 0:title=colour|type=string ## @param 1:title=size|type=string <span style="color: $param0; font-size: $param1">$body</span> 可选的，你也可以在你的宏中明确定义参数名。这些参数将会在$param<x> 中调用，其中 <x> 是你参数的名字。 ## @param Colour:title=colour|type=string ## @param Size:title=size|type=string <span style="color: $paramColour; font-size: $paramSize">$body</span>   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

这个示例演示了如何创建一个用户宏，这个宏包括了在查看页面中显示的内容，但是不被打印。 Macro name noprint Visibility Visible to all users in the Macro Browser Macro Title No Print Description Hides text from printed output. Categories Confluence Content Icon URL You can leave this field blank Documentation URL You can leave this field blank Macro body processing Rendered Template Enter the code below in the template field. ## @noparams <div class="noprint">$body</div> Using the 'NoPrint' Macro on a page Now you can add the macro to your Confluence page using the Macro Browser. Text entered into the body of the macro placeholder will not be printed, but will appear when the page is viewed online. Making the PDF export recognize the NoPrint macro See Writing User Macros.   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

下面示例显示了如何创建一个用户宏，在这个用户宏中显示文本 'Hello World!' 和任何用户在宏内容中输入的内容。 Macro name helloworld Visibility Visible to all users in the Macro Browser Macro Title Hello World Description Displays "Hello World" and the macro body. Categories Confluence Content Icon URL 可以设置为空。 Documentation URL 可以设置为空。 Macro body processing Rendered Template 在模板字段中输入下面的内容 - 这个示例将会直接在页面中进行输出： ## @noparams Hello World! $body 如果你希望文本显示在相对的 AUI message class 的话，如下所示： ## @noparams <div class="aui-message closeable"> Hello World! $body </div> 在页面中使用 'Hello World' 宏 Now you can add the macro to your Confluence page using the Macro Browser, or by typing {hello in the editor and selecting the macro from the list of suggestions. 页面显示的结果是   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

这个页面为你在创建用户宏的最佳实践中包含了一些小技巧和建议。 为你的宏添加一个简短的描述 我们鼓励你为你的宏在 模板（Template ）添加一个备注的描述，可以参考下面的显示的内容： ## Macro title: My macro name ## Macro has a body: Y or N ## Body processing: Selected body processing option ## Output: Selected output option ## ## Developed by: My Name ## Date created: dd/mm/yyyy ## Confluence version: Version it was developed for ## Installed by: My Name ## Short description of what the macro does 在宏浏览器中展示你的参数 宏浏览器是为你用户使用配置你的宏的最简单的方式。你可以指定你的宏的分类，图标的连接定义在宏浏览器中为用户展示的信息的参数等。 为宏参数提供默认值 一般来说你不能保证用户能够完整的提供用户的参数，一个让宏进行校验是否收到了正确的参数的话，你可以在你的宏中指定参数并在后面使用。 请参考下面的示例，在这个宏中有 3 个参数，当用户不提供参数的时候，这些参数的默认值将会被使用。 #set($spacekey= $paramspacekey) #set($numthreads= $paramnumthreads) #set($numchars= $paramnumchars) ## Check for valid space key, otherwise use current #if (!$spacekey)   #set ($spacekey=$space.key) #end ## Check for valid number of threads, otherwise use default of 5 #if (!$numthreads)   #set ($numthreads=5) #end ## Check for valid excerpt size, otherwise use default of 35 #if (!$numchars)   #set ($numchars=35) #end 考虑安全提示 我们建议你为你定义的宏进行一些权限方面的测试。例如，限制页面和空间权限来避免没有权限的用户可能的不经意间的显示。请查看 Writing User Macros 页面中的内容。   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

编辑一个用户宏 希望对一个用户宏进行编辑： 进入  > 基本配置（General Configuration） > 用户宏（User Macros） 在相关的宏的边上，单击 编辑（Edit） 更新宏的详细信息 单击 保存（Save） 删除一个用户宏 希望删除一个用户宏： 进入  > 基本配置（General Configuration） > 用户宏（User Macros） 当前系统中定义的用户宏将会完全显示出来 在相关的用户宏上，单击 删除（Delete） 在删除一个用户宏之前，你应该查找使用了这个用户宏的所有页面和博客页面。如果你删除的用户宏还在页面中被引用了的话，你的用户将会在页面中看到 'unknown macro' 错误信息。   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

如果你想创建自定义的宏的话，用户宏能够帮你完成这个任务。这个可以在你系统中应用特定的操作，比如说应用自定义格式等。 用户用是在 Confluence 创建和和管理的，你需要有一定的编码基础才可以。 你需要具有系统管理员权限来创建和应用用户自定义宏。 希望创建一个新的用户宏： 进入  > 基本配置（General Configuration） > 用户宏（User Macros） 选择 创建一个用户宏（Create a User Macro） 输入宏的一些详细信息（请查看下面列表） 单击 添加（Add） 宏名称（Macro name） 宏的名字，将会出现在代码中。 可见（Visibility） 这个选项控制谁可以在宏浏览器中查看这个宏或者自动完成功能。选项有： 所有用户可见（Visible to all users） 仅系统管理员可见（Visible only to system administrators） 请注意，如果你选择仅系统管理员可见的话，用户任然可以看到用在页面中输出的结果，宏的占位符也还是在编辑页面中出现的，这个仅仅在宏浏览器和自动完成的时候隐藏了。 所有宏的信息都是可以找到的，包括宏的标题，描述，参数名称和其他元数据。尽管宏只能被系统管理员查看到，也请不要在用户宏中定义任何敏感信和保密信息。 宏标题（Macro Title） 在宏浏览器和自动完成功能中出现的宏标题。 描述（Description） 这个描述信息将会出现在宏浏览器中。宏浏览器的查找将会对查找字段在宏标题和描述中的文字进行匹配。 分类（Categories） 为你的宏在宏浏览器中选择一个或多个分类。 图标 URL（Icon URL） 如果你希望宏浏览器为你的宏显示图标的话，输入绝对地址（例如 http://mysite.com/mypath/status.png）或相对于 Confluence base URL 的相对地址（例如：/images/icons/macrobrowser/status.png） 。 文档 URL（Documentation URL） 如果你的宏有文档的话，请在这里输入文档的 URL。 宏内容处理（Macro Body Processing） 指定 Confluence 应该如何处理你的宏的内容。 宏的内容中包含了在 Confluence 页面中如何处理的信息。如果你的宏有一个内容，所有宏的内容将会在 $body 变量字段中可用。 处理宏内容字段选项包括有： No macro body 选择这个选项，如果你的宏没有任何内容的话。 Escaped Confluence 将会添加在 HTML 标记中添加转义字符。如果你希望显示 HTML 标记在生产的页面中的时候，你可以使用转义字符。例如：如果内容为 <b>Hello World</b> 那么将会在生成页面中显示   <b>Hello World</b>。 Unrendered 内容中的 HTML 将会在模板输出之前进行处理。请确定模板中的 HTML 是非再生的。 Rendered Confluence 将会对 HTML 宏内容的部分进行让浏览器进行解析。例如宏内容为 <b>Hello World</b> 这个内容将会显示 Hello World。 模板（Template ） 这里是你写的代码去确定宏应该是什么样子的。 在宏模板中使用 HTML 和 Confluence 自定义 XML 元素。 你可以使用  Velocity 模板语言。这里是有关 Velocity project 项目的相关信息。 如果你的宏有 body 内容，你的宏可以将 body 的文本引用为 '$body'。 每个参数变量必须有一个与之对应的元数据定义。在你的宏参数中使用 @param 来定义元数据。 当使用参数传递信息，请参考 $paramXXX 在 'XXX' 的参数，是你定义 @param 元数据后来引用的参数。 如果你的宏不能接受参数，请使用 @noparams 。 请查看 Writing User Macros 要么获得更多的信息和示例。 希望使用插件完成编辑？ 如果你希望将你的自定义宏按照插件进行分发的话，请参考  User Macro plugin module 页面中的内容。如果你希望使用更加复杂，更加程序化的宏的话，你需要写成 Macro plugin 宏。 https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros