TypeScript 索引签名类型在动态键值对中的应用

当你需要处理对象的键不是预先确定、而是运行时动态生成的情况（比如从用户输入、API 响应或配置文件中读取），TypeScript 的索引签名（Index Signature）类型就能派上用场。它允许你定义一个对象，其属性名可以是任意字符串（或数字），而值具有统一类型。

1. 定义基本的索引签名类型

创建一个接口或类型别名，使用 [key: string]: Type 语法来声明所有字符串键对应的值类型。

interface UserPreferences {
  [key: string]: string | number;
}

上面的代码表示：UserPreferences 类型的对象可以拥有任意数量的属性，每个属性的键是字符串，值只能是 string 或 number。

注意：索引签名中的 key 只是一个占位符名称，你可以写成 [prop: string] 或 [field: string]，效果完全一样。

2. 使用索引签名处理动态数据

假设你从后端获取一组用户自定义设置，键名未知但值都是字符串：

function processSettings(settings: { [key: string]: string }) {
  for (const key in settings) {
    console.log(`${key}: ${settings[key]}`);
  }
}

// 调用示例
processSettings({
  theme: "dark",
  language: "zh-CN",
  notifications: "enabled"
});

确保传入的对象满足索引签名约束——所有值必须是 string。如果混入其他类型（如布尔值），TypeScript 会报错。

3. 混合已知属性与动态属性

很多时候，对象既有固定结构的字段，又有动态扩展的字段。这时可以将具体属性与索引签名组合使用。

interface Config {
  version: string;           // 固定属性
  debug: boolean;            // 固定属性
  [pluginName: string]: unknown; // 动态插件配置
}

关键点：索引签名的值类型必须是固定属性值类型的超集。例如，version 是 string，debug 是 boolean，所以索引签名的值类型至少要是 string | boolean | ...。使用 unknown 是一种安全做法，后续可通过类型守卫细化。

访问动态属性时，需自行验证类型：

function getPluginConfig(config: Config, name: string): unknown {
  return config[name];
}

4. 使用数字索引签名（较少见）

如果你的对象键是数字（例如数组-like 结构，但又不是标准数组），可以用数字索引签名：

interface NumericMap {
  [index: number]: string;
}

注意：JavaScript 对象的键本质上都是字符串，即使你写 obj[0]，实际存储的是 "0"。因此，数字索引签名主要用于语义清晰或与数组交互的场景。

5. 避免常见陷阱

错误：索引签名与具体属性类型冲突

// ❌ 错误示例
interface BadExample {
  name: string;
  [key: string]: number; // 报错！'name' 的类型 'string' 不符合索引签名要求的 'number'
}

解决方法：让索引签名的值类型包含所有具体属性的类型：

// ✅ 正确做法
interface GoodExample {
  name: string;
  count: number;
  [key: string]: string | number;
}

错误：过度宽泛导致类型安全丧失

// ❌ 危险做法
const data: { [key: string]: any } = {};

建议：尽量避免 any。如果不确定值类型，优先使用 unknown，并在使用前做类型检查。

6. 实战：构建动态表单验证规则

假设你要为表单字段动态添加验证规则，字段名未知，但每条规则是一个函数：

type Validator = (value: string) => boolean;

interface ValidationRules {
  [fieldName: string]: Validator;
}

const rules: ValidationRules = {
  email: (val) => val.includes("@"),
  password: (val) => val.length >= 8,
  // 可随时添加新字段规则
};

function validateField(fieldName: string, value: string, rules: ValidationRules): boolean {
  const validator = rules[fieldName];
  if (validator) {
    return validator(value);
  }
  return true; // 无规则视为通过
}

调用 validateField("email", "user@example.com", rules) 即可验证。

7. 与 Record 工具类型的对比

TypeScript 提供了内置工具类型 Record<Keys, Type>，常用于类似场景：

type UserPrefs = Record<string, string | number>;

这等价于：

interface UserPrefs {
  [key: string]: string | number;
}

选择建议：

• 如果只需要纯动态键值对，用 Record<string, T> 更简洁。
• 如果需要混合固定属性和动态属性，必须使用索引签名语法。

8. 处理嵌套动态对象

当值本身也是动态对象时，可递归使用索引签名：

interface NestedConfig {
  [key: string]: string | NestedConfig;
}

示例数据：

const config: NestedConfig = {
  server: {
    host: "localhost",
    port: "3000"
  },
  db: {
    url: "mongodb://..."
  }
};

注意：这种结构在访问深层属性时需谨慎，建议配合可选链操作符（?.）使用。

9. 限制动态键的范围（进阶）

如果动态键不是任意字符串，而是来自一个联合类型，应优先使用映射类型而非索引签名：

type Theme = "light" | "dark" | "auto";

// ✅ 推荐：明确键的范围
type ThemeSettings = {
  [K in Theme]: { primaryColor: string };
};

// ❌ 不推荐：失去键的约束
interface LooseThemeSettings {
  [key: string]: { primaryColor: string };
}

前者能确保只有 light、dark、auto 三个键可用，后者允许任意字符串键，容易引入拼写错误。

10. 编译选项影响

确认你的 tsconfig.json 中未启用过于严格的选项导致索引签名失效。通常默认配置即可支持。若遇到意外错误，检查是否启用了 noPropertyAccessFromIndexSignature（TypeScript 4.2+）：

{
  "compilerOptions": {
    "noPropertyAccessFromIndexSignature": false
  }
}

启用该选项后，通过点号访问动态属性（如 obj.key）会报错，必须使用方括号（obj["key"]）。建议始终使用方括号访问动态键，以保持一致性。