> ## Documentation Index
> Fetch the complete documentation index at: https://fluxon.tabooproject.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Map 扩展函数

> 映射操作、键值访问、遍历等扩展方法

Map 扩展函数通过上下文调用语法 `::` 使用，提供键值对集合操作能力。

## 基础属性

| 方法          | 说明           |
| ----------- | ------------ |
| `size()`    | 返回映射中键值对的数量。 |
| `isEmpty()` | 检查映射是否为空。    |

```fluxon theme={null}
[a: 1, b: 2] :: size()      # => 2
[:] :: isEmpty()            # => true（空映射）
[a: 1] :: isEmpty()         # => false
```

## 键值访问

| 方法                           | 说明                    |
| ---------------------------- | --------------------- |
| `get(key)`                   | 获取指定键的值，不存在返回 `null`。 |
| `getOrDefault(key, default)` | 获取值，不存在则返回默认值。        |
| `keys()`                     | 返回所有键的集合。             |
| `values()`                   | 返回所有值的集合。             |
| `entries()`                  | 返回所有键值对的集合。           |

```fluxon theme={null}
map = [name: "Alice", age: 30]

map :: get("name")                  # => "Alice"
map :: get("email")                 # => null
map :: getOrDefault("email", "N/A") # => "N/A"
map :: keys()                       # => ["name", "age"]
map :: values()                     # => ["Alice", 30]
```

也可以使用索引访问语法：

```fluxon theme={null}
map = [a: 1, b: 2]
&map["a"]                   # => 1
&map["c"]                   # => null
```

## 元素修改（可变映射）

以下方法仅适用于可变映射：

| 方法                 | 说明                 |
| ------------------ | ------------------ |
| `put(key, value)`  | 添加或更新键值对，返回旧值（如有）。 |
| `putAll(otherMap)` | 批量添加键值对。           |
| `remove(key)`      | 移除指定键，返回被移除的值。     |
| `clear()`          | 清空映射。              |

```fluxon theme={null}
map = mutableMap([a: 1])
map :: put("b", 2)          # map = [a: 1, b: 2]
map :: put("a", 10)         # => 1（返回旧值），map = [a: 10, b: 2]
map :: remove("b")          # => 2, map = [a: 10]
map :: clear()              # map = [:]
```

## 包含检查

| 方法                     | 说明         |
| ---------------------- | ---------- |
| `containsKey(key)`     | 检查是否包含指定键。 |
| `containsValue(value)` | 检查是否包含指定值。 |

```fluxon theme={null}
map = [a: 1, b: 2]
map :: containsKey("a")     # => true
map :: containsKey("c")     # => false
map :: containsValue(1)     # => true
map :: containsValue(3)     # => false
```

## 遍历与转换

| 方法                        | 说明                |
| ------------------------- | ----------------- |
| `forEach(action)`         | 对每个键值对执行操作。       |
| `map(transform)`          | 转换每个值，返回新映射。      |
| `mapKeys(transform)`      | 转换每个键，返回新映射。      |
| `filter(predicate)`       | 过滤键值对，返回满足条件的新映射。 |
| `filterKeys(predicate)`   | 按键过滤。             |
| `filterValues(predicate)` | 按值过滤。             |

```fluxon theme={null}
map = [a: 1, b: 2, c: 3]

# forEach 遍历
map :: forEach(fn(k, v) { print(&k + ": " + &v) })

# map 转换值
map :: map(fn(k, v) { &v * 2 })         # => [a: 2, b: 4, c: 6]

# filter 过滤
map :: filter(fn(k, v) { &v > 1 })      # => [b: 2, c: 3]
map :: filterValues(fn(v) { &v > 1 })   # => [b: 2, c: 3]
```

## 使用 for 循环遍历

映射可以直接用 `for` 循环遍历：

```fluxon theme={null}
map = [name: "Alice", age: 30]

# 遍历键值对
for (key, value) in &map {
    print(&key + " = " + &value)
}

# 只遍历键
for key in map :: keys() {
    print(&key)
}

# 只遍历值
for value in map :: values() {
    print(&value)
}
```

## 合并与转换

| 方法               | 说明                    |
| ---------------- | --------------------- |
| `plus(otherMap)` | 合并两个映射，返回新映射（后者覆盖前者）。 |
| `minus(key)`     | 返回移除指定键后的新映射。         |
| `minus(keys)`    | 返回移除多个键后的新映射。         |
| `toList()`       | 转换为键值对列表。             |

```fluxon theme={null}
map1 = [a: 1, b: 2]
map2 = [b: 20, c: 3]

map1 :: plus(&map2)         # => [a: 1, b: 20, c: 3]
map1 :: minus("a")          # => [b: 2]
map1 :: minus(["a", "b"])   # => [:]
map1 :: toList()            # => [["a", 1], ["b", 2]]
```

## 默认值

| 方法                            | 说明                       |
| ----------------------------- | ------------------------ |
| `getOrPut(key, defaultValue)` | 获取值，不存在则添加默认值并返回（仅可变映射）。 |

```fluxon theme={null}
map = mutableMap([a: 1])
map :: getOrPut("a", 10)    # => 1（已存在）
map :: getOrPut("b", 2)     # => 2（新添加）
# map = [a: 1, b: 2]
```

## 相关链接

* [String 扩展函数](/language/extensions/string)
* [List 扩展函数](/language/extensions/list)
* [控制流（循环）](/language/control-flow#循环)
* [字面量与类型](/language/literals-and-types)