Asset

Finch 中的 Asset 是指被动态注入到页面模板中的 JavaScript 和 CSS 文件。控制器为当前请求注册 Asset，而不是在每个模板中硬编码 <script> 和 <link> 标签。然后模板通过一个占位符一次性输出所有已注册的 Asset。

这对于特定页面的脚本和样式非常有用：只有当某个页面实际需要某个数据表格库时，才会加载该库的 JS/CSS。

工作原理

控制器调用 rq.addAsset()，为当前响应注册一个或多个 Asset。
Jinja 模板调用 {{ assets.js() }} 和 {{ assets.css() }} 来输出已注册的标签。
Finch 会在这些位置渲染出正确的 <script> 或 <link> 标签。

添加 Asset

Asset 会在控制器方法内部、渲染视图之前被添加：

Future<String> showPage() async {
  // Add a single JavaScript file
  rq.addAsset(Asset(
    path: '/public/js/datatable.min.js',
    type: AssetType.js,
  ));

  // Add a CSS file
  rq.addAsset(Asset(
    path: '/public/css/datatable.min.css',
    type: AssetType.css,
  ));

  return rq.renderView(path: 'pages/books');
}

要一次添加多个 Asset，可以使用 rq.addAssets()：

rq.addAssets([
  Asset(path: '/public/js/chart.js',   type: AssetType.js),
  Asset(path: '/public/css/chart.css', type: AssetType.css),
  Asset(path: '/public/js/utils.js',   type: AssetType.js),
]);

AssetType 取值

取值	输出
`AssetType.js`	`<script src="path"></script>`
`AssetType.css`	`<link rel="stylesheet" href="path">`

在模板中输出 Asset

将 Asset 占位符放置在你的基础布局模板中。CSS 应放在 <head> 内，以便在页面渲染之前加载；JavaScript 应放在 </body> 之前，以避免阻塞页面加载：

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>{{ $t('logo.title') }}</title>

    <!-- Outputs all registered CSS <link> tags -->
    {{ assets.css() }}
  </head>
  <body>

    {% block content %}{% endblock %}

    <!-- Outputs all registered JS <script> tags -->
    {{ assets.js() }}
  </body>
</html>

如果某种类型没有注册任何 Asset，该占位符会渲染为空字符串。

提供静态文件服务

Asset 是从你的 publicDir 提供服务的静态文件。在 FinchConfigs 中配置公共目录：

FinchConfigs configs = FinchConfigs(
  publicDir: pathTo(env.get('PUBLIC_DIR', './public')),
);

publicDir 内的所有文件都可以通过其路径直接访问。例如，位于 ./public/js/app.js 的文件会通过 /public/js/app.js 提供服务。

publicDir 路径必须是绝对路径。请使用 pathTo() 相对于项目根目录来解析它。