扩展

Kotlin 提供了向一个类或一个接口扩展新功能的能力, 而且不必从这个类继承, 也不必使用装饰器(Decorator) 之类的设计模式. 这种功能是通过一种特殊的声明来实现的, Kotlin 中称为扩展(extension).

比如, 你无法修改第三方库中的一个类或一个接口, 但你可以为它编写新的函数. 这些函数可以象原来的类的方法那样调用. 这种机制称为扩展函数(extension function). 此外还有扩展属性(extension property), 你可以用来向已有的类添加新的属性.

扩展函数(Extension Function)

要声明一个扩展函数, 需要在函数名之前添加前缀, 表示这个函数的接收者类型(receiver type), 也就是我们希望扩展的对象类型. 以下示例将为 MutableList<Int> 类型添加一个 swap 函数:

fun MutableList<Int>.swap(index1: Int, index2: Int) {
    val tmp = this[index1] // 'this' 指代 list 实例
    this[index1] = this[index2]
    this[index2] = tmp
}

在扩展函数内, this 关键字指代接收者对象(receiver object)(也就是调用扩展函数时, 在点号之前指定的对象实例). 现在, 你可以对任意一个 MutableList<Int> 对象调用这个扩展函数:

val list = mutableListOf(1, 2, 3)
list.swap(0, 2) // 'swap()' 函数内的 'this' 将指向 'list' 的值

这个函数可以适用与任意元素类型的 MutableList<T>, 因此你可以使用泛型, 将它的元素类型泛化:

fun <T> MutableList<T>.swap(index1: Int, index2: Int) {
    val tmp = this[index1] // 'this' 指代 list 实例
    this[index1] = this[index2]
    this[index2] = tmp
}

你需要在函数名之前声明泛型的类型参数, 然后在接收者类型表达式中就可以使用泛型了. 关于泛型的更多详情, 请参见泛型函数.

扩展函数的解析是静态的

扩展函数并不会真正修改它所扩展的类. 定义扩展函数时, 并没有向类中插入新的成员方法, 而只是创建了一个新的函数, 并且可以通过点号标记法的形式, 对这个数据类型的变量调用这个新函数.

扩展函数的调用派发过程是静态的. 因此, 被调用的是哪个扩展函数, 是在编译期间通过接受者的类型决定的. 比如:

fun main() {
//sampleStart
    open class Shape
    class Rectangle: Shape()

    fun Shape.getName() = "Shape"
    fun Rectangle.getName() = "Rectangle"

    fun printClassName(s: Shape) {
        println(s.getName())
    }

    printClassName(Rectangle())
//sampleEnd
}

这段示例程序的打印结果将是 Shape, 因为调用哪个函数, 仅仅是由参数 s 声明的类型决定, 这里参数 s 的类型为 Shape 类.

如果类中存在成员函数, 同时又在同一个类上定义了同名的扩展函数, 并且与调用时指定的参数匹配, 这种情况下成员函数总是会优先使用. 比如:

fun main() {
//sampleStart
    class Example {
        fun printFunctionType() { println("Class method") }
    }

    fun Example.printFunctionType(i: Int) { println("Extension function #$i") }

    Example().printFunctionType(1)
//sampleEnd
}

这段代码的输出将是 Class method.

但是, 我们完全可以使用同名称但不同参数的扩展函数, 来重载(overload)成员函数:

fun main() {
//sampleStart
    class Example {
        fun printFunctionType() { println("Class method") }
    }

    fun Example.printFunctionType(i: Int) { println("Extension function") }

    Example().printFunctionType(1)
//sampleEnd
}

可为空的接收者(Nullable Receiver)

注意, 对可以为空的接收者类型也可以定义扩展. 这样的扩展函数, 即使在对象变量值为 null 时也可以调用. 如果接受者为 null, 那么 this 也是 null. 因此, 在对可为 null 的接收者类型定义扩展时, 我们建议在函数体之内进行 this == null 检查, 以避免编译错误.

你可以在 Kotlin 中调用 toString() 函数, 而不必检查对象是否为 null, 因为在扩展函数内部已经进行了对象是否为 null 的检查.

fun Any?.toString(): String {
    if (this == null) return "null"
    // 进行过 null 检查后, 'this' 会被自动转换为非 null 类型, 因此下面的 toString() 方法
    // 会被解析为 Any 类的成员函数
    return toString()
}

扩展属性(Extension Property)

Kotlin 也支持扩展属性, 与扩展函数类似:

val <T> List<T>.lastIndex: Int
    get() = size - 1

示例:

val House.number = 1 // 错误: 扩展属性不允许存在初始化器

对同伴对象(Companion Object)的扩展

如果一个类定义了同伴对象, 你可以对这个同伴对象定义扩展函数和扩展属性. 与同伴对象的常规成员一样, 可以只使用类名限定符来调用这些扩展函数和扩展属性:

class MyClass {
    companion object { }  // 通过 "Companion" 来引用这个同伴对象
}

fun MyClass.Companion.printCompanion() { println("companion") }

fun main() {
    MyClass.printCompanion()
}

扩展的范围

大多数情况下, 你可以直接在包之下的顶级位置定义扩展:

package org.example.declarations

fun List<String>.getLongestString() { /*...*/}

要在这个包之外使用扩展, 需要在调用处 import 这个扩展:

package org.example.usage

import org.example.declarations.getLongestString

fun main() {
    val list = listOf("red", "green", "blue")
    list.getLongestString()
}

详情请参见导入.

将扩展定义为成员

你可以在一个类的内部为另一个类定义扩展. 在这类扩展中, 存在多个隐含接受者(implicit receiver) - 这些隐含接收者的成员可以不使用限定符直接访问. 扩展方法的定义所在的类的实例, 称为派发接受者(dispatch receiver), 扩展方法的目标类型的实例, 称为扩展接受者(extension receiver).

class Host(val hostname: String) {
    fun printHostname() { print(hostname) }
}

class Connection(val host: Host, val port: Int) {
    fun printPort() { print(port) }

    fun Host.printConnectionString() {
        printHostname()   // 这里会调用 Host.printHostname()
        print(":")
        printPort()   // 这里会调用 Connection.printPort()
    }

    fun connect() {
        /*...*/
        host.printConnectionString()   // 这里会调用扩展函数
    }
}

fun main() {
    Connection(Host("kotl.in"), 443).connect()
    //Host("kotl.in").printConnectionString()  // 错误, 在 Connection 之外无法访问扩展函数
}

当派发接受者与扩展接受者的成员名称发生冲突时, 扩展接受者的成员将会被优先使用. 如果想要使用派发接受者的成员, 请参见带限定符的 this 语法.

class Connection {
    fun Host.getConnectionString() {
        toString()         // 这里会调用 Host.toString()
        this@Connection.toString()  // 这里会调用 Connection.toString()
    }
}

以成员的形式定义的扩展函数, 可以声明为 open, 而且可以在子类中覆盖. 也就是说, 在这类扩展函数的派发过程中, 针对派发接受者是虚拟的(virtual), 但针对扩展接受者仍然是静态的(static).

open class Base { }

class Derived : Base() { }

open class BaseCaller {
    open fun Base.printFunctionInfo() {
        println("Base extension function in BaseCaller")
    }

    open fun Derived.printFunctionInfo() {
        println("Derived extension function in BaseCaller")
    }

    fun call(b: Base) {
        b.printFunctionInfo()   // 这里会调用扩展函数
    }
}

class DerivedCaller: BaseCaller() {
    override fun Base.printFunctionInfo() {
        println("Base extension function in DerivedCaller")
    }

    override fun Derived.printFunctionInfo() {
        println("Derived extension function in DerivedCaller")
    }
}

fun main() {
    BaseCaller().call(Base())   // 输出结果为 "Base extension function in BaseCaller"
    DerivedCaller().call(Base())  // 输出结果为 "Base extension function in DerivedCaller" - 派发接受者的解析过程是虚拟的
    DerivedCaller().call(Derived())  // 输出结果为 "Base extension function in DerivedCaller" - 扩展接受者的解析过程是静态的
}

关于可见度的注意事项

扩展函数或扩展属性对其他元素的可见度规则, 与定义在同一范围内的普通函数相同. 比如:

定义在源代码文件顶级(top-level)范围内的扩展, 可以访问同一源代码文件内的其他顶级 private 元素.
如果扩展定义在它的接受者类型的外部, 那么它不能访问接受者的 private 或 protected 成员.

最终更新: 2024/12/17