Skip to content

模板语法#

XenForo 2 的模板语法是开发者和论坛管理员的强大工具，使您能够完全控制 XenForo 页面的布局。

最佳实践#

  • 按照惯例，XenForo 标签应为 小写。
  • 所有 XenForo 标签都带有 xf: 命名空间前缀。

实用信息#

在模板中添加注释#

如果您想注释掉一些模板代码（或一条激励性消息），并且不希望这些内容出现在最终页面源代码中，可以使用 xf:comment 标签。

HTML
<xf:comment>
如果你不再以喜欢和不喜欢的方式看待世界，
而是看到事物的本质，
你会在生活中找到更多的平静。
</xf:comment>

在模板中包含另一个模板#

xf:include 标签允许您在当前模板中包含另一个模板。

HTML
<xf:include template="my_template" />

只需将 template 属性设置为您要包含的模板名称即可。

模板宏#

模板宏是 XenForo 模板语法中非常强大的部分。

通常，您可以在编程语言中使用函数或子例程的地方使用宏。 对于非程序员，我总结为：要么 在多个不同文件中多次生成相同内容的地方使用宏，要么 在不同情况下生成不同内容的地方使用宏（如果您查看定义宏的指南，可能会更清楚）。

警告

出于可读性考虑，您不应将宏标签用作变量。相反，您应使用 Set 标签，并将变量视为任何模板变量。

定义宏#

HTML
<xf:macro
    name="my_macro_name">

    <!-- 您的宏内容 -->

</xf:macro>

最简单的宏可以通过 name 属性和您希望在宏标签内重复的内容来定义。

注意

当您在多个文件中使用宏时，最佳做法是将宏放在其自己的模板中。

宏参数#

HTML
<xf:macro
    name="my_macro_name"
    arg-message="我的惊人宏消息！">

    <h1>消息</h1>
    <p>{$message}</p>

</xf:macro>

在此示例中，定义了一个带有 arg-message 默认值（我的惊人宏消息！）的宏。 如果调用宏时提供了 message 参数，此值将被覆盖。

有时需要将参数标记为必需。这可以通过在宏定义中将参数值设置为 ! 来实现。

包含和使用宏#

HTML
<xf:macro template="my_macro_template" name="my_macro_name" />

最简单的包含宏的方式是设置 name 属性并保持标签为空。

注意

使用宏标签时，应使用自闭合形式的标签，以便更容易区分宏的定义和使用。

宏参数#

您还可以向宏提供参数：

HTML
<xf:macro template="my_macro_template" name="my_macro_name" arg-argName="argValue" />

其中 argName 是宏参数的名称。

注意

宏参数名称应使用 lowerCamelCase。

模板控制结构#

XenForo 2 的模板语法支持某些控制结构，以使某些任务更容易实现。

If 标签#

if 模板标签可用于有条件地显示某些 HTML 或模板的一部分。

HTML
<!-- 仅当用户登录时显示内容... -->
<xf:if is="$xf.visitor.user_id">
    <!-- 做一些事情... -->
</xf:if>

if 标签接受以下属性：

  • is - 满足条件时显示标签内容的条件。

条件#

is 属性支持一些逻辑运算符：

  • OR - 用于链接替代条件。（替代：||）
  • AND - 用于链接附加条件。（替代：&&）
  • ! - 在条件前放置以反转它。（称为：'非'）
  • XOR - 如果两个条件中只有一个为真，则返回真。（称为：异或）

Else/Else-If 标签#

else 和 else-if 标签与 if 标签结合使用，以有条件地显示 HTML，方式如其名称所示。

else 的示例用法：

HTML
<xf:if is="$xf.visitor.is_admin">
    <!-- 此处内容仅对管理员显示... -->
<xf:else />
    <!-- 此处内容对非管理员的任何人显示！ -->
</xf:if>

else-if 的示例用法：

HTML
<xf:if is="$xf.visitor.is_admin">

    <!-- 此处内容仅对管理员显示... -->

<xf:elseif is="$xf.visitor.is_moderator" />
    <!--
        此处内容仅对版主显示
        （不包括也是管理员的用户）。
    -->
<xf:else />
    <!--
        此处内容对非管理员或版主的任何人显示。
    -->
</xf:if>

如您所见，一旦满足条件，if 语句的其余部分将被忽略。（因此，在此示例中，如果用户是管理员，则顶部的 xf:if 部分将运行，但 if 语句的其余部分将被忽略。）

For-each 标签#

for-each 标签允许您遍历数组中的项目，为每个项目打印一块 HTML。

HTML
<xf:set var="$names" value="{{ ['Patrick', 'Theresa', 'Kimball', 'Wayne', 'Grace'] }}" />

<xf:foreach loop="$names" key="$key" value="$name" i="$i">
    <p>你好，{$name}。这是第 {$i} 个名字。此元素的数组键：{$key}</p>
</xf:foreach>

for-each 标签接受以下属性：

  • loop - 要遍历的数组。
  • key - 在循环中使用的变量名，用于获取当前元素的数组键。可以是整数（普通数组）或字符串（关联数组）。
  • value - 在循环中使用的变量名，包含当前数组项。
  • i - 在循环中使用的变量名，用于当前索引。

示例输出#

你好，Patrick。这是第 1 个名字。此元素的数组键：0

你好，Theresa。这是第 2 个名字。此元素的数组键：1

你好，Kimball。这是第 3 个名字。此元素的数组键：2

你好，Wayne。这是第 4 个名字。此元素的数组键：3

你好，Grace。这是第 5 个名字。此元素的数组键：4

模板标签#

Avatar 标签#

在页面中插入用户的头像。

HTML
<xf:avatar user="{$xf.visitor}" size="o" canonical="true" />

avatar 标签接受以下属性：

  • user - 要生成头像的 XenForo 用户对象。
  • size - 要生成的图像大小。（参见图像大小）
  • canonical - 是否使用完整的 SEO 友好 URL。此值仅对 custom 头像有效。
  • notooltip - 是否禁用悬停在头像上时显示的工具提示。
  • forcetype - 可用于通过将值设置为 gravatar 或 custom 来强制获取 Gravatar 或自定义头像。
  • defaultname - 如果 user 属性包含无效用户，则使用的用户名。

图像大小#

如果提供了无效大小的头像，代码将回退到大小 's'。

  • o - 384px
  • h - 384px
  • l - 192px
  • m - 96px
  • s - 48px

修改页面面包屑。

HTML
<xf:breadcrumb href="{{ link('my_page') }}">{{ phrase('my_page_name') }}</xf:breadcrumb>

breadcrumb 标签接受以下属性：

  • href - 为面包屑中的最后一个元素设置的链接。

标签的值可用于设置面包屑中最后一个元素的名称。

替代用法#

HTML
<xf:breadcrumb source="$category.getBreadcrumbs(false)" />

您还可以通过调用 source 属性中的函数以编程方式定义自己的面包屑。

source 参数本质上接受一个具有 href 和 value 属性的对象数组（多维数组），其中每个对象都是一个面包屑元素。

注意

如果您想更改根面包屑，可以在“基本论坛信息”选项部分中更改“根面包屑”选项。

Button 标签#

添加一个带有适当类和可选图标的按钮元素。

HTML
<xf:button icon="save"></xf:button>

button 标签接受以下属性：

  • icon - 应用于按钮的图标类。（参见按钮图标）

按钮图标#

默认情况下，XenForo 按钮支持以下图标（使用 CSS 创建）：

  • add
  • confirm
  • write
  • import
  • export
  • download
  • disable
  • edit
  • save
  • reply
  • quote
  • purchase
  • payment
  • convert
  • search
  • sort
  • upload
  • attach
  • login
  • rate
  • config
  • refresh
  • translate
  • vote
  • result
  • history
  • cancel
  • preview
  • conversation
  • bolt
  • list
  • prev
  • next
  • markRead
  • notificationsOn
  • notificationsOff
  • merge
  • move
  • copy
  • approve
  • unapprove
  • delete
  • undelete
  • stick
  • unstick
  • lock
  • unlock

回调方法#

要使方法被视为回调方法，必须适当命名，否则将抛出错误 'callback_method_x_does_not_appear_to_indicate_read_only'。要被视为只读，方法名称必须以以下前缀之一开头：

  • are
  • can
  • count
  • data
  • display
  • does
  • exists
  • fetch
  • filter
  • find
  • get
  • has
  • is
  • pluck
  • print
  • render
  • return
  • show
  • total
  • validate
  • verify
  • view

CSS 标签#

包含一个 CSS 或 LESS 模板文件。

HTML
<xf:css src="mycss_file.css"  />

CSS 标签接受以下属性：

  • src - 要包含的 CSS 或 LESS 模板文件。

替代用法#

HTML
<xf:css>
html, body {
 font-family: "Roboto", sans-serif;
}
</xf:css>

如果 CSS 标签不为空，标签内的任何内容都将转换为内联 CSS。

进一步说明#

对于 [CSS]，忘记将它们作为文件调用。将它们复制并粘贴到新模板中。

Chris D, XenForo 开发者 来源: https://xenforo.com/community/threads/including-external-library-js-and-css.136153/post-1185631

JS 标签#

包含一个 JavaScript 文件。

HTML
<xf:js src="myaddon/vendor/scripts/myjs_file.js"  />

JS 标签接受以下属性：

  • src - 要在模板中包含的 JS 文件。
  • prod - 仅在生产模式下包含的 JS 文件。
  • dev - 仅在开发模式下包含的 JS 文件。
  • min - 是否包含文件的压缩版本。（将 .js 替换为 .min.js） - 仅在生产模式下有效。
  • addon - 是否应使用开发 JS URL。 - 仅在开发模式下有效。

警告

src 标签不能与 prod 或 dev 标签一起使用。

替代用法#

HTML
<xf:js>
alert("真相伤人，我知道。这实际上是基于生物学的。");
</xf:js>

如果 JS 标签不为空，标签内的任何内容都将转换为内联 JS。

进一步说明#

JavaScript 文件相对于 /js 目录提供服务。虽然不推荐，但您也可以使用此标签包含外部资源。

此标签的一个很好的示例在 editor 模板中。

Set 标签#

Set 标签允许您创建对另一个变量的引用或创建一个新变量。您应该在编程语言中使用变量的任何地方使用 Set 标签。

HTML
<xf:set var="$visitor" value="{$xf.visitor}" />

警告

不要将 Set 标签用于您希望在多个模板中使用的一组元素，您应改用 Macro 标签。

警告

变量名称（var 属性）必须以 $ 开头。

Set 标签接受以下属性：

  • var - 您希望定义的变量名称（本质上是别名）。
  • value - 要引用的变量或变量值。

替代用法#

HTML
<xf:set var="$myVariableName">
我的变量值！
这可以是一个回调，或者只是一组短语。
</xf:set>

当未提供 value 属性且标签不为空时，变量值将设置为标签的内容。

警告

当您以这种形式使用 Set 标签时，值将被转义，结果值将是一个字符串。 value 属性虽然不支持 HTML 或类似 HTML 的标签，但没有此限制。

Likes 标签#

显示帖子上的点赞数以及一些点赞帖子的用户。

HTML
<xf:likes content="{$post}" url="" />

Likes 标签接受以下属性：

  • content - 要显示“点赞”文本的 XF\Entity\Post 或 XF\Entity\ProfilePost 实体。
  • url - 点击“点赞”文本时显示的 URL。

格式#

你、tlisbon、kcho 和 2 其他人

格式为 [👍 abc 和 x 其他人]（其中 👍 '竖起大拇指' 表情符号代表“点赞”图标，abc 代表最后三个点赞帖子的用户名。）

参见 分段标签。

SideNav 标签#

参见 分段标签。

Title 标签#

设置页面的标题，包括页面上的 h1 标签和浏览器标签中的标题。

HTML
<xf:title>{{ phrase('my_page_title') }}</xf:title>

进一步说明#

虽然标题当然可以硬编码，但强烈建议您使用短语，既为了国际化，也为了增加站点管理员的可定制性。

Widget 标签#

在页面中包含一个小部件，或将小部件添加到小部件位置。

HTML
<xf:widget key="widget_name" />

Widget 标签接受以下属性：

  • key - 小部件键，如小部件设置中所定义。
  • position - 如果设置，将更改小部件呈现的位置。
  • class - 不要与 HTML 类混淆，这是包含小部件定义的 PHP 类。
  • title - 当使用 class 属性时，您可以使用 title 属性设置小部件标题。
  • 当使用 class 属性时，您还可以提供小部件特定的选项作为属性。

警告

class 标签不能与 key 标签一起使用。

UserActivity 标签#

显示用户的状态，包括他们的最后操作以及该操作发生的时间。

HTML
<xf:useractivity user="{$xf.visitor}" />

UserActivity 标签接受以下属性：

  • user - 要显示状态的用户。

格式#

正在查看页面 最新案例文件 · 4 分钟前

格式为 [活动名称] · [时间]

UserBanners 标签#

以水平列表显示用户的横幅。

HTML
<xf:userbanners user="{$xf.visitor}" />

UserBanners 标签接受以下属性：

  • user - 要显示用户横幅的用户。

示例#

UserBanners 标签的示例结果。

UserBanners 标签的示例结果。

UserBlurb 标签#

显示用户个人资料的一行摘要。

HTML
<xf:userblurb user="${xf.visitor}" />

UserBlurb 标签接受以下属性：

  • user - 要显示摘要的 XenForo 用户对象。

格式#

FBI 顾问 · 43 · 来自美国

格式为 [角色 / 自定义标题] · 年龄 · 位置

Username 标签#

显示用户的用户名，可选地带有工具提示。

HTML
<xf:username user="{$xf.visitor.username}" notooltip="true" />

Username 标签接受以下属性：

  • user - 要显示名称的 XenForo 用户对象。
  • notooltip - 是否禁用工具提示。
  • href - 点击用户名时导航到的链接。

警告

如果设置了 href，工具提示将不会显示，因为它不起作用，并且可能会误导用户。

UserTitle 标签#

显示用户的标题。

HTML
<xf:usertitle user="{$xf.visitor}" />

UserTitle 标签接受以下属性：

  • user - 要显示用户标题的 XenForo 用户对象。

分段标签#

分段标签都调用函数 modifySectionedHtml。 它们更改的 HTML 元素只是标签名称。因此，sidebar 标签将修改侧边栏 HTML，等等。

示例#

HTML
<xf:sidebar>
 <h1>我的神奇侧边栏！</h1>
</xf:sidebar>

常见属性#

  • mode - 修改模式。（参见修改模式）

修改模式#

默认情况下，修改模式为 replace。（即如果未指定属性。）

  • prepend - 将标签内容放置在元素 HTML 的开头。
  • append - 将标签内容放置在元素 HTML 的末尾。
  • replace - 用标签内容替换元素的 HTML。