<commit_before>---
type: doc
layout: reference
category: "Syntax"
title: "属性与字段：Getters、Setters、const、lateinit"
---

# 属性与字段

## 声明属性

Kotlin 类中的属性既可以用关键字 *var*{: .keyword } 声明为可变的，也可以用关键字 *val*{: .keyword } 声明为只读的。

<div class="sample" markdown="1" theme="idea" data-highlight-only>

```kotlin
class Address {
    var name: String = "<NAME>"
    var street: String = "Baker"
    var city: String = "London"
    var state: String? = null
    var zip: String = "123456"
}
```
</div>

要使用一个属性，只要用名称引用它即可：

<div class="sample" markdown="1" theme="idea" data-highlight-only>

```kotlin
fun copyAddress(address: Address): Address {
    val result = Address() // Kotlin 中没有“new”关键字
    result.name = address.name // 将调用访问器
    result.street = address.street
    // ……
    return result
}
```
</div>

## Getters 与 Setters

声明一个属性的完整语法是

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var <propertyName>[: <PropertyType>] [= <property_initializer>]
    [<getter>]
    [<setter>]
```
</div>

其初始器（initializer）、getter 和 setter 都是可选的。属性类型如果可以从初始器
（或者从其 getter 返回值，如下文所示）中推断出来，也可以省略。

例如:

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var allByDefault: Int? // 错误：需要显式初始化器，隐含默认 getter 和 setter
var initialized = 1 // 类型 Int、默认 getter 和 setter
```
</div>

一个只读属性的语法和一个可变的属性的语法有两方面的不同：1、只读属性的用 `val`开始代替`var` 2、只读属性不允许 setter

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
val simple: Int? // 类型 Int、默认 getter、必须在构造函数中初始化
val inferredType = 1 // 类型 Int 、默认 getter
```
</div>

我们可以为属性定义自定义的访问器。如果我们定义了一个自定义的 getter，那么每次访问该属性时都会调用它
（这让我们可以实现计算出的属性）。以下是一个自定义 getter 的示例：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
val isEmpty: Boolean
    get() = this.size == 0
```
</div>

如果我们定义了一个自定义的 setter，那么每次给属性赋值时都会调用它。一个自定义的 setter 如下所示：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var stringRepresentation: String
    get() = this.toString()
    set(value) {
        setDataFromString(value) // 解析字符串并赋值给其他属性
    }
```
</div>

按照惯例，setter 参数的名称是 `value`，但是如果你喜欢你可以选择一个不同的名称。

自 Kotlin 1.1 起，如果可以从 getter 推断出属性类型，则可以省略它：

<div class="sample" markdown="1" theme="idea" data-highlight-only>

```kotlin
val isEmpty get() = this.size == 0  // 具有类型 Boolean
```
</div>

如果你需要改变一个访问器的可见性或者对其注解，但是不需要改变默认的实现，
你可以定义访问器而不定义其实现:

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var setterVisibility: String = "abc"
    private set // 此 setter 是私有的并且有默认实现

var setterWithAnnotation: Any? = null
    @Inject set // 用 Inject 注解此 setter
```
</div>

### 幕后字段

在 Kotlin 类中不能直接声明字段。然而，当一个属性需要一个幕后字段时，Kotlin 会自动提供。这个幕后字段可以使用`field`标识符在访问器中引用：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var counter = 0 // 注意：这个初始器直接为幕后字段赋值
    set(value) {
        if (value >= 0) field = value
    }
```
</div>

`field` 标识符只能用在属性的访问器内。

如果属性至少一个访问器使用默认实现，或者自定义访问器通过 `field` 引用幕后字段，将会为该属性生成一个幕后字段。

例如，下面的情况下， 就没有幕后字段：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
val isEmpty: Boolean
    get() = this.size == 0
```
</div>

### 幕后属性

如果你的需求不符合这套“隐式的幕后字段”方案，那么总可以使用 *幕后属性（backing property）*：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
private var _table: Map<String, Int>? = null
public val table: Map<String, Int>
    get() {
        if (_table == null) {
            _table = HashMap() // 类型参数已推断出
        }
        return _table ?: throw AssertionError("Set to null by another thread")
    }
```
</div>

> **对于 JVM 平台**：通过默认 getter 和 setter 访问私有属性会被优化，
所以本例不会引入函数调用开销。


## 编译期常量

If the value of a read-only property is known at the compile time, mark it as a _compile time constant_ using the *const*{: .keyword } modifier.
这种属性需要满足以下要求：

  * 位于顶层或者是 [*object*{: .keyword } 声明](object-declarations.html#对象声明) 或 [*companion object*{: .keyword }](object-declarations.html#伴生对象) 的一个成员
  * 以 `String` 或原生类型值初始化
  * 没有自定义 getter

这些属性可以用在注解中：

<div class="sample" markdown="1" theme="idea" data-highlight-only>
<commit_msg>补充《属性与字段》翻译<commit_after>---
type: doc
layout: reference
category: "Syntax"
title: "属性与字段：Getters、Setters、const、lateinit"
---

# 属性与字段

## 声明属性

Kotlin 类中的属性既可以用关键字 *var*{: .keyword } 声明为可变的，也可以用关键字 *val*{: .keyword } 声明为只读的。

<div class="sample" markdown="1" theme="idea" data-highlight-only>

```kotlin
class Address {
    var name: String = "<NAME>"
    var street: String = "Baker"
    var city: String = "London"
    var state: String? = null
    var zip: String = "123456"
}
```
</div>

要使用一个属性，只要用名称引用它即可：

<div class="sample" markdown="1" theme="idea" data-highlight-only>

```kotlin
fun copyAddress(address: Address): Address {
    val result = Address() // Kotlin 中没有“new”关键字
    result.name = address.name // 将调用访问器
    result.street = address.street
    // ……
    return result
}
```
</div>

## Getters 与 Setters

声明一个属性的完整语法是

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var <propertyName>[: <PropertyType>] [= <property_initializer>]
    [<getter>]
    [<setter>]
```
</div>

其初始器（initializer）、getter 和 setter 都是可选的。属性类型如果可以从初始器
（或者从其 getter 返回值，如下文所示）中推断出来，也可以省略。

例如:

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var allByDefault: Int? // 错误：需要显式初始化器，隐含默认 getter 和 setter
var initialized = 1 // 类型 Int、默认 getter 和 setter
```
</div>

一个只读属性的语法和一个可变的属性的语法有两方面的不同：1、只读属性的用 `val`开始代替`var` 2、只读属性不允许 setter

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
val simple: Int? // 类型 Int、默认 getter、必须在构造函数中初始化
val inferredType = 1 // 类型 Int 、默认 getter
```
</div>

我们可以为属性定义自定义的访问器。如果我们定义了一个自定义的 getter，那么每次访问该属性时都会调用它
（这让我们可以实现计算出的属性）。以下是一个自定义 getter 的示例：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
val isEmpty: Boolean
    get() = this.size == 0
```
</div>

如果我们定义了一个自定义的 setter，那么每次给属性赋值时都会调用它。一个自定义的 setter 如下所示：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var stringRepresentation: String
    get() = this.toString()
    set(value) {
        setDataFromString(value) // 解析字符串并赋值给其他属性
    }
```
</div>

按照惯例，setter 参数的名称是 `value`，但是如果你喜欢你可以选择一个不同的名称。

自 Kotlin 1.1 起，如果可以从 getter 推断出属性类型，则可以省略它：

<div class="sample" markdown="1" theme="idea" data-highlight-only>

```kotlin
val isEmpty get() = this.size == 0  // 具有类型 Boolean
```
</div>

如果你需要改变一个访问器的可见性或者对其注解，但是不需要改变默认的实现，
你可以定义访问器而不定义其实现:

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var setterVisibility: String = "abc"
    private set // 此 setter 是私有的并且有默认实现

var setterWithAnnotation: Any? = null
    @Inject set // 用 Inject 注解此 setter
```
</div>

### 幕后字段

在 Kotlin 类中不能直接声明字段。然而，当一个属性需要一个幕后字段时，Kotlin 会自动提供。这个幕后字段可以使用`field`标识符在访问器中引用：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
var counter = 0 // 注意：这个初始器直接为幕后字段赋值
    set(value) {
        if (value >= 0) field = value
    }
```
</div>

`field` 标识符只能用在属性的访问器内。

如果属性至少一个访问器使用默认实现，或者自定义访问器通过 `field` 引用幕后字段，将会为该属性生成一个幕后字段。

例如，下面的情况下， 就没有幕后字段：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
val isEmpty: Boolean
    get() = this.size == 0
```
</div>

### 幕后属性

如果你的需求不符合这套“隐式的幕后字段”方案，那么总可以使用 *幕后属性（backing property）*：

<div class="sample" markdown="1" theme="idea" data-highlight-only auto-indent="false">

```kotlin
private var _table: Map<String, Int>? = null
public val table: Map<String, Int>
    get() {
        if (_table == null) {
            _table = HashMap() // 类型参数已推断出
        }
        return _table ?: throw AssertionError("Set to null by another thread")
    }
```
</div>

> **对于 JVM 平台**：通过默认 getter 和 setter 访问私有属性会被优化，
所以本例不会引入函数调用开销。


## 编译期常量

如果只读属性的值在编译期是已知的，那么可以使用 *const*{: .keyword } 修饰符将其标记为*编译期常量*。
这种属性需要满足以下要求：

  * 位于顶层或者是 [*object*{: .keyword } 声明](object-declarations.html#对象声明) 或 [*companion object*{: .keyword }](object-declarations.html#伴生对象) 的一个成员
  * 以 `String` 或原生类型值初始化
  * 没有自定义 getter

这些属性可以用在注解中：

<div class="sample" markdown="1" theme="idea" data-highlight-only>

{'fraction_non_alphanumeric': 0.15693039857227842, 'fraction_numerical': 0.007138607971445568, 'mean_word_length': 4.6189839572192515, 'pattern_counts': {'":': 0, '<': 69, '<?xml version=': 0, '>': 73, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7640195', 'n_tokens_mistral': 4189, 'n_tokens_neox': 4356, 'n_words': 733}