Confluence 6 在你用户宏中使用参数

你可以为你的用户宏指定参数。这样的话，用户可以使用参数来决定 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