TypeScript 内置工具类型速查手册

interface TableConfig {
  border: boolean;
  stripe: boolean;
  size: "large" | "default" | "small";
  showHeader: boolean;
}

const customConfig: Partial<TableConfig> = {
  size: "small",
  stripe: true,
};

type UpdateUserPayload = { id: string } & Partial<Omit<UserEntity, "id">>;

async function patchUser(payload: UpdateUserPayload) {
  // 只传 { id, avatar } 也合法
  await fetch(`/api/users/${payload.id}`, {
    method: "PATCH",
    body: JSON.stringify(payload),
  });
}

patchUser({ id: "u-001", avatar: "https://cdn.example.com/new.png" }); // ✅

type UserInputConfig = Partial<TableConfig>;

function mergeConfig(options: UserInputConfig): Required<TableConfig> {
  return {
    border: options.border ?? false,
    stripe: options.stripe ?? false,
    size: options.size ?? "default",
    showHeader: options.showHeader ?? true,
  };
}

interface ProfileForm {
  nickname?: string;
  phone?: string;
  email?: string;
  departmentId?: string;
}

// 提交时断言所有字段已填写
function submitProfile(form: Required<ProfileForm>) {
  console.log("提交:", form.nickname, form.email);
}

// 调用时 TS 会强制要求所有字段
submitProfile({
  nickname: "Alice",
  phone: "138-0000-0000",
  email: "alice@example.com",
  departmentId: "D-02",
});

interface TenantContext {
  tenantId: string;
  tenantName: string;
  isVip: boolean;
}

const currentTenant: Readonly<TenantContext> = {
  tenantId: "T-8848",
  tenantName: "华东区代理",
  isVip: true,
};
// currentTenant.tenantId = "T-1001"; // ❌ 只读属性

function applyTheme(theme: Readonly<{ primary: string; fontSize: number }>) {
  // theme.primary = "red"; // ❌ 编译报错，阻止意外修改
  document.documentElement.style.setProperty("--primary", theme.primary);
}

const a = { x: 1, y: [2, 3] } as const;
// a.x = 10;     // ❌ 深层只读
// a.y.push(4);  // ❌ 数组也只读

const b: Readonly<{ x: number; y: number[] }> = { x: 1, y: [2, 3] };
// b.x = 10;     // ❌
b.y.push(4); // ✅ 浅层只读，数组内容仍可变

type AppRole = "super_admin" | "tenant_admin" | "editor";

const rolePermissions: Record<AppRole, string[]> = {
  super_admin: ["all"],
  tenant_admin: ["user_manage", "content_manage"],
  editor: ["content_edit"],
  // 若漏写 editor，TS 会报错 ✅ 穷举检查
};

const cache: Record<string, unknown> = {};
cache["user_123"] = { name: "Alice" };

type HttpStatus = 200 | 201 | 400 | 401 | 403 | 404 | 500;

const statusMessages: Record<HttpStatus, string> = {
  200: "OK",
  201: "Created",
  400: "Bad Request",
  401: "Unauthorized",
  403: "Forbidden",
  404: "Not Found",
  500: "Internal Server Error",
};

function getStatusMessage(code: HttpStatus): string {
  return statusMessages[code];
}

type Locale = "zh-CN" | "en-US" | "ja-JP";

const dateFormats: Record<Locale, Intl.DateTimeFormatOptions> = {
  "zh-CN": { year: "numeric", month: "2-digit", day: "2-digit" },
  "en-US": { month: "short", day: "numeric", year: "numeric" },
  "ja-JP": { year: "numeric", month: "long", day: "numeric" },
};

interface UserEntity {
  id: string;
  username: string;
  passwordHash: string;
  avatar: string;
  departmentId: string;
  createdAt: string;
}

type NavbarUserInfo = Pick<UserEntity, "username" | "avatar">;

const navUser: NavbarUserInfo = {
  username: "Admin",
  avatar: "https://cdn.example.com/avatar.png",
};

// 列表卡片只需要这几个字段，不暴露 passwordHash / departmentId
type UserCardProps = Pick<UserEntity, "id" | "username" | "avatar">;

function UserCard({ id, username, avatar }: UserCardProps) {
  return `<div data-id="${id}">${username}</div>`;
}

type CreateUserPayload = Omit<UserEntity, "id" | "createdAt" | "passwordHash">;

const newUser: CreateUserPayload = {
  username: "new_employee",
  avatar: "",
  departmentId: "D-01",
};

// 创建：去掉服务端自动生成的字段
type CreateArticleDto = Omit<
  ArticleEntity,
  "id" | "createdAt" | "updatedAt" | "viewCount"
>;

// 更新：创建基础上再套 Partial，所有字段可选
type UpdateArticleDto = Partial<CreateArticleDto>;

// 查询响应：完整实体
type ArticleResponse = ArticleEntity;

type ComponentSizes = "large" | "default" | "small" | "mini";

type ValidSizes = Exclude<ComponentSizes, "mini">;
// 结果: "large" | "default" | "small"

type NonFunction<T> = Exclude<T, Function>;
type T = NonFunction<string | number | (() => void)>;
// 结果: string | number

type AllActions =
  | "view"
  | "create"
  | "edit"
  | "delete"
  | "export"
  | "manage_users";
type AdminOnlyActions = "delete" | "manage_users";

// 普通用户可用的操作
type RegularUserActions = Exclude<AllActions, AdminOnlyActions>;
// 结果: "view" | "create" | "edit" | "export"

function checkPermission(action: RegularUserActions) {
  console.log("普通用户执行:", action);
}

type LegacyFeatures = "login" | "log_view" | "sentry_monitor" | "export_excel";
type NewFeatures = "login" | "export_excel" | "pdf_preview";

type CommonFeatures = Extract<LegacyFeatures, NewFeatures>;
// 结果: "login" | "export_excel"

type DOMEvents = keyof HTMLElementEventMap;
type MouseEventNames = Extract<DOMEvents, `mouse${string}`>;
// 结果: "mousedown" | "mouseenter" | "mouseleave" | "mousemove" | ...

function onMouseEvent(
  event: MouseEventNames,
  handler: (e: MouseEvent) => void,
) {
  document.addEventListener(event, handler as EventListener);
}

type SentryIssueId = string | number | null | undefined;

function resolveIssue(id: SentryIssueId) {
  if (id == null) return;
  const validId: NonNullable<SentryIssueId> = id;
  console.log("处理 issue:", validId);
}

type T0 = NonNullable<string | number | undefined>; // string | number
type T1 = NonNullable<string[] | null | undefined>; // string[]

function assertDefined<T>(val: T, name: string): NonNullable<T> {
  if (val == null) {
    throw new Error(`[断言失败] ${name} 不能为空`);
  }
  return val as NonNullable<T>;
}

const userId = assertDefined(localStorage.getItem("userId"), "userId");
// userId 类型为 string（去掉了 null）

function legacySubmit(data: { id: number; code: string }, force: boolean) {
  // ...
}

type LegacyParams = Parameters<typeof legacySubmit>;
// 结果: [data: { id: number; code: string }, force: boolean]

function myWrapper(...args: LegacyParams) {
  console.log("拦截记录:", args[0].code);
  return legacySubmit(...args);
}

function debounce<T extends (...args: any[]) => any>(
  fn: T,
  delay: number,
): (...args: Parameters<T>) => void {
  let timer: ReturnType<typeof setTimeout>;
  return (...args: Parameters<T>) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), delay);
  };
}

function handleSearch(keyword: string, page: number) {
  console.log("搜索:", keyword, page);
}

// debouncedSearch 保留了 (keyword: string, page: number) 的类型
const debouncedSearch = debounce(handleSearch, 300);
debouncedSearch("typescript", 1); // ✅ 类型安全

class MonitorService {
  constructor(
    public dsn: string,
    public maxBreadcrumbs: number,
  ) {}
}

type MonitorConfig = ConstructorParameters<typeof MonitorService>;
// 结果: [dsn: string, maxBreadcrumbs: number]

const config: MonitorConfig = ["https://sentry.io/dsn/xxx", 50];
const service = new MonitorService(...config);

function createInstance<T extends new (...args: any[]) => any>(
  Cls: T,
  ...args: ConstructorParameters<T>
): InstanceType<T> {
  return new Cls(...args);
}

class HttpClient {
  constructor(
    public baseUrl: string,
    public timeout: number,
    public withCredentials: boolean,
  ) {}
}

// 参数类型由 HttpClient 的构造函数自动推导
const client = createInstance(
  HttpClient,
  "https://api.example.com",
  5000,
  true,
);
client.baseUrl; // string ✅

function useDeviceState() {
  return {
    isMobile: false,
    screenWidth: 1920,
    orientation: "landscape" as "landscape" | "portrait",
  };
}

type DeviceState = ReturnType<typeof useDeviceState>;
// 结果: { isMobile: boolean; screenWidth: number; orientation: "landscape" | "portrait" }

function applyState(state: DeviceState) {
  if (!state.isMobile) {
    console.log("桌面端宽度:", state.screenWidth);
  }
}

function createUserStore() {
  return {
    list: [] as UserEntity[],
    loading: false,
    pagination: { page: 1, pageSize: 20, total: 0 },
  };
}

// 直接从 Store 工厂函数推导，无需再手写 UserStoreState 接口
type UserStoreState = ReturnType<typeof createUserStore>;
// { list: UserEntity[]; loading: boolean; pagination: { page: number; pageSize: number; total: number } }

function memoize<T extends (...args: any[]) => any>(
  fn: T,
): (...args: Parameters<T>) => ReturnType<T> {
  const cache = new Map<string, ReturnType<T>>();
  return (...args: Parameters<T>): ReturnType<T> => {
    const key = JSON.stringify(args);
    if (cache.has(key)) return cache.get(key)!;
    const result = fn(...args);
    cache.set(key, result);
    return result;
  };
}

const expensiveCalc = memoize((a: number, b: number) => a * b + Math.random());
expensiveCalc(2, 3); // 计算并缓存
expensiveCalc(2, 3); // 直接返回缓存，类型为 number ✅

<!-- IipForm.vue（子组件）-->
<script setup lang="ts">
const validate = async (): Promise<boolean> => {
  return true;
};
const reset = (): void => {
  /* 重置 */
};
defineExpose({ validate, reset });
</script>

<!-- 父组件 -->
<script setup lang="ts">
import { ref } from "vue";
import IipForm from "./IipForm.vue";

const formRef = ref<InstanceType<typeof IipForm> | null>(null);

const onSubmit = async () => {
  if (!formRef.value) return;
  const isValid = await formRef.value.validate();
  if (isValid) formRef.value.reset();
};
</script>

// 不使用 NoInfer：defaultColor 污染推断，"blue" 不报错
function createStreetLightBad<C extends string>(
  colors: C[],
  defaultColor?: C,
) {}
createStreetLightBad(["red", "yellow", "green"], "blue");
// ❌ 不报错！TS 把 C 推断为 "red" | "yellow" | "green" | "blue"

// 使用 NoInfer：defaultColor 不参与推断，强制只能传 colors 中的值
function createStreetLight<C extends string>(
  colors: C[],
  defaultColor?: NoInfer<C>,
) {}
createStreetLight(["red", "yellow", "green"], "red"); // ✅ OK
createStreetLight(["red", "yellow", "green"], "blue"); // ❌ 报错

const messages = {
  welcome: "欢迎",
  goodbye: "再见",
  error: "出错了",
} as const;

type MessageKey = keyof typeof messages;

function t<K extends MessageKey>(key: K, fallback?: NoInfer<K>): string {
  return messages[key] ?? (fallback ? messages[fallback] : "");
}

t("welcome"); // ✅
t("welcome", "goodbye"); // ✅ fallback 也是合法的 key
t("welcome", "unknown"); // ❌ 报错，"unknown" 不是 MessageKey

function toHex(this: Number) {
  return this.toString(16);
}

type HexThis = ThisParameterType<typeof toHex>;
// 结果: Number

function numberToString(n: HexThis) {
  return toHex.apply(n);
}

const mixin = {
  data() {
    return { count: 0 };
  },
  methods: {
    increment(this: { count: number }) {
      this.count++;
    },
  },
};

type IncrementThis = ThisParameterType<typeof mixin.methods.increment>;
// 结果: { count: number }

function toHex(this: Number) {
  return this.toString(16);
}

const fiveToHex: OmitThisParameter<typeof toHex> = toHex.bind(5);
console.log(fiveToHex()); // "5"

class Formatter {
  prefix = "[LOG]";

  format(this: Formatter, msg: string) {
    return `${this.prefix} ${msg}`;
  }
}

const formatter = new Formatter();

// 绑定 this 后，类型中的 this 约束消除，可以安全地传递给第三方 API
const boundFormat: OmitThisParameter<typeof formatter.format> =
  formatter.format.bind(formatter);

["err", "warn", "info"].map(boundFormat); // ✅

type ObjectDescriptor<D, M> = {
  data?: D;
  methods?: M & ThisType<D & M>;
};

function makeObject<D, M>(desc: ObjectDescriptor<D, M>): D & M {
  const data: object = desc.data || {};
  const methods: object = desc.methods || {};
  return { ...data, ...methods } as D & M;
}

const obj = makeObject({
  data: { x: 0, y: 0 },
  methods: {
    moveBy(dx: number, dy: number) {
      this.x += dx; // ✅ 强类型 this
      this.y += dy;
    },
  },
});

obj.x = 10;
obj.moveBy(5, 5);

type A = Awaited<Promise<string>>; // string
type B = Awaited<Promise<Promise<number>>>; // number（递归解包）
type C = Awaited<boolean | Promise<number>>; // boolean | number

interface PageResult<T> {
  records: T[];
  total: number;
}
interface TenantData {
  id: string;
  name: string;
}

async function fetchTenants(): Promise<PageResult<TenantData>> {
  return { records: [{ id: "1", name: "华东区" }], total: 1 };
}

type FetchResult = Awaited<ReturnType<typeof fetchTenants>>;
// 结果: PageResult<TenantData>（Promise 被解包）

function renderList(data: FetchResult) {
  console.log(`共 ${data.total} 条`, data.records);
}

async function getUserAndOrders(userId: string) {
  const [user, orders] = await Promise.all([
    fetchUser(userId), // Promise<UserEntity>
    fetchOrders(userId), // Promise<OrderEntity[]>
  ]);
  // user: UserEntity，orders: OrderEntity[] — 自动解包 ✅
  return { user, orders };
}

// 推导并联结两个异步结果的类型
type DashboardData = Awaited<ReturnType<typeof getUserAndOrders>>;
// { user: UserEntity; orders: OrderEntity[] }

type Environment = "dev" | "test" | "prod";
type EnvConst = `VITE_APP_ENV_${Uppercase<Environment>}`;
// 结果: "VITE_APP_ENV_DEV" | "VITE_APP_ENV_TEST" | "VITE_APP_ENV_PROD"

type BuildEnv = "Dev" | "Test" | "Prod";
type OutDir = `dist/${Lowercase<BuildEnv>}`;
// 结果: "dist/dev" | "dist/test" | "dist/prod"

type ModelKeys = "visible" | "title" | "content";
type EmitEvents = `onUpdate${Capitalize<ModelKeys>}`;
// 结果: "onUpdateVisible" | "onUpdateTitle" | "onUpdateContent"

type ComponentName = "Button" | "Input" | "Select";
type CssClass = `iip-${Uncapitalize<ComponentName>}`;
// 结果: "iip-button" | "iip-input" | "iip-select"

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type Setters<T> = {
  [K in keyof T as `set${Capitalize<string & K>}`]: (value: T[K]) => void;
};

interface UserStore {
  name: string;
  age: number;
  isAdmin: boolean;
}

type UserGetters = Getters<UserStore>;
// {
//   getName: () => string;
//   getAge: () => number;
//   getIsAdmin: () => boolean;
// }

type UserSetters = Setters<UserStore>;
// {
//   setName: (value: string) => void;
//   setAge: (value: number) => void;
//   setIsAdmin: (value: boolean) => void;
// }

type UserStoreInterface = UserStore & UserGetters & UserSetters;

type DesignToken = "primary" | "secondary" | "danger" | "warning";

// CSS 变量名：--color-primary, --color-secondary ...
type CssVarName = `--color-${DesignToken}`;

// 对应的 JS 变量名（驼峰）：colorPrimary, colorSecondary ...
type JsVarName = `color${Capitalize<DesignToken>}`;

const tokenMap: Record<JsVarName, CssVarName> = {
  colorPrimary: "--color-primary",
  colorSecondary: "--color-secondary",
  colorDanger: "--color-danger",
  colorWarning: "--color-warning",
};