与 Swift/Objective-C 代码交互

对 Objective-C 和 Swift 隐藏 Kotlin 声明

warning

@HiddenFromObjC 注解是 实验性功能, 需要 使用者同意(Opt-in).

要让你的 Kotlin 代码更加易于在 Objective-C/Swift 中使用, 你可以使用 @HiddenFromObjC, 对 Objective-C 和 Swift 隐藏一些 Kotlin 声明. 这个注解会禁止一个函数或属性导出到 Objective-C.

或者, 你可以使用 internal 修饰符标记 Kotlin 声明, 将它的可见度限定在编译模块之内. 如果你只希望对 Objective-C 和 Swift 隐藏 Kotlin 声明, 但让它对其他 Kotlin 模块继续保持可见, 那么请选择 @HiddenFromObjC.

参见 Kotlin-Swift interopedia 中的示例.

在 Swift 中使用润色(Refine)

warning

@ShouldRefineInSwift 注解是 实验性功能, 需要 使用者同意(Opt-in).

@ShouldRefineInSwift 可以将一个 Kotlin 声明替换为 Swift 编写的一个封装(Wrapper). 这个注解会在生成的 Objective-C API 中, 将一个函数或属性标记为 swift_private. 这样的声明会带有 __ 前缀, 使得它们在 Swift 中不可见.

你仍然可以在 Swift 代码中使用这些声明, 来创建 Swift 友好的 API, 但在 Xcode 的代码自动完成功能中, 不会显示这些声明.

• 关于如何在 Swift 中润色(Refine) Objective-C 声明, 详情请参见 Apple 官方文档.

• 关于使用 @ShouldRefineInSwift 注解的示例, 请参见 Kotlin-Swift interopedia.

修改声明的名称

warning

@ObjCName 注解是 实验性功能, 需要 使用者同意(Opt-in).

如果要避免对 Kotlin 声明的重新命名, 请使用 @ObjCName 注解. 这个注解会指示 Kotlin 编译器对标注了注解的类, 接口, 以及其他 Kotlin 元素使用自定义的 Objective-C 和 Swift 名称:

@ObjCName(swiftName = "MySwiftArray")
class MyKotlinArray {
    @ObjCName("index")
    fun indexOf(@ObjCName("of") element: String): Int = TODO()
}

// ObjCName 注解的使用示例
let array = MySwiftArray()
let index = array.index(of: "element")

参见 Kotlin-Swift interopedia 的示例.

使用 KDoc 注释提供文档

要理解任何 API, 文档是必须的. 为共用的 Kotlin API 提供文档, 可以让你与 API 使用者更好的沟通, 例如使用时的注意实现, 应该做什么, 不应该做什么, 等等.

默认情况下, 在生成 Objective-C 头文件时, KDocs 注释不会被翻译为头文件中对应的注释. 例如, 以下带 KDoc 文档的 Kotlin 代码:

/**
 * Prints the sum of the arguments.
 * Properly handles the case when the sum doesn't fit in 32-bit integer.
 */
fun printSum(a: Int, b: Int) = println(a.toLong() + b)

会生成 Objective-C 声明, 没有任何注释:

+ (void)printSumA:(int32_t)a b:(int32_t)b __attribute__((swift_name("printSum(a:b:)")));

要启用 KDoc 注释导出功能, 请在你的 build.gradle(.kts) 添加以下编译器选项:

kotlin {
    targets.withType<org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget> {
        compilations.get("main").compilerOptions.options.freeCompilerArgs.add("-Xexport-kdoc")
    }
}

kotlin {
    targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget) {
        compilations.get("main").compilerOptions.options.freeCompilerArgs.add("-Xexport-kdoc")
    }
}

这样设置之后, Objective-C 头文件将包含对应的注释:

/**
 * Prints the sum of the arguments.
 * Properly handles the case when the sum doesn't fit in 32-bit integer.
 */
+ (void)printSumA:(int32_t)a b:(int32_t)b __attribute__((swift_name("printSum(a:b:)")));

你将能够在自动完成中看到类和方法上的注释, 例如, 在 Xcode 中, 如果你跳转到 函数的定义 (在 .h 文件中), 你会看到 @param, @return 等等上的注释.

已知的限制:

warning

KDoc 注释导出到生成的 Objective-C 头文件是 实验性功能. 它随时有可能变更或被删除. 需要使用者同意(Opt-in) (详情见下文), 而且你应该只为评估目的来使用这个功能. 希望你能通过我们的 问题追踪系统 提供你的反馈意见.

• 依赖项的文档不会导出, 除非它本身也使用 -Xexport-kdoc 选项来编译. 这个功能还是实验性功能, 因此使用这个选项编译的库可能与其他编译器版本不兼容.

• 绝大多数 KDoc 注释会保持原状导出. 很多 KDoc 功能还不支持, 例如 @property.

类

初始化器(Initializer)

Swift/Objective-C 初始化器(Initializer)导入 Kotlin 时会成为构造器. 对于 Objective-C category 中声明的初始化器, 或声明为 Swift extension 的初始化器, 导入 Kotlin 时会成为名为 create 的工厂方法, 因为 Kotlin 没有扩展构造器的概念.

tip

将 Swift 初始化器导入到 Kotlin 之前, 不要忘记对它添加 @objc 注解.

Kotlin 构造器导入 Swift/Objective-C 时会成为初始化器.

设值方法(Setter)

Objective-C 中可写的属性如果覆盖超类中的只读属性, 对于 foo 属性会表示为 setFoo() 方法. 对于一个协议(protocol)的只读属性, 如果实现为可变的属性, 那么也是同样的规则.

顶层函数和属性

Kotlin 的顶层函数和属性, 可以通过某个特殊类的成员来访问. 每个 Kotlin 源代码文件都会被翻译为一个这样的类, 例如:

// MyLibraryUtils.kt
package my.library

fun foo() {}

你可以在 Swift 中这样调用 foo() 函数:

MyLibraryUtilsKt.foo()

参见 Kotlin-Swift interopedia 中访问 Kotlin 顶层声明的一组示例:

• 顶层函数

• 顶层只读属性

• 顶层可变属性

方法名称翻译

通常来说, Swift 的参数标签和 Objective-C 的 selector 会被映射为 Kotlin 的参数名称. 但这两种概念还是存在一些语义上的区别, 因此有时 Swift/Objective-C 方法导入时可能导致 Kotlin 中的签名冲突. 这时, 发生冲突的方法可以在 Kotlin 使用命名参数来调用, 例如:

[player moveTo:LEFT byMeters:17]
[player moveTo:UP byInches:42]

在 Kotlin 中, 应该这样调用:

player.moveTo(LEFT, byMeters = 17)
player.moveTo(UP, byInches = 42)

下面是 kotlin.Any 函数到 Swift/Objective-C 的映射:

参见 Kotlin-Swift interopedia 中数据类的示例.

你可以使用 @ObjCName 注解, 在 Swift 或 Objective-C 中指定一个更加符合使用习惯的名称, 而不是对 Kotlin 声明自动重命名.

错误与异常

所有的 Kotlin 异常都是不受控的, 也就是说错误会在运行期间捕获. 但是 Swift 只有受控错误, 在编译期间处理. 因此如果 Swift 或 Objective-C 的代码调用一个抛出异常的 Kotlin 方法, 那么 Kotlin 方法应该使用 @Throws 注解， 指明一组 "期待的" 异常类.

编译为 Objective-C/Swift 框架时, 非-suspend 的函数如果拥有或继承了 @Throws 注解, 在 Objective-C 中会被表示为产生 NSError* 的方法, 在 Swift 中会被表示为 throws 方法. suspend 函数的表达中, 在它的 completion handler 中一定会有 NSError*/Error 参数.

如果从 Swift/Objective-C 代码调用的 Kotlin 函数中抛出异常, 而且这个异常是 @Throws 注解指定的异常类(或其子类)的实例, 那么这个异常会被转换为 NSError. 其他 Kotlin 异常到达 Swift/Objective-C 代码后, 会被认为是未处理的错误, 并导致程序终止.

没有 @Throws 注解的 suspend 函数, 只会传播 CancellationException 异常 (做为 NSError). 没有 @Throws 注解的非-suspend 函数, 则完全不会传播 Kotlin 的异常.

注意, 反过来的翻译目前还未实现: Swift/Objective-C 中抛出 error 的方法, 导入 Kotlin 时不会成为抛出异常的方法.

参见 Kotlin-Swift interopedia 中的示例.

枚举类

Kotlin 枚举类会被导入为 Objective-C 中的 @interface, 以及 Swift 中的 class. 这些数据结构拥有与各个枚举值相对应的属性. 对于下面的 Kotlin 代码:

// Kotlin
enum class Colors {
    RED, GREEN, BLUE
}

在 Swift 中, 你可以这样访问这个枚举类的属性:

// Swift
Colors.red
Colors.green
Colors.blue

要在 Swift 的 switch 语句中使用 Kotlin 枚举类型的变量, 需要提供一个 default 语句, 以避免发生编译错误:

switch color {
    case .red: print("It's red")
    case .green: print("It's green")
    case .blue: print("It's blue")
    default: fatalError("No such color")
}

参见 Kotlin-Swift interopedia 中的示例.

挂起函数

warning

从 Swift 代码中 以 async 方式调用 suspend函数是 实验性功能. 它随时有可能变更或被删除. 请注意, 只为评估和试验目的来使用这个功能. 希望你能通过我们的 问题追踪系统 提供你的反馈意见.

Kotlin 的 挂起函数 (suspend) 在生成的 Objective-C 头文件中表达为带有回调的函数, 或用 Swift/Objective-C 术语称为 completion handlers.

从 Swift 5.5 开始, Kotlin 的 suspend 函数也可以从 Swift 代码中以 async 函数的方式调用, 而不需要使用 completion handler. 目前, 这个功能还处于非常初始的实验阶段, 存在很多限制. 详情请参见 这个 YouTrack issue.

• 更多详情请参见 关于 async/await 机制的 Swift 文档.

• 参见 Kotlin-Swift interopedia 中的示例, 以及推荐的实现相同功能的第三方库.

扩展与 Category 成员

Objective-C Category 的成员, 以及 Swift extension 的成员, 导入 Kotlin 时通常会变成扩展函数. 因此这些声明在 Kotlin 中不能被覆盖, 而且 extension 初始化器在 Kotlin 中不会成为类的构造器.

note

目前有两种例外情况. 从 Kotlin 1.8.20 开始, 在 NSView 类 (来自 AppKit 框架) 或 UIView 类 (来自 UIKit 框架) 的相同的头文件中声明的 Category 的成员, 会被导入为这些类的成员. 因此你可以覆盖从 NSView 或 UIView 继承的子类的方法.

对 "通常的" Kotlin 类的 Kotlin 扩展, 导入 Swift 和 Objective-C 后, 分别会成为扩展和 category 成员. 对其他类型的 Kotlin 扩展, 会被当作 顶层声明 处理, 带有额外的接受者参数. 这些类型包括:

• Kotlin String 类型

• Kotlin 集合类型, 及其子类型

• Kotlin interface 类型

• Kotlin 基本类型(primitive type)

• Kotlin inline 类

• Kotlin Any 类型

• Kotlin 函数类型, 及其子类型

• Objective-C 类和协议(protocol)

参见 Kotlin-Swift interopedia 中的一组示例.

Kotlin 单子(Singleton)

Kotlin 单子(Singleton) (通过 object 声明产生, 包括 companion object) 导入 Swift/Objective-C 会成为一个类, 但它只有唯一一个实例.

这个实例可以通过 shared 和 companion 属性来访问.

对于下面的 Kotlin 代码:

object MyObject {
    val x = "Some value"
}

class MyClass {
    companion object {
        val x = "Some value"
    }
}

可以通过以下方式访问这些对象:

MyObject.shared
MyObject.shared.x
MyClass.companion
MyClass.Companion.shared

note

通过 Objective-C 的 [MySingleton mySingleton] 和 Swift 的 MySingleton() 访问对象, 这个功能已被废弃.

参见 Kotlin-Swift interopedia 中的更多示例:

• 如何使用 shared 访问 Kotlin 对象

• 如何在 Swift 中 访问 Kotlin 伴随对象的成员.

NSNumber

Kotlin 基本类型的装箱类会被映射为 Swift/Objective-C 中的特殊类. 比如, kotlin.Int 装箱类在 Swift 中会被表达为 KotlinInt 类的实例 (或 Objective-C 中的 ${prefix}Int 类的实例, 其中 prefix 是框架名称前缀). 这些类都继承自 NSNumber, 因此它们的实例都是 NSNumber, 也支持 NSNumber 上的所有的操作.

NSNumber 类型用做 Swift/Objective-C 的参数类型或返回值类型时, 不会自动翻译为 Kotlin 的基本类型. 原因是, NSNumber 类型没有提供足够的信息, 指明它内部包装的基本值类型是什么, 例如, 通过 NSNumber 我们无法知道它究竟是 Byte, Boolean, 还是 Double. 因此 Kotlin 基本类型 与 NSNumber 类型的相互转换必须手工进行.

NSMutableString

Objective-C 的 NSMutableString 类在 Kotlin 中无法使用. NSMutableString 所有实例在传递给 Konlin 之前都会被复制一次.

集合

Kotlin 集合会被转换为 Swift/Objective-C 的集合类型, 对应关系请参见 上表. Swift/Objective-C 的集合也会以同样的方式映射为 Kotlin 的集合类型, 但 NSMutableSet 和 NSMutableDictionary 除外.

NSMutableSet 不会转换为 Kotlin 的 MutableSet. 要将一个对象传递给 Kotlin MutableSet, 需要明确地创建这个 Kotlin 集合类型的实例. 具体做法是, 例如, 在 Kotlin 中使用 mutableSetOf() 函数, 或在 Swift 中使用 KotlinMutableSet 类, 或在 Objective-C 中使用 ${prefix}MutableSet (prefix 是框架名称前缀). 对于 MutableMap 类型也是如此.

参见 Kotlin-Swift interopedia 中的示例.

Function 类型

Kotlin 的函数类型对象 (比如 Lambda 表达式) 会被转换为 Swift 的函数, 或 Objective-C 的代码段(block). 参见 Kotlin-Swift interopedia 中带 Lambda 表达式的 Kotlin 函数的示例.

但是, 在翻译函数和函数类型时, 对于参数类型和返回值类型的映射方法存在区别. 对于函数类型, 基本类型映射为它们的装箱类. Kotlin 的 Unit 返回值类型在 Swift/Objective-C 中会被表达为对应的 Unit 单子. 这个单子的值可以象其他任何 Kotlin object 一样, 通过相同的方式得到 参见 上表 中的单子.

对于下面的 Kotlin 函数:

fun foo(block: (Int) -> Unit) { ... }

在 Swift 中会成为:

func foo(block: (KotlinInt) -> KotlinUnit)

你可以这样调用它:

foo {
    bar($0 as! Int32)
    return KotlinUnit()
}

泛型

Objective-C 支持类上定义的 "轻量的泛型", 支持的功能相对有限. Swift 可以导入类上定义的泛型, 向编译器提供额外的类型信息.

Objective-C 和 Swift 对泛型功能的支持与 Kotlin 不同, 因此翻译过程不可避免的将会丢失部分信息, 但支持的那部分功能还能保留有意义的信息.

关于如何在 Swift 中使用 Kotlin 泛型的具体示例, 请参见 Kotlin-Swift interopedia.

class Sample<T>() {
    fun myVal(): T
}

class Sample<T>() {
    fun myVal(): T?
}

class Sample<T : Any>() {
    fun myVal(): T
}

data class SomeData(val num: Int = 42) : BaseData()
class GenVarOut<out T : Any>(val arg: T)

let variOut = GenVarOut<SomeData>(arg: sd)
let variOutAny : GenVarOut<BaseData> = variOut as! GenVarOut<BaseData>

binaries.framework {
    freeCompilerArgs += "-Xno-objc-generics"
}

提前声明(Forward Declaration)

要导入提前声明(Forward Declaration), 请使用 objcnames.classes 和 objcnames.protocols 包. 例如, 要导入在 Objective-C 库 library.package 中声明的提前声明 objcprotocolName, 要使用一个特殊的提前声明包: import objcnames.protocols.objcprotocolName.

假设有两个 objcinterop 库: 一个使用 objcnames.protocols.ForwardDeclaredProtocolProtocol, 另一个库在另一个包中包含实际实现:

// 第 1 个 objcinterop 库
#import <Foundation/Foundation.h>

@protocol ForwardDeclaredProtocol;

NSString* consumeProtocol(id<ForwardDeclaredProtocol> s) {
    return [NSString stringWithUTF8String:"Protocol"];
}

// 第 2 个 objcinterop 库
// 头文件:
#import <Foundation/Foundation.h>
@protocol ForwardDeclaredProtocol
@end
// 实现:
@interface ForwardDeclaredProtocolImpl : NSObject <ForwardDeclaredProtocol>
@end

id<ForwardDeclaredProtocol> produceProtocol() {
    return [ForwardDeclaredProtocolImpl new];
}

要在两个库之间转换对象, 请在你的 Kotlin 代码中使用明确的 as 转换:

// Kotlin 代码:
fun test() {
    consumeProtocol(produceProtocol() as objcnames.protocols.ForwardDeclaredProtocolProtocol)
}

note

你只能从对应的真实的类转换到 objcnames.protocols.ForwardDeclaredProtocolProtocol. 否则, 会发生错误.

在 Swift/Objective-C 中继承 Kotlin 类和接口

Swift/Objective-C 类和 protocol 可以继承 Kotlin 类和接口.

在 Kotlin 中继承 Swift/Objective-C 类和接口

Kotlin 的 final class 可以继承 Swift/Objective-C 类和 protocol. 目前还不支持非 final 的 Kotlin 类继承 Swift/Objective-C 类型, 因此不可能声明一个复杂的类层级, 同时又继承 Swift/Objective-C 类型.

可以使用 Kotlin 的 override 关键字来覆盖通常的方法. 这种情况下, 子类方法的参数名称, 必须与被覆盖的方法相同.

有时我们会需要覆盖初始化器, 例如, 继承 UIViewController 时. 初始化器会被导入成为 Kotlin 中的构造器, 它可以被 Kotlin 中使用了 @OverrideInit 注解的构造器覆盖:

class ViewController : UIViewController {
    @OverrideInit constructor(coder: NSCoder) : super(coder)

    ...
}

子类构造器的参数名称和类型, 必须与被覆盖的构造器相同.

如果多个方法在 Kotlin 中发生了签名冲突, 要覆盖这些方法, 你可以在类上添加 @ObjCSignatureOverride 注解. 这个注解指示 Kotlin 编译器忽略冲突的覆盖, 以防多个函数带有相同的参数类型, 但不同的参数名称, 而且这些函数继承自 Objective-C 类.

Kotlin/Native 默认不会允许通过 super() 构造器来调用 Objective-C 的非指定(non-designated)初始化器. 如果在 Objective-C 库中没有正确地标注出指定的(designated)初始化器, 那么这种限制可能会造成我们的不便. 要关闭编译器的这个检查, 请在库的 .def 文件 中添加一个 disableDesignatedInitializerChecks = true 设定.