TypeScript

Bạn đang xem tài liệu Inertia.js v2. Inertia.js v3 đã được phát hành và hiện là phiên bản mặc định. Hãy xem hướng dẫn nâng cấp để bắt đầu.

Inertia hỗ trợ TypeScript ở mức first-class. Bạn có thể cấu hình kiểu toàn cục bằng declaration merging và truyền generic vào hook cũng như phương thức router để có props, form và quản lý state type-safe.

Sử dụng pnpm

Do cơ chế cô lập dependency nghiêm ngặt của pnpm, @inertiajs/core không truy cập được tại node_modules/@inertiajs/core. Thay vào đó, package nằm lồng trong .pnpm/, khiến TypeScript module augmentation không thể resolve module. Bạn có thể khắc phục bằng cách cấu hình pnpm để hoist package. Thêm cấu hình sau vào file .npmrc rồi chạy pnpm install.

public-hoist-pattern[]=@inertiajs/core

Hoặc bạn có thể thêm @inertiajs/core làm dependency trực tiếp của project.

pnpm add @inertiajs/core

Cấu hình toàn cục

Bạn có thể cấu hình type của Inertia trên toàn cục bằng cách augment interface InertiaConfig trong module @inertiajs/core. Việc này thường được thực hiện trong file global.d.ts ở thư mục root hoặc thư mục types của project.

// global.d.ts
import '@inertiajs/core'

declare module "@inertiajs/core" {
  export interface InertiaConfig {
    sharedPageProps: {
      auth: { user: { id: number; name: string } | null };
      appName: string;
    };
    flashDataType: {
      toast?: { type: "success" | "error"; message: string };
    };
    errorValueType: string[];
  }
}

Câu lệnh import (hoặc export {}) là bắt buộc để biến file này thành module. Nếu thiếu nó, declare module sẽ thay thế định nghĩa module thay vì augment module. tsconfig.json cũng phải include các file .d.ts, vì vậy hãy đảm bảo mảng include có pattern như "resources/js/**/*.d.ts".

Shared page props

Tùy chọn sharedPageProps định nghĩa kiểu dữ liệu được chia sẻ với mọi trang trong ứng dụng. Với cấu hình này, page.props.auth và page.props.appName sẽ có kiểu chính xác ở mọi nơi.

sharedPageProps: {
    auth: { user: { id: number; name: string } | null }
    appName: string
}

Flash data

Tùy chọn flashDataType định nghĩa kiểu của flash data trong ứng dụng.

flashDataType: {
    toast?: { type: 'success' | 'error'; message: string }
}

Giá trị lỗi

Mặc định, giá trị validation error có kiểu string. Bạn có thể cấu hình TypeScript để nhận mảng thay thế khi dùng nhiều lỗi trên mỗi field.

errorValueType: string[]

Phiên bản tiếp theo của Laravel Wayfinder có thể tự động sinh các type này bằng cách phân tích ứng dụng Laravel. Nó sinh TypeScript type cho shared props, page props, form request và Eloquent model. Phiên bản này hiện đang ở giai đoạn beta.

Page component

Bạn có thể khai báo type cho kết quả import.meta.glob để tăng type safety khi resolve page component.

import { createInertiaApp } from "@inertiajs/vue3";
import type { DefineComponent } from "vue";

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob<DefineComponent>("./Pages/**/*.vue", {
      eager: true,
    });
    return pages[`./Pages/${name}.vue`];
  },
  // ...
});

import { createInertiaApp, type ResolvedComponent } from "@inertiajs/react";

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob<ResolvedComponent>("./Pages/**/*.tsx", {
      eager: true,
    });
    return pages[`./Pages/${name}.tsx`];
  },
  // ...
});

import { createInertiaApp, type ResolvedComponent } from "@inertiajs/svelte";

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob<ResolvedComponent>("./Pages/**/*.svelte", {
      eager: true,
    });
    return pages[`./Pages/${name}.svelte`];
  },
  // ...
});

Page props

Bạn có thể khai báo kiểu cho prop riêng của từng trang bằng cách truyền generic vào usePage(). Chúng được gộp với sharedPageProps toàn cục, nhờ đó bạn có autocomplete và type checking cho cả dữ liệu shared lẫn dữ liệu riêng của trang.

<script setup lang="ts">
import { usePage } from "@inertiajs/vue3";

const page = usePage<{
  posts: { id: number; title: string }[];
}>();
</script>

import { usePage } from "@inertiajs/react";

export default function Posts() {
  const page = usePage<{
    posts: { id: number; title: string }[];
  }>();

  return (
    <ul>
      {page.props.posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

<script lang="ts">
    import { usePage } from '@inertiajs/svelte'

    const page = usePage<{
        posts: { id: number; title: string }[]
    }>()
</script>

Form helper

Form helper nhận generic type parameter để đảm bảo type-safe cho form data và error handling. Điều này cung cấp autocomplete cho field và error, đồng thời ngăn lỗi chính tả trong tên field.

<script setup lang="ts">
import { useForm } from "@inertiajs/vue3";

const form = useForm<{
  name: string;
  email: string;
  company: { name: string };
}>({
  name: "",
  email: "",
  company: { name: "" },
});
</script>

import { useForm } from "@inertiajs/react";

export default function CreateUser() {
  const form = useForm<{
    name: string;
    email: string;
    company: { name: string };
  }>({
    name: "",
    email: "",
    company: { name: "" },
  });

  return null;
}

<script lang="ts">
    import { useForm } from '@inertiajs/svelte'

    const form = useForm<{
        name: string
        email: string
        company: { name: string }
    }>({
        name: '',
        email: '',
        company: { name: '' },
    })
</script>

Dữ liệu lồng nhau và mảng

Form type hỗ trợ đầy đủ object lồng nhau và mảng. Bạn có thể truy cập và cập nhật field lồng nhau bằng dot notation, còn error key sẽ tự động có kiểu tương ứng.

import { useForm } from "@inertiajs/react";

const form = useForm<{
  user: { name: string; email: string };
  tags: { id: number; label: string }[];
}>({
  user: { name: "", email: "" },
  tags: [],
});

Ghi nhớ state

Hook useRemember nhận generic type parameter để lưu local state an toàn kiểu, cung cấp autocomplete và đảm bảo giá trị khớp với kiểu mong đợi.

<script setup lang="ts">
import { useRemember } from "@inertiajs/vue3";

const filters = useRemember<{
  search: string;
  status: "active" | "inactive" | "all";
}>({
  search: "",
  status: "all",
});
</script>

import { useRemember } from "@inertiajs/react";

export default function Users() {
  const [filters, setFilters] = useRemember<{
    search: string;
    status: "active" | "inactive" | "all";
  }>({
    search: "",
    status: "all",
  });

  return null;
}

<script lang="ts">
    import { useRemember } from '@inertiajs/svelte'

    const filters = useRemember<{
        search: string
        status: 'active' | 'inactive' | 'all'
    }>({
        search: '',
        status: 'all',
    })
</script>

Khôi phục state

Phương thức router.restore() nhận generic để khai báo kiểu cho state được khôi phục từ history.

import { router } from "@inertiajs/react";

interface TableState {
  sortBy: string;
  sortDesc: boolean;
  page: number;
}

const restored = router.restore<TableState>("table-state");

if (restored) {
  console.log(restored.sortBy);
}

Router request

Các phương thức router nhận generic để khai báo kiểu cho request data, giúp type checking dữ liệu được gửi đi.

import { router } from "@inertiajs/react";

interface CreateUserData {
  name: string;
  email: string;
}

router.post<CreateUserData>("/users", {
  name: "John",
  email: "john@example.com",
});

Flash data theo scope

Phương thức router.flash() nhận generic để khai báo kiểu cho flash data riêng theo trang hoặc section, tách biệt với cấu hình flashDataType toàn cục.

import { router } from "@inertiajs/react";

router.flash<{ paymentError: string }>({ paymentError: "Card declined" });

Client-side visits

Các phương thức router.push() và router.replace() nhận generic để khai báo kiểu cho prop của client-side visit.

import { router } from "@inertiajs/react";

interface UserPageProps {
  user: { id: number; name: string };
}

router.push<UserPageProps>({
  component: "Users/Show",
  url: "/users/1",
  props: { user: { id: 1, name: "John" } },
});

router.replace<UserPageProps>({
  props: (current) => ({
    ...current,
    user: { ...current.user, name: "Updated" },
  }),
});

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 v2 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

Dữ liệu & Props

Bảo mật

Nâng cao

Sử dụng pnpm

Cấu hình toàn cục

Shared page props

Flash data

Giá trị lỗi

Page component

Page props

Form helper

Dữ liệu lồng nhau và mảng

Ghi nhớ state

Khôi phục state

Router request

Flash data theo scope

Client-side visits

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

​Sử dụng pnpm

​Cấu hình toàn cục

​Shared page props

​Flash data

​Giá trị lỗi

​Page component

​Page props

​Form helper

​Dữ liệu lồng nhau và mảng

​Ghi nhớ state

​Khôi phục state

​Router request

​Flash data theo scope

​Client-side visits

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

Sử dụng pnpm

Cấu hình toàn cục

Shared page props

Flash data

Giá trị lỗi

Page component

Page props

Form helper

Dữ liệu lồng nhau và mảng

Ghi nhớ state

Khôi phục state

Router request

Flash data theo scope

Client-side visits

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