inertiajs 中文文档协议
协议#
本页面包含 Inertia 协议的详细规范。请务必先阅读工作原理页面，以获得一个高层次的概述.
HTML 响应#
对于 Inertia 应用的第一个请求，它只是一个普通的完整页面浏览器请求，没有特殊的 Inertia 头部或数据。对于这些请求，服务器返回一个完整的 HTML 文档。
这个 HTML 响应包括网站资源（CSS、JavaScript），以及页面主体中的一个根 <div>。根 <div> 作为客户端应用的挂载点，并包含一个带有 JSON 编码的页面对象的 data-page 属性。Inertia 使用这些信息来启动您的客户端框架并显示初始页面组件。
请求
GET: http://example.com/events/80
Accept: text/html, application/xhtml+xml
响应
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
<html>
<head>
<title>我的应用</title>
<link href="/css/app.css" rel="stylesheet">
<script src="/js/app.js" defer></script>
</head>
<body>
<div id="app" data-page='{"component":"Event","props":{"event":{"id":80,"title":"生日派对","start_date":"2019-06-02","description":"快来参加Jonathan的36岁生日派对！"}},"url":"/events/80","version":"c32b8e4965f418ad16eaebba1d4e960f"}'></div>
</body>
</html>虽然初始响应是 HTML，但 Inertia 不会在服务器端渲染 JavaScript 页面组件。
Inertia 响应#
一旦 Inertia 应用启动，对站点的所有后续请求都通过 XHR 进行，其中 X-Inertia 头部设置为 true。这个头部指示该请求是由 Inertia 发起的，并不是一个标准的完整页面访问。
当服务器检测到 X-Inertia 头部时，服务器不会返回完整的 HTML 文档，而是返回一个带有编码的页面对象的 JSON 响应。
请求
GET: http://example.com/events/80
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5
响应
HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept
X-Inertia: true
{
"component": "Event",
"props": {
"event": {
"id": 80,
"title": "生日派对",
"start_date": "2019-06-02",
"description": "快来参加Jonathan的36岁生日派对！"
}
},
"url": "/events/80",
"version": "c32b8e4965f418ad16eaebba1d4e960f"
}页面对象#
Inertia 通过页面对象在服务器和客户端之间共享数据。该对象包含了渲染页面组件、更新浏览器历史状态和跟踪站点资源版本所需的必要信息。页面对象包含以下四个属性：
- component: JavaScript 页面组件的名称。
- props: 页面属性（数据）。
- url: 页面的 URL。
- version: 当前资源版本。
在标准的完整页面访问中，页面对象被 JSON 编码到根 <div> 的 data-page 属性中。在 Inertia 访问中，页面对象作为 JSON 负载返回。
资源版本控制#
单页应用的一个常见挑战是在资源更改时刷新站点资源。Inertia 通过可选地跟踪站点资源的当前版本来简化此过程。如果资源发生变化，Inertia 会自动进行完整页面访问，而不是 XHR 请求。
Inertia 的页面对象包括一个 version 标识符。这个版本标识符是在服务器端设置的，可以是数字、字符串、文件哈希或任何代表站点资源当前 “版本” 的值，只要该值在站点资源更新时发生变化即可。
每当发起 Inertia 请求时，Inertia 会在 X-Inertia-Version 头部中包含当前资源版本。当服务器接收到请求时，它会将 X-Inertia-Version 头部提供的资源版本与当前资源版本进行比较。这通常在服务器端框架的中间件层处理。
如果资源版本相同，请求会按预期继续进行。然而，如果资源版本不同，服务器立即返回 409 Conflict 响应，并在 X-Inertia-Location 头部中包含 URL。这个头部是必需的，因为可能发生了服务器端重定向。这告诉 Inertia 最终目标的 URL 是什么。
请注意，在 GET 请求中只发送 409 Conflict 响应，而不是 POST/PUT/PATCH/DELETE 请求。然而，在这些请求之后，如果发生 GET 重定向，也会发送 409 Conflict 响应。
当 409 Conflict 响应发生时，如果存在 “闪存” 会话数据，Inertia 的服务器端框架适配器将自动刷新这些数据。
请求
GET: http://example.com/events/80
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5
响应
409: Conflict
X-Inertia-Location: http://example.com/events/80部分刷新#
在进行 Inertia 请求时，部分刷新选项允许您在对同一个页面组件后续访问时，从服务器请求一部分属性（数据）。如果一些页面数据变得过时是可以接受的话，这可以是一种有用的性能优化。
当进行部分刷新请求时，Inertia 会在请求中包含两个额外的头部：X-Inertia-Partial-Data 和 X-Inertia-Partial-Component。
X-Inertia-Partial-Data 头部是一个逗号分隔的所需属性（数据）键列表，应该返回这些属性。
X-Inertia-Partial-Component 头部包含正在部分刷新的组件的名称。这是必需的，因为部分刷新仅适用于对同一个页面组件发起的请求。如果由于某种原因（例如用户已注销并且现在在登录页面上）最终目标不同，则不会进行部分刷新。
请求
GET: http://example.com/events
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5
X-Inertia-Partial-Data: events
X-Inertia-Partial-Component: Events
响应
HTTP/1.1 200 OK
Content-Type: application/json
{
"component": "Events",
"props": {
"auth": {...}, // 不包括
"categories": [...], // 不包括
"events": [...] // 包括
},
"url": "/events/80",
"version": "c32b8e4965f418ad16eaebba1d4e960f"
}
关于 LearnKu
粤公网安备 44030502004330号
推荐文章：