meteor-blaze

Meteor 3 的 Blaze 接口

Blaze 会将 Spacebars 模板编译成 JavaScript，并在响应式依赖失效时更新较小的 View 区域。让状态、订阅、DOM 效果和异步工作都归属于某个模板实例。在应用代码中使用公开的 Template、Blaze、Spacebars 和 Tracker API。

决策流程

1. 对于新应用，运行 meteor create --blaze <name>。更改软件包或构建设置前，请检查生成的 package.json、.meteor/packages、客户端入口文件和 rspack.config.js。
2. 在注册模板 helper、事件和生命周期钩子的 JavaScript 模块中导入每个模板的 .html。从客户端入口模块图中导入该模块。
3. 在普通 helper 中进行同步 Minimongo 读取。如果 helper 返回 Promise，请明确渲染等待、拒绝和已解析状态。
4. 将 ReactiveVar、ReactiveDict、this.autorun 和 this.subscribe 放在模板实例上。将 DOM 初始化放在 onRendered 中，并在 onDestroyed 中撤销外部效果。
5. 将命名数据和回调传递给可复用的子模板。将发布和变更权限保留在服务器端。
6. 诊断刷新行为前，先确认使用的打包器。blaze-hot 可以在 Meteor 打包器模块图中替换模板；Rspack 目前会对 Blaze 执行完整热重载。通用构建、迁移、数据库或测试运行器相关工作应交由相应的技能处理。

当前脚手架

meteor create --blaze my-app
cd my-app
meteor

Meteor 3.4 及更高版本默认使用 Rspack 创建 Blaze 应用。较早的 Meteor 3 版本可能使用 Meteor 打包器。当前脚手架声明了明确的客户端和服务器 meteor.mainModule 入口，且会从客户端入口导入 .html、启用现代构建栈，并包含 blaze-html-templates、tracker、reactive-var、hot-module-replacement、blaze-hot 和 rspack。请以所选 Meteor 版本生成的文件为基准。这些软件包不会在 Rspack 模块图中启用 Blaze HMR。此处的 Blaze 编辑会触发快速的整页重载，并重置页面局部状态。blaze-hot 的替换行为仅适用于由 Meteor 打包器管理的模块。

不要仅凭版本名称推断已安装的 Blaze 运行时。请检查 .meteor/versions，然后参考 Blaze 历史记录了解功能最低版本要求和兼容性变更。

Meteor 3.6-beta.0 的 meteor create --pwa <name> 可提供使用 Blaze/Rspack 的可安装 Web 应用，并配有无依赖的 service worker。它不会提供离线 Meteor 数据或原生二进制文件。更改缓存或作用域前，请阅读 PWA 边界。

组件脚手架

<template name="taskList">
  <label>
    <input type="checkbox" class="js-show-done">
    Show completed
  </label>

  {{#if Template.subscriptionsReady}}
    {{#each task in tasks}}
      {{> taskRow task=task}}
    {{else}}
      <p>No tasks.</p>
    {{/each}}
  {{else}}
    <p>Loading...</p>
  {{/if}}
</template>

import { Template } from "meteor/templating";
import { ReactiveVar } from "meteor/reactive-var";
import { Tasks } from "/imports/api/tasks";
import "./task-list.html";

Template.taskList.onCreated(function () {
  this.showDone = new ReactiveVar(false);
  this.autorun(() => {
    this.subscribe("tasks.list", { showDone: this.showDone.get() });
  });
});

Template.taskList.helpers({
  tasks() {
    const showDone = Template.instance().showDone.get();
    return Tasks.find(showDone ? {} : { done: false }, {
      sort: { createdAt: -1 },
    });
  },
});

Template.taskList.events({
  "change .js-show-done"(event, instance) {
    instance.showDone.set(event.currentTarget.checked);
  },
});

模板实例销毁时，this.autorun 和 this.subscribe 会停止。同步 helper 返回的游标会通过 Minimongo 保持实时。授权和字段投影仍应由发布负责。

异步 helper

当加载、拒绝和空结果必须区分时，请使用 #let：

{{#let profile=loadProfile}}
  {{#if @pending "profile"}}<p>Loading...</p>{{/if}}
  {{#if @rejected "profile"}}<p>Could not load profile.</p>{{/if}}
  {{#if @resolved "profile"}}
    {{> profileCard profile=profile}}
  {{/if}}
{{/let}}

Spacebars 会存储最近一次解析的值，但这不一定是最新 Promise 的结果。如果响应式输入可能触发重叠请求，请使用中止信号、代次令牌或串行队列。不要假设 #let 会对结果排序。请参阅 references/spacebars-and-async.md。

生命周期所有权

资源	创建	销毁
ReactiveVar 或 ReactiveDict	onCreated	无需手动释放
响应式工作	this.autorun	随实例自动销毁
订阅	this.subscribe	随实例自动销毁
DOM 组件	onRendered，通常在 Tracker.afterFlush 之后	在 onDestroyed 中执行组件特定的拆除操作
Window、document、计时器、观察器	生命周期回调	在 onDestroyed 中显式移除、清除、断开连接或停止
以编程方式创建的 Blaze View	Blaze.render 或 Blaze.renderWithData	Blaze.remove(view)

阅读 references/lifecycle-and-components.md，了解数据上下文规则、 回调、动态模板、DOM 作用域和清理模式。

路由边界

请求	路由
全新的 Blaze UI、Spacebars、模板生命周期、异步渲染	此技能
通用 Rspack 或 SWC 设置和配置辅助工具	meteor-modern-build-stack
将现有应用迁移到 Rspack	migrate-to-rspack
将 Blaze 代码从 Meteor 2 升级到 Meteor 3	migrate-to-meteor-3
发布设计或订阅授权	meteor-pubsub
Mongo 和 Minimongo API 选择	meteor-mongo-minimongo
Mocha 驱动程序、浏览器运行器或端到端测试设置	meteor-testing
CSP、清理审查或更广泛的加固	meteor-security

仅在处理 Blaze 专属的入口导入、HMR 所有权和以编程方式进行的模板测试时， 使用 references/build-hmr-and-testing.md。

反模式

• 在每个辅助函数中返回异步 Minimongo 值。除非流程本身已是异步，或与服务端共享， 否则优先使用同步客户端读取。
• 在 await 之后读取响应式数据，却不恢复捕获的 Tracker 计算。
• 将 {{#each ...}}{{else}} 视为加载指示器。else 分支也会涵盖拒绝状态和已解析的空序列。
• 在可复用模板中传递隐式继承的上下文。请传递具名数据。
• 使用全局 $() 或 document.querySelector 操作组件 DOM。请将查找范围限定在模板实例内。
• 未经过可信清理，就通过三重花括号或 Spacebars.SafeString 插入用户控制的内容。
• 移除由 Blaze.render 创建的 DOM 节点，却不调用 Blaze.remove。
• 依赖 UI.body、Template.__define__、Template.__body__、Spacebars.TemplateWith 或 Blaze.InOuterTemplateScope 等私有或已移除的 UI 时代 API。

权威资源

• Meteor Blaze 教程
• Blaze 指南
• Spacebars API
• Templates API
• Blaze 编程 API
• meteor/blaze 源码和测试
• references/spacebars-and-async.md
• references/lifecycle-and-components.md
• references/build-hmr-and-testing.md
• references/eval-cases.md