模板

当您在应用程序中的 HTML 文件中编写模板为 <template name="foo"> ... </template> 时，Meteor 会生成一个名为 Template.foo 的“模板对象”。请注意，模板名称不能包含连字符和其他特殊字符。

同一模板可能在页面上多次出现，这些出现称为模板实例。模板实例具有创建、放入文档以及稍后从文档中取出并销毁的生命周期。Meteor 为您管理这些阶段，包括确定何时应删除或替换模板实例，以及何时应清理模板实例。您可以将数据与模板实例关联，并且可以在该实例位于文档中时访问其 DOM 节点。

阅读有关模板以及如何在指南中的 Spacebars 和 Blaze 文章中使用模板的更多信息。

模板声明

为该模板的实例声明事件处理程序。多次调用会在现有的事件处理程序的基础上添加新的事件处理程序。

有关事件映射格式以及 Meteor 中的事件处理机制的详细说明，请参阅 事件映射。

每个模板都有一个局部助手字典，这些助手对它可用，此调用会指定要添加到模板字典的助手。

示例

1
2
3
4
5

Template.myTemplate.helpers({
  foo() {
    return Session.get("foo");
  }
});

现在，您可以使用 {{foo}} 在使用 <template name="myTemplate"> 定义的模板中调用此助手。

助手可以接受位置参数和关键字参数

1
2
3
4
5
6

Template.myTemplate.helpers({
  displayName(firstName, lastName, keyword) {
    var prefix = keyword.hash.title ? keyword.hash.title + " " : "";
    return prefix + firstName + " " + lastName;
  }
});

然后，您可以从模板中像这样调用此助手

1

{{displayName "John" "Doe" title="President"}}

您可以在 Spacebars 中了解更多有关助手参数的信息。

在幕后，每个助手都会启动一个新的 Tracker.autorun。当其响应式依赖项发生更改时，助手将重新运行。助手依赖于其数据上下文、传递的参数以及执行期间访问的其他响应式数据源。

若要创建可在任何模板中使用的助手，请使用 Template.registerHelper。

使用此方法添加的回调将在 Template.myTemplate 的实例首次渲染为 DOM 节点并放入文档中时调用一次。

在回调主体中，this 是一个 模板实例 对象，该对象对于此模板的出现是唯一的，并且在重新渲染时保持一致。使用 onCreated 和 onDestroyed 回调对对象执行初始化或清理操作。

由于您的模板已渲染，因此可以使用 this.findAll 等函数，这些函数会查看其 DOM 节点。

这可以是应用您想要的任何 DOM 操作的理想位置，前提是模板首次渲染后。

1
2
3
4
5
6
7

<template name="myPictures">
  <div class="container">
    {{#each pictures}}
      <img class="item" src="/{{.}}"/>
    {{/each}}
  </div>
</template>

1
2
3
4
5
6
7

Template.myPictures.onRendered(function () {
  // Use the Packery jQuery plugin
  this.$('.container').packery({
    itemSelector: '.item',
    gutter: 10
  });
});

使用此方法添加的回调会在您的模板逻辑首次评估之前调用。在回调内部，this 是新的 模板实例 对象。您在此对象上设置的属性将从使用 onRendered 和 onDestroyed 方法添加的回调以及从事件处理程序中可见。

这些回调会触发一次，并且是第一个触发的回调组。处理 created 事件是使用 Template.instance() 从模板助手读取的模板实例上设置值的一种实用方法。

1
2
3
4
5
6
7

Template.myPictures.onCreated(function () {
  // set up local reactive variables
  this.highlightedPicture = new ReactiveVar(null);
  
  // register this template within some central store
  GalleryTemplates.push(this);
});

当模板的出现因任何原因从页面中取出且未替换为重新渲染时，会调用这些回调。在回调内部，this 是要销毁的 模板实例 对象。

这组回调最适合清理或撤销 created 或 rendered 组的任何外部影响。这组回调会触发一次，并且是最后一个触发的回调。

1
2
3
4

Template.myPictures.onDestroyed(function () {
  // deregister from some central store
  GalleryTemplates = _.without(GalleryTemplates, this);
});

模板实例

模板实例对象表示模板在文档中的出现。它可用于访问 DOM，并且可以为其分配在模板响应式更新时保持不变的属性。

模板实例对象在 onCreated、onRendered 和 onDestroyed 模板回调中作为 this 的值找到，并且作为事件处理程序的参数。您可以使用 Template.instance() 从助手访问当前模板实例。

除了下面描述的属性和函数外，您还可以为该对象分配您选择的其他属性。使用 onCreated 和 onDestroyed 方法添加执行对象初始化或清理操作的回调。

您只能从 onRendered 回调和事件处理程序中访问 findAll、find、firstNode 和 lastNode，而不能从 onCreated 和 onDestroyed 中访问，因为它们要求模板实例位于 DOM 中。

模板实例对象是 instanceof Blaze.TemplateInstance。

template.findAll 返回一个 DOM 元素数组，这些元素与 selector 匹配。

template.$ 返回 jQuery 对象，它包含这些相同元素。jQuery 对象类似于数组，具有 jQuery 库定义的其他方法。

模板实例用作选择器的文档根目录。只有模板及其子模板内的元素才能与选择器的部分匹配。

返回与 selector 匹配的一个 DOM 元素，如果没有此类元素，则返回 null。

模板实例用作选择器的文档根目录。只有模板及其子模板内的元素才能与选择器的部分匹配。

firstNode 和 lastNode 这两个节点指示 DOM 中渲染的模板的范围。渲染的模板包括这些节点、它们之间的兄弟节点及其后代。这两个节点是兄弟节点（它们具有相同的父节点），lastNode 在 firstNode 之后，否则它们是同一个节点。

此属性提供对模板顶层数据上下文的访问权限。它在每次重新渲染模板时更新。访问权限为只读且非响应式。

您可以从 onCreated 或 onRendered 回调中使用 this.autorun 来响应式更新 DOM 或模板实例。您可以在此回调内部使用 Template.currentData() 来访问模板实例的响应式数据上下文。当模板销毁时，Computation 会自动停止。

template.view.autorun 的别名。

您可以从 onCreated 回调中使用 this.subscribe 来指定此模板依赖的哪些数据发布。当模板销毁时，订阅会自动停止。

有一个互补函数 Template.instance().subscriptionsReady()，它在使用 this.subscribe 调用的所有订阅都准备就绪时返回 true。

在模板的 HTML 中，您可以使用内置助手 Template.subscriptionsReady，这是一种在模板依赖于从订阅加载的数据时显示加载指示器的简单模式。

示例

1
2
3
4

Template.notifications.onCreated(function () {
  // Use this.subscribe inside onCreated callback
  this.subscribe("notifications");
});

1
2
3
4
5
6
7
8
9
10

<template name="notifications">
  {{#if Template.subscriptionsReady}}
    <!-- This is displayed when all data is ready. -->
    {{#each notifications}}
      {{> notification}}
    {{/each}}
  {{else}}
    Loading...
  {{/if}}
</template>

订阅依赖于数据上下文的另一个示例

1
2
3
4
5
6
7

Template.comments.onCreated(function () {
  // Use this.subscribe with the data context reactively
  this.autorun(() => {
    var dataContext = Template.currentData();
    this.subscribe("comments", dataContext.postId);
  });
});

1
2
3

{{#with post}}
  {{> comments postId=_id}}
{{/with}}

订阅完成时要初始化插件的另一个示例

1
2
3
4
5
6
7
8
9
10
11
12

Template.listing.onRendered(function () {
  var template = this;
  
  template.subscribe('listOfThings', () => {
    // Wait for the data to load using the callback
    Tracker.afterFlush(() => {
      // Use Tracker.afterFlush to wait for the UI to re-render
      // then use highlight.js to highlight a code snippet
      highlightBlock(template.find('.code'));
    });
  });
});

例如，Template.parentData(0) 等效于 Template.currentData()。 Template.parentData(2) 等效于模板中的 {{../..}}。

您可以在 Template.body 上定义辅助函数和事件映射，就像在任何 Template.myTemplate 对象上一样。

Template.body 上的辅助函数仅在您应用程序的 <body> 标记中可用。 要注册全局辅助函数，请使用 Template.registerHelper。 Template.body 上的事件映射不适用于通过 Blaze.render、jQuery 或 DOM API 添加到 body 的元素，也不适用于 body 元素本身。 要处理 body、window 或 document 上的事件，请使用 jQuery 或 DOM API。

Template.dynamic 允许您按名称包含模板，其中名称可能由辅助函数计算，并且可能随反应性变化。 data 参数是可选的，如果省略，则使用当前数据上下文。 还可以使用 Template.dynamic 作为块辅助函数 ({{#Template.dynamic}} ... {{/Template.dynamic}})

例如，如果存在名为“foo”的模板，{{> Template.dynamic template="foo"}} 等效于 {{> foo}}，而 {{#Template.dynamic template="foo"}} ... {{/Template.dynamic}} 等效于 {{#foo}} ... {{/foo}}。

事件映射

事件映射是一个对象，其属性指定要处理的一组事件，而值是这些事件的处理程序。 该属性可以采用以下几种形式之一

eventtype

匹配事件的类型，例如 'click'，以斜线分隔，如下所示 'touchend/mouseup/keyup'。

eventtype selector

匹配特定类型的事件，但仅当事件出现在与特定 CSS 选择器匹配的元素上时。

event1, event2

要使用相同的函数处理多个事件/选择器，请使用逗号分隔列表。

处理程序函数接收两个参数：event，一个包含有关事件的信息的对象，以及 template，定义处理程序的模板的 模板实例。 处理程序还会在 this 中接收一些额外的上下文数据，具体取决于当前处理事件的元素的上下文。 在模板中，元素的上下文是该元素出现的数据上下文，由 #with 和 #each 等块辅助函数设置。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  // Fires when any element is clicked
  'click'(event) { ... },
  
  // Fires when any element with the 'accept' class is clicked
  'click .accept'(event) { ... },
  
  // Fires when 'accept' is clicked or focused
  'click .accept, focus .accept'(event) { ... }
  'click/focus .accept'(event) { ... }
  
  // Fires when 'accept' is clicked or focused, or a key is pressed
  'click .accept, focus .accept, keypress'(event) { ... }
  'click/focus .accept, keypress'(event) { ... }
  
}

大多数事件会从其源元素向上冒泡到文档树。 例如，'click p' 会捕获段落中的任何地方的点击，即使点击源于段落内部的链接、跨度或其他元素。 事件的源元素可作为 target 属性使用，而与选择器匹配并当前处理事件的元素称为 currentTarget。

1
2
3
4
5
6

{
  'click p'(event) {
    var paragraph = event.currentTarget; // always a P
    var clickedElement = event.target; // could be the P or a child element
  }
}

如果选择器匹配事件冒泡到的多个元素，则它将被调用多次，例如在 'click div' 或 'click *' 的情况下。 如果没有给出选择器，则处理程序将仅在原始目标元素上调用一次。

传递给处理程序的事件对象上提供以下属性和方法

typeString

事件的类型，例如“click”、“blur”或“keypress”。

targetDOM Element

源自事件的元素。

currentTargetDOM Element

当前处理事件的元素。 这是与事件映射中的选择器匹配的元素。 对于冒泡的事件，它可能是 target 或 target 的祖先，并且其值会在事件冒泡时发生变化。

whichNumber

对于鼠标事件，鼠标按钮的编号 (1=左键，2=中键，3=右键)。 对于键事件，则是字符或键码。

stopPropagation()

阻止事件传播（冒泡）到其他元素。 其他与相同元素匹配的事件处理程序仍然会被触发，在当前事件映射和另一个事件映射中。

stopImmediatePropagation()

阻止此事件上所有其他事件处理程序的运行，包括此事件映射中的其他处理程序、通过冒泡到达的处理程序以及其他事件映射中的处理程序。

preventDefault()

阻止浏览器对该事件的正常响应，例如，阻止链接被跟踪或表单被提交。 仍会调用其他处理程序，但无法逆转效果。

isPropagationStopped()

返回是否已针对此事件调用 stopPropagation()。

isImmediatePropagationStopped()

返回是否已针对此事件调用 stopImmediatePropagation()。

isDefaultPrevented()

返回是否已针对此事件调用 preventDefault()。

从处理程序返回 false 与在事件上同时调用 stopImmediatePropagation 和 preventDefault 相同。

事件类型及其用途包括

click

在任何元素上单击鼠标，包括链接、按钮、表单控件或 div。 使用 preventDefault() 阻止被单击的链接被跟踪。 有些从键盘激活元素的方式也会触发 click。

dblclick

双击。

focus, blur

文本输入字段或其他表单控件获得或失去焦点。 您可以通过为元素提供 tabindex 属性使其可聚焦。 浏览器在链接、复选框和单选按钮是否天生可聚焦方面有所不同。 这些事件不会冒泡。

change

复选框或单选按钮状态发生改变。 对于文本字段，请使用 blur 或键事件来响应更改。

mouseenter, mouseleave

指针进入或离开元素的边界。 这些事件不会冒泡。

mousedown, mouseup

鼠标按钮被按下或松开。

keydown, keypress, keyup

用户按下键盘上的一个键。 keypress 最适合捕捉文本字段中的键入内容，而 keydown 和 keyup 可用于方向键或修饰键。

其他 DOM 事件也可用，但对于以上事件，Meteor 已尽力确保它们在所有浏览器中都能统一运行。