Giao thức

Đây là tài liệu Inertia.js v1, phiên bản không còn được duy trì tích cực. Vui lòng tham khảo tài liệu v3.

Trang này trình bày đặc tả chi tiết của giao thức Inertia. Trước tiên, hãy đọc trang cách Inertia hoạt động để có cái nhìn tổng quan ở mức cao.

Response HTML

Request đầu tiên đến một ứng dụng Inertia chỉ là request trình duyệt tải toàn bộ trang thông thường, không có header hoặc dữ liệu đặc biệt nào của Inertia. Với các request này, máy chủ trả về một tài liệu HTML đầy đủ. Response HTML này bao gồm các tài nguyên của website (CSS, JavaScript) cùng với một thẻ <div> gốc trong phần body của trang. Thẻ <div> gốc đóng vai trò là điểm mount cho ứng dụng phía client và chứa một thuộc tính data-page với page object được mã hóa JSON dành cho trang ban đầu. Inertia sử dụng thông tin này để khởi động framework phía client và hiển thị page component đầu tiên.

http
REQUEST
GET: https://example.com/events/80
Accept: text/html, application/xhtml+xml

RESPONSE
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<html>
    <head>
        <title>My app</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":"Birthday party","start_date":"2019-06-02","description":"Come out and celebrate Jonathan&apos;s 36th birthday party!"}},"url":"/events/80","version":"c32b8e4965f418ad16eaebba1d4e960f"}'></div>
    </body>
</html>

Mặc dù response ban đầu là HTML, Inertia không render các page component JavaScript ở phía máy chủ.

Response của Inertia

Sau khi ứng dụng Inertia đã được khởi động, mọi request tiếp theo đến website đều được thực hiện qua XHR với header X-Inertia được đặt thành true. Header này cho biết request được thực hiện bởi Inertia và không phải là một lần tải toàn bộ trang thông thường. Khi máy chủ phát hiện header X-Inertia, thay vì phản hồi bằng một tài liệu HTML đầy đủ, nó trả về response JSON chứa page object đã được mã hóa.

REQUEST
GET: https://example.com/events/80
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5

RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json
Vary: X-Inertia
X-Inertia: true

{
    "component": "Event",
    "props": {
    "event": {
        "id": 80,
        "title": "Birthday party",
        "start_date": "2019-06-02",
        "description": "Come out and celebrate Jonathan's 36th birthday party!"
    }
    },
    "url": "/events/80",
    "version": "c32b8e4965f418ad16eaebba1d4e960f"
}

Page object

Inertia chia sẻ dữ liệu giữa máy chủ và client thông qua page object. Object này chứa các thông tin cần thiết để render page component, cập nhật history state của trình duyệt và theo dõi phiên bản asset của website. Page object bao gồm bốn thuộc tính sau:

component: Tên của page component JavaScript.
props: Props (dữ liệu) của trang.
url: URL của trang.
version: Phiên bản asset hiện tại.

Trong các lần tải toàn bộ trang thông thường, page object được mã hóa JSON vào thuộc tính data-page của thẻ <div> gốc. Trong các lần truy cập Inertia, page object được trả về dưới dạng payload JSON.

Quản lý phiên bản asset

Một thách thức phổ biến của ứng dụng một trang là làm mới các asset của website khi chúng thay đổi. Inertia giúp việc này trở nên đơn giản bằng cách cho phép theo dõi phiên bản hiện tại của asset trên website. Khi một asset thay đổi, Inertia sẽ tự động thực hiện một lần tải toàn bộ trang thay vì truy cập bằng XHR. Page object của Inertia chứa một định danh version. Phiên bản này được thiết lập ở phía máy chủ và có thể là số, chuỗi, hash của file hoặc bất kỳ giá trị nào đại diện cho “phiên bản” hiện tại của asset trên website, miễn là giá trị đó thay đổi khi asset của website được cập nhật. Mỗi khi một request Inertia được thực hiện, Inertia sẽ gửi kèm phiên bản asset hiện tại trong header X-Inertia-Version. Khi máy chủ nhận request, nó so sánh phiên bản asset được cung cấp trong header X-Inertia-Version với phiên bản asset hiện tại. Thông thường việc này được xử lý ở tầng middleware của framework phía máy chủ. Nếu hai phiên bản asset giống nhau, request tiếp tục được xử lý như bình thường. Tuy nhiên, nếu các phiên bản asset khác nhau, máy chủ ngay lập tức trả về response 409 Conflict và đặt URL trong header X-Inertia-Location. Header này là cần thiết vì có thể đã xảy ra redirect ở phía máy chủ. Thông tin này cho Inertia biết URL đích cuối cùng dự kiến là gì. Lưu ý, response 409 Conflict chỉ được gửi cho request GET, không áp dụng cho request POST/PUT/PATCH/DELETE. Tuy vậy, response này vẫn được gửi nếu sau một trong các request trên xảy ra redirect đến một request GET. Nếu tồn tại dữ liệu session dạng “flash” khi response 409 Conflict xảy ra, các adapter framework phía máy chủ của Inertia sẽ tự động flash lại dữ liệu này.

REQUEST
GET: http://example.com/events/80
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5

RESPONSE
409: Conflict
X-Inertia-Location: http://example.com/events/80

Tải lại một phần

Khi thực hiện request Inertia, tùy chọn tải lại một phần cho phép bạn chỉ yêu cầu một tập con props (dữ liệu) từ máy chủ trong các lần truy cập tiếp theo đến cùng một page component. Đây có thể là một cách tối ưu hiệu năng hữu ích nếu việc một phần dữ liệu của trang trở nên cũ là chấp nhận được. Khi một request tải lại một phần được thực hiện, Inertia gửi thêm hai header trong request: X-Inertia-Partial-Data và X-Inertia-Partial-Component. Header X-Inertia-Partial-Data là danh sách các key props (dữ liệu) mong muốn, phân tách bằng dấu phẩy, mà máy chủ cần trả về. Header X-Inertia-Partial-Component chứa tên component đang được tải lại một phần. Điều này là cần thiết vì tải lại một phần chỉ hoạt động với request đến cùng một page component. Nếu đích cuối cùng khác đi vì một lý do nào đó (ví dụ người dùng đã đăng xuất và hiện đang ở trang đăng nhập), thì việc tải lại một phần sẽ không diễn ra.

REQUEST
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

RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
    "component": "Events",
    "props": {
    "auth": {...},       // NOT included
    "categories": [...], // NOT included
    "events": [...]      // included
    },
    "url": "/events/80",
    "version": "c32b8e4965f418ad16eaebba1d4e960f"
}

Tài liệu chính thức

Bài dịch này được đối chiếu từ tài liệu Inertia.js v1 chính thức. Nếu có khác biệt do phiên bản hoặc cập nhật mới, hãy ưu tiên tài liệu chính thức làm nguồn tham chiếu.

Bắt đầu

Cài đặt

Khái niệm cốt lõi

Kiến thức cơ bản

Nâng cao

Response HTML

Response của Inertia

Page object

Quản lý phiên bản asset

Tải lại một phần

Tài liệu chính thức

​Response HTML

​Response của Inertia

​Page object

​Quản lý phiên bản asset

​Tải lại một phần

​Tài liệu chính thức

Response HTML

Response của Inertia

Page object

Quản lý phiên bản asset

Tải lại một phần

Tài liệu chính thức