نوعهای پایه و آرایه
نوع مقدارها و مجموعههای همنوع را مشخص کنید.
const title: string = "Guide";const count: number = 3;const enabled: boolean = true;const tags: string[] = ["web", "typed"];
الگوهای اصلی تایپگذاری TypeScript برای داده، توابع و محدودکردن حالتهای نامعتبر. نوعها را بر اساس شکل واقعی داده تعریف کنید و حالتهای معتبر را تا حد ممکن محدود نگه دارید. TypeScript در زمان اجرا دادهٔ ورودی را اعتبارسنجی نمیکند. امضای تابع، نوع ورودی و خروجی را روشن میکند. برای دادهٔ ناشناخته از `unknown` شروع کنید و با guard نوع قابلاستفاده بسازید. از این صفحه بهعنوان مرجع سریع استفاده کنید و مثالها و نکتهها را با نسخهٔ ابزار، نیاز و شرایط واقعی پروژهٔ خود تطبیق دهید.
نوع مقدارها و مجموعههای همنوع را مشخص کنید.
const title: string = "Guide";const count: number = 3;const enabled: boolean = true;const tags: string[] = ["web", "typed"];برای قرارداد شیء، propertyهای لازم و اختیاری را جدا کنید.
type User = { id: string; name: string; nickname?: string;};مجموعهٔ محدود literalها جلوی مقدارهای خارج از قرارداد را میگیرد.
type Status = "idle" | "loading" | "success" | "error";function setStatus(status: Status) { return status;}با کلید متمایز، دادهٔ هر حالت را دقیق مدل و در switch بهصورت امن narrow کنید.
type Result<T> = | { state: "success"; data: T } | { state: "error"; message: string };function show<T>(result: Result<T>) { if (result.state === "success") return result.data; return result.message;}نوع ورودی و خروجی تابع را صریح تعریف کنید.
function formatName(first: string, last: string): string { return `${first} ${last}`;}پارامتر اختیاری یا دارای مقدار پیشفرض را متناسب با قرارداد انتخاب کنید.
function greet(name: string, prefix = "Hello"): string { return `${prefix}, ${name}`;}greet("Sam");greet("Sam", "Welcome");پیش از استفاده از مقدار ناشناخته، نوع آن را در زمان اجرا بررسی کنید.
function isString(value: unknown): value is string { return typeof value === "string";}function lengthOf(value: unknown) { return isString(value) ? value.length : 0;}Generic رابطهٔ نوع ورودی و خروجی را حفظ میکند، بدون اینکه نوع مشخص را قربانی کند.
function first<T>(items: readonly T[]): T | undefined { return items[0];}const firstId = first([10, 20]);قرارداد شیء را میتوان با interface توسعه داد.
interface Identified { id: string;}interface Product extends Identified { name: string; price: number;}برای دادهٔ ثابت، تغییرناپذیری و literal typeها را حفظ کنید.
const settings = { mode: "compact", retries: 3,} as const;type Settings = typeof settings;از نوع موجود برای فرم و projection داده نوع جدید بسازید.
type User = { id: string; name: string; email: string };type UserUpdate = Partial<Pick<User, "name" | "email">>;type PublicUser = Omit<User, "email">;Record برای mapهای همشکل و keyof برای کلیدهای معتبر مفید است.
type Theme = "light" | "dark";const labels: Record<Theme, string> = { light: "روشن", dark: "تیره",};type LabelKey = keyof typeof labels;خروجیهای عمومی فایل را صریح و قابلپیشبینی نگه دارید.
export type { User } from "./user";export { createUser } from "./user";import { createUser } from "./user";assertion نوع را در runtime بررسی نمیکند؛ ابتدا guard بنویسید.
function printId(value: string | number) { if (typeof value === "number") { return value.toFixed(0); } return value.toUpperCase();}حالت strict بررسی نوع را تقویت میکند؛ تنظیمات را تدریجی در پروژه فعال کنید.
{ "compilerOptions": { "strict": true, "noEmit": true }}نوع پایه: string، number، boolean و آرایه مانند string[].
برای شکل داده از type یا interface با ویژگیهای دقیق استفاده کنید.
اتحاد محدود: type Status = "idle" | "loading" | "done"
مقدار احتمالی را با guard بررسی کنید تا narrowing انجام شود.
نوع nullable را با string | null بیان و پیش از استفاده کنترل کنید.
Generics: function identity<T>(value: T): T برای حفظ نوع ورودی.
از unknown برای داده نامطمئن استفاده کنید و پیش از مصرف آن را narrow کنید.
نوع خروجی تابع و APIهای مهم را صریح مشخص کنید.
readonly و as const را برای دادههای ثابت و محدود بهکار ببرید.
از any و type assertion فقط در مرزهای اجتنابناپذیر و با دلیل استفاده کنید.
برای حالتهای محدود از discriminated union استفاده کنید تا هر شاخه با یک کلید قابل تشخیص و exhaustiveness قابل بررسی باشد.
دادهٔ بیرونی را در زمان اجرا validate کنید؛ typeهای TypeScript بهتنهایی پاسخ API را اعتبارسنجی نمیکنند.
از unknown برای دادهٔ ناشناخته استفاده کنید و پس از type guard آن را مصرف کنید؛ as نوع را در زمان اجرا بررسی نمیکند.