README

使用 Kirby 和 Inertia.js 创建服务器端渲染的单页应用（SPA）。此插件配置您的 Kirby 网站以输出 Inertia 响应并集成 Inertia 的服务器端渲染器。

Inertia.js 是什么？

Inertia 是构建经典服务器驱动型网络应用的新方法。它与 Kirby 的面板后端架构类似 - 但它有一个围绕 Vue、React 和 Svelte 生态系统构建的环境。

原始 JSON 数据从服务器返回并在客户端渲染。这允许您构建 SPA 而无需构建单独的 API。利用服务器端渲染器，这非常适合高度交互式但不应受 SEO 或性能问题困扰的网站。

使用方法

设置

我建议使用 Vite 和 kirby-laravel-vite 编译您的前端资源。这是开始使用强大的构建设置而不必过于担心配置的最好方式。

要开始使用 Inertia，只需使用 composer 安装插件（composer require tobimori/kirby-inertia）并设置您的 default.php 模板以包含 Inertia 响应即可

<!DOCTYPE html>
<html>

<head>
	<?php /* other meta tags */ ?>

	<?php /* kirby-laravel-vite */ ?>
	<?= vite()->reactRefresh() ?>
	<?= vite(['src/index.tsx', 'src/styles/index.css']) ?>

	<?= inertiaHead() ?> <?php /* for server-side-rendered head */ ?>
</head>

<body>
	<?= inertia() ?>  <?php /* renders the application shell or server-side-rendered content */ ?>
</body>

</html>

然后您可以开始构建您的 Inertia 前端。

创建响应

我们在 Kirby 控制器中创建 Inertia 响应。您可以使用 Inertia::createResponse() 方法正确地格式化响应。默认控制器仅对页面运行 toArray() 方法。您可以通过为您的页面模板创建自定义控制器来覆盖此操作。

<?php

use Kirby\Cms\Page;
use tobimori\Inertia\Inertia;

return function (Page $page) {
	return Inertia::createResponse(
		$page->intendedTemplate(), // the component name passed to inertia
		$page->toArray() // the props passed to the component
	);
};

如果您需要在 Kirby 模板中访问任何其他数据，您可以通过返回一个数组作为第三个参数来传递它。

懒加载评估

Inertia 允许从服务器部分请求数据。在这种情况下，如果您在控制器中运行资源密集型操作，您可能希望延迟这些操作，直到它们实际需要。您可以通过使用 Kirby 的 LazyValue 类作为属性来实现这一点。

Inertia::createResponse(
	'page',
	[
		'title' => $page->title(), // will be evaluated immediately
		'children' => new LazyValue(function () use ($page) { // will be evaluated when requested
			return $page->children()->listed();
		})
	]
);

共享数据

可以在模板中第一次调用 inertia() 或 inertiaHead() 之前定义任何地方的应用程序中的共享数据。您可以使用 Inertia::share() 方法来定义共享数据。

Inertia::share('user', kirby()->user()->id());

您还可以使用配置选项 tobimori.inertia.shared 在您的 site/config/config.php 文件中定义共享数据。

// site/config/config.php
return [
	'tobimori.inertia.shared' => [
		'user' => new LazyValue(function () { // lazy evaluation works here as well
			return kirby()->user()->id();
		})
	]
];

请注意，您不能在配置文件中访问 Kirby 实例，因此我们在这里使用 LazyValue 类。

服务器端渲染

Inertia 允许您在服务器端渲染您的应用程序。这特别适用于 SEO 和性能原因。要启用服务器端渲染，您需要将配置选项 tobimori.inertia.ssr.enabled 设置为 true。

// site/config/config.php
return [
	'tobimori.inertia.ssr' => [
		'enabled' => true,
		'server' => 'http://127.0.0.1:13714'
	],
];

您还必须指定服务器端渲染器的 URL。

Kirby Inertia 不像 Laravel 包那样提供启动服务器端渲染器的命令，您必须使用进程管理器（如 PM2）自己实现。

自定义路由

如果您想为您的Inertia应用使用自定义路由（例如，当数据定义在组件中时），您可以使用Inertia::route()辅助函数在您的site/config/config.php文件中定义自定义路由。

// site/config/config.php
return [
	'routes' => [
		Inertia::route('about', 'about') // renders the about component on /about
	]
];

缓存

目前对Kirby缓存的支撑处于开发中，启用页面缓存时可能会有问题。

自动模板

此插件自动将默认模板分配给所有没有分配模板的控制器页面。这是必要的，以便Kirby能够正确识别控制器。

致谢

此插件的部分代码基于由Jon Gacnik编写的、不支持服务器端渲染的较老版本的Inertia实现。

tobimori / kirby-inertia

维护者

详细信息