模板

Finch 使用 Jinja Dart 包作为其模板引擎。模板文件位于 FinchConfigs.widgetsPath 所配置的目录中，并使用 FinchConfigs.widgetsType 中设置的扩展名（默认为 j2.html）。

渲染模板

调用 rq.renderView(path: '...')，路径相对于 widgetsPath，且不含文件扩展名：

// Loads: widgetsPath/pages/home.j2.html
return rq.renderView(path: 'pages/home');

在调用 renderView 之前，使用 rq.addParam() 或 rq.addParams() 向模板传递数据：

rq.addParams({
  'title': 'My Page',
  'user': user.toJson(),
  'items': items.map((i) => i.toJson()).toList(),
});
return rq.renderView(path: 'pages/home');

模板语法

Finch 使用标准的 Jinja2 语法。分隔符可以在 FinchConfigs 中配置，默认如下：

变量

{{ title }}
{{ user.name }}
{{ user['email'] }}

控制流

{% if user %}
  <p>Hello, {{ user.name }}</p>
{% else %}
  <p>Please log in.</p>
{% endif %}

{% for item in items %}
  <li>{{ item.title }}</li>
{% endfor %}

引入

{% include 'partials/header.j2.html' %}

继承 / 块

{# layout.j2.html #}
<!DOCTYPE html>
<html>
<head><title>{% block title %}{% endblock %}</title></head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

{# pages/home.j2.html #}
{% extends 'layout.j2.html' %}

{% block title %}Home{% endblock %}

{% block content %}
  <h1>{{ title }}</h1>
{% endblock %}

使用打包（Map）模板

对于编译后的二进制文件，模板无法在运行时从磁盘读取。可以使用 FinchConfigs 中的 jinjaMapTemplate，将模板打包为一个 Map<String, String>：

// Generated by: finch build or finch runner
final mapTemplates = {
  'pages/home.j2.html': '<h1>{{ title }}</h1>',
  // ...
};

FinchConfigs configs = FinchConfigs(
  jinjaMapTemplate: mapTemplates,
  widgetsType: 'j2.html',
);

当模板文件发生变化时，finch serve 的监听器会自动重新生成该映射表。

自定义模板函数（localEvents）

添加可在任何模板中调用的全局函数：

// In app.dart
Request.localEvents.addAll({
  'currentYear': () => DateTime.now().year,
  'formatDate': (String iso) => iso.substring(0, 10),
});

在模板中（使用 $l. 前缀调用本地事件）：

<footer>© {{ $l.currentYear() }}</footer>
<span>{{ $l.formatDate(post.createdAt) }}</span>

自定义过滤器（localLayoutFilters）

添加 Jinja 过滤器：

Request.addLocalLayoutFilters({
  'upper': (value) => value.toString().toUpperCase(),
  'excerpt': (value) {
    var s = value.toString();
    return s.length > 100 ? '${s.substring(0, 100)}…' : s;
  },
});

在模板中：

{{ post.title | upper }}
{{ post.body | excerpt }}

内置 Finch 模板变量

以下变量会自动在每个模板中可用：

{{ isLocalDebug }}        — true in development mode
{{ data }}                — all addParam() data
{{ session }}             — current session map
{{ $rq }}                 — the Request object

参阅 Template Events 获取完整的 $e.* 和 $t() 辅助方法列表。

Complete Example

<!DOCTYPE html>
<html lang="{{ $e.ln }}" dir="{{ $t('dir') }}">
<head>
  <meta charset="UTF-8">
  <title>{{ $t(title) }}</title>
  {{ assets.css() }}
</head>
<body>
  <nav>
    {% if user %}
      <a href="/logout">{{ user.name }}</a>
    {% else %}
      <a href="/login">Login</a>
    {% endif %}
  </nav>

  <main>
    {% block content %}{% endblock %}
  </main>

  {{ assets.js() }}
</body>
</html>