中文标题【用户宏模板句法】
在你用户宏中使用参数
你可以为你的用户宏指定参数。这样的话，用户可以使用参数来决定 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
你模板中可用的对象
包含宏正文和参数，下面的 Confluence 对象在宏中可用：
变量 | 描述 | 类索引 |
|---|---|---|
| 宏的正文（如果宏有正文的话） | String |
| 传递到你宏中被命名的参数（"foo", "bar"） | String |
|
| |
|
| |
|
| |
| 当前的 |
宏也可以访问 Velocity 默认可以访问的对象，例如下面开发文档中描述的：as described in the developer documentation。
在编辑器中控制参数的显示
你可以决定宏参数在 Confluence 编辑器中如何进行显示的。
在默认的情况下，在宏占位符下尽可能显示能显示的所有参数：
你可以控制这里显示的参数数量，通过这种控制你可能尽量的为编辑者提供有效的信息。
例如，在 Confluence 的经过宏中有 2 个参数，title 和 icon。我们考虑到 title 是最有意义的参数，因此我们配置了经过宏显示了 title 参数的具体值。
让我们假设一个编辑用户添加了一个警告宏到编辑页面中。然后给了标题名称为 'The title of the warning'。在编辑器中的宏占位符将会显示下面的内容：
为一个用户宏配置宏占位符，你需要添加参数属性 @param 到整个模板中。
例如，如果我们的经过宏是一个用户宏，那么配置的 title 参数如下所示：
## @param title:type=string|option-showNameInPlaceholder=false|option-showValueInPlaceholder=true
属性 showNameInPlaceholder 指定了 title 下面显示的参数的名字。
属性 showValueInPlaceholder 指定了 title 参数的 value 值应该在下面显示。
如果在宏中没有上面的的 2 个参数没有包含有任何值，那么默认的配置将会在占位符中显示：完整的名字和值。
如果一个或多个参数属性被设置了，那么是所有不包含有属性的参数将会默认显示为 false（例如这里将不会显示）。