Auto-update blog content

Author: github-actions[bot]

content/posts/2025-09-19-151791591.md

@@ -0,0 +1,353 @@
+---
+layout: post
+title: "Objective-C-APIs-declaration-自定义"
+date: 2025-09-19T19:37:42+0800
+description: "NS_REFINED_FOR_SWIFT 是把 Objective-C API 在导入到 swift 时,重命名成在第一个标签前加 _ _ 的函数——表示不建议 swift 侧直接调用. 然后你就可以在 swift 侧用 swift extension 里写一个更 Swifty 的替代方案.举个例子:__initWithCString(_:freeWhenDone:) // 有双下划线，不建议直接在类外调。"
+keywords: "Objective-C —— APIs declaration 自定义"
+categories: ['未分类']
+tags: ['Swift', 'Ios', 'C']
+artid: "151791591"
+arturl: "https://blog.csdn.net/m0_73093743/article/details/151791591"
+image:
+    path: https://api.vvhan.com/api/bing?rand=sj&artid=151791591
+    alt: "Objective-C-APIs-declaration-自定义"
+render_with_liquid: false
+featuredImage: https://bing.ee123.net/img/rand?artid=151791591
+featuredImagePreview: https://bing.ee123.net/img/rand?artid=151791591
+cover: https://bing.ee123.net/img/rand?artid=151791591
+image: https://bing.ee123.net/img/rand?artid=151791591
+img: https://bing.ee123.net/img/rand?artid=151791591
+---
+
+
+
+# Objective-C —— APIs declaration 自定义
+
+## 一、枚举
+
+#### 1、NS_ENUM
+
+NS_ENUM 只是简单地把一些常量组成一组,然后构成枚举类型.但值得注意的是,在这 5 种枚举中,只有 NS_ENUM 和 NS_CLOSED_ENUM 在引入到 swift 后变成 enum.
+
+因为 NS_ENUM 在引入到 swift 后变成 enum: Int, 所以 NS_ENUM 在 swift 侧是允许用 swift 创建新值的.但在 oc 是不允许创建新值的.
+
+NS_ENUM 的 raw value 只支持整型家族(NSInteger, NSUInteger……)
+
+```
+
+typedef NS_ENUM(NSInteger, UITableViewCellStyle) {
+    UITableViewCellStyleDefault,
+    UITableViewCellStyleValue1,
+    UITableViewCellStyleValue2,
+    UITableViewCellStyleSubtitle
+};
+```
+
+引入 swift 时就会变成这样:
+
+![](https://i-blog.csdnimg.cn/direct/a5b09e239cc642bbb5fe5f9b11ea3c71.png)
+
+另外值得注意的是, 因为 NS_ENUM 是可扩展的, 所以所有的 case 有可能不只声明时的 3 种,因此  NS_ENUM 在引入 swift 时, swift5 和 swift6 会分别通过警告和报错强制要你在 switch-case 里加 default, 来应对除声明 NS_ENUM 以外的 case.
+
+![](https://i-blog.csdnimg.cn/direct/b8b300631e934b9282bfb74805810c5f.png)
+
+![](https://i-blog.csdnimg.cn/direct/d48aa4abaeb0491e944480eb9ac29c2e.png)
+
+#### 2、NS_CLOSED_ENUM
+
+在了解了 NS_ENUM 后, NS_CLOSED_ENUM 就很通俗易懂了. 就是你只能在 NS_CLOSED_ENUM 声明时往大括号里加值,不能在大括号外创建新值. 所以在引入 swift 后, swift 的 switch-case 并不用强制写 @unknown default.
+
+当然, 我们也不能在声明 NS_CLOSED_ENUM 的大括号外创建新值.
+
+同样, NS_CLOSED_ENUM 的 raw value 只支持整型家族的.
+
+```
+
+typedef NS_CLOSED_ENUM(NSInteger, MyClosedEnum) {
+    MyClosedEnumA = 0,
+    MyClosedEnumB = 1,
+};
+```
+
+引入 swift 后会变成这样:
+
+![](https://i-blog.csdnimg.cn/direct/eff4c6b4782e475383ea80f1c1aaaee7.png)
+
+例子:  
+![](https://i-blog.csdnimg.cn/direct/83a8b3165cd1462694c3f3ff079f0b1c.png)
+
+#### 3、NS_OPTIONS
+
+当你想让所有 case 都互斥,那么 NS_OPTIONS 就是很好的选择. NS_OPTIONS 会作为一个 Optional Set (也就是 bitmap) 引入 swift.这样 swift 就可以给一个整型变量赋多个枚举值, 然后做逻辑判断的时候可以用 |, &  来替代 ||, && . 因此一般 NS_OPTIONS 的值用在 if 组合判断比较多,一般不用于 switch-case.
+
+当然, NS_OPTIONS 的 raw value 依旧只能是整型家族的.
+
+```
+
+typedef NS_OPTIONS(NSUInteger, UIViewAutoresizing) {
+        UIViewAutoresizingNone                 = 0,
+        UIViewAutoresizingFlexibleLeftMargin   = 1 << 0,
+        UIViewAutoresizingFlexibleWidth        = 1 << 1,
+        UIViewAutoresizingFlexibleRightMargin  = 1 << 2,
+        UIViewAutoresizingFlexibleTopMargin    = 1 << 3,
+        UIViewAutoresizingFlexibleHeight       = 1 << 4,
+        UIViewAutoresizingFlexibleBottomMargin = 1 << 5
+};
+```
+
+作为以下形式引入 swift:
+
+![](https://i-blog.csdnimg.cn/direct/cb5b46849c5842f7b29647753895e19b.png)
+
+#### 4、NS_TYPED_ENUM
+
+如果你想用 raw value 为非整型的枚举, 而且你枚举的 case 在逻辑上 (语义上) 是不可扩展的, 那就推荐用 NS_TYPED_ENUM.
+
+![](https://i-blog.csdnimg.cn/direct/f3b69772f15f42348d5a826b95ed59a1.png)
+
+> ⬆️ 把 NS_TYPED_ENUM 宏展开后, 可以看到  NS_TYPED_ENUM 是作为 swift 的 enum 引入 swift 的._
+
+```
+
+// Store the three traffic light color options as 0, 1, and 2.
+typedef long TrafficLightColor NS_TYPED_ENUM;
+
+
+TrafficLightColor const TrafficLightColorRed;
+TrafficLightColor const TrafficLightColorYellow;
+TrafficLightColor const TrafficLightColorGreen;
+```
+
+作为以下形式引入 swift:
+
+![](https://i-blog.csdnimg.cn/direct/e85c983a3b304779a45b1ec905748477.png)
+
+NS_TYPED_ENUM 是作为 swift 的 enum 引入的, 所以其实在代码上确实可以通过对 TrafficLightColor 加 extension 的方式来实现新增 case. 所以 NS_TYPED_ENUM 仅仅只是语义上不支持新增 case 而已.
+
+![](https://i-blog.csdnimg.cn/direct/5c187e9999864d12bcb35c59600ecbd4.png)
+
+#### 5、NS_TYPED_EXTENSIBLE_ENUM
+
+NS_TYPED_EXTENSIBLE_ENUM 同样支持 raw value 自定义, 而且同样可以在 swift 侧通过 extension 给 oc 的 enum 加新的 case. 但与 NS_TYPED_ENUM 不同的是, NS_TYPED_EXTENSIBLE_ENUM 在逻辑上 (语义上) 支持新增 case 的时候才用.
+
+![](https://i-blog.csdnimg.cn/direct/b0d1adeec3a94885a43e82f5438679ba.png)
+
+> ⬆️ 把 NS_TYPED_EXTENSIBLE_ENUM 展开后, NS_TYPED_EXTENSIBLE_ENUM 是作为 swift 的 struct 引入 swift 的.
+
+```
+
+typedef long FavoriteColor NS_TYPED_EXTENSIBLE_ENUM;
+FavoriteColor const FavoriteColorBlue;
+```
+
+⬇️ OC 侧的 FavoriteColor 将作为以下形式引入到 swift 中:
+
+![](https://i-blog.csdnimg.cn/direct/86f78c6de15e45c090ae1ee8c5b84ab6.png)
+
+同时你也同样可以通过 extension 的方式给 FavoriteColor 加新的 case, 这点和 NS_TYPED_ENUM 是完全一样的.
+
+```
+
+extension FavoriteColor {
+    static var green: FavoriteColor {
+        return FavoriteColor(1) // blue is 0, green is 1, and new favorite colors could follow
+    }
+}
+```
+
+## 二、 oc 侧 API 桥接声明自定义
+
+### 1、重命名
+
+#### 1.1. NS_REFINED_FOR_SWIFT
+
+NS_REFINED_FOR_SWIFT 是把 Objective-C API 在导入到 swift 时,重命名成在第一个标签前加 _ _ 的函数——表示不建议 swift 侧直接调用. 然后你就可以在 swift 侧用 swift extension 里写一个更 Swifty 的替代方案.
+
+> 举个例子:  
+> ObjC 里你写了一个很底层的初始化：
+>
+> ```
+>
+> - (instancetype)initWithCString:(const char *)cString
+>                           freeWhenDone:(BOOL)freeWhenDone
+>     NS_REFINED_FOR_SWIFT;
+> ```
+>
+> Swift 里会变成：
+>
+> ```
+>
+> __initWithCString(_:freeWhenDone:)   // 有双下划线，不建议直接在类外调
+> ```
+>
+> 这时候你就可以在 Swift extension 里写一个更 Swift 化的替代方案：
+>
+> ```
+>
+> extension MyString {
+>     convenience init(_ string: String) {
+>         self.init(cString: string.cString(using: .utf8), freeWhenDone: false)
+>     }
+> }
+> ```
+
+#### 1.2. NS_SWIFT_NAME
+
+NS_SWIFT_NAME 就是把类, 成员属性, 成员函数等重命名. 相当于告诉 swift: 在 Swift 里，这个函数 / 类型 / 方法应该显示成什么名字。NS_SWIFT_NAME 只影响 swift 侧的名字,不影响 oc 侧的名字.
+
+```
+
+NS_SWIFT_NAME(Sandwich.Preferences)
+@interface SandwichPreferences : NSObject
+
+
+@property BOOL includesCrust NS_SWIFT_NAME(isCrusty);
+
+
+@end
+
+
+@interface Sandwich : NSObject
+@end
+```
+
+```
+
+typedef NS_ENUM(NSInteger, SandwichBreadType) {
+    brioche, pumpernickel, pretzel, focaccia
+} NS_SWIFT_NAME(SandwichPreferences.BreadType);
+```
+
+```
+
+var preferences = Sandwich.Preferences()
+preferences.isCrusty = true
+```
+
+### 2、有效性自定义
+
+#### 2.1. API_AVAILABLE  & @available
+
+API_AVAILABLE 就是 oc 侧在声明函数时规定该函数应该对哪些版本的系统有效. 记住,
+
+Objective-C 侧声明成员函数的有效性用 API_AVAILABLE:
+
+```
+
+@interface MyViewController : UIViewController
+- (void) newMethod API_AVAILABLE(ios(11), macosx(10.13));
+@end
+```
+
+相当于 Swift 侧用 @available 修饰成员函数:
+
+```
+
+@available(iOS 11, macOS 10.13, *)
+func newMethod() {
+    // Use iOS 11 APIs.
+}
+```
+
+Objective-C 侧用 @available 检查当前操作系统的版本:
+
+```
+
+if (@available(iOS 11, *)) {
+    // Use iOS 11 APIs.
+} else {
+    // Alternative code for earlier versions of iOS.
+}
+```
+
+等同于Swift 侧用 #available 检查当前操作系统的版本:
+
+```
+
+if #available(iOS 11, *) {
+    // Use iOS 11 APIs.
+} else {
+    // Alternative code for earlier versions of iOS.
+}
+```
+
+#### 2.2. NS_SWIFT_UNAVAILABLE
+
+NS_SWIFT_UNAVAILABLE 就是在 Objective-C 侧函数声明的时候告诉 swift 这个函数对 swift 不开放. NS_SWIFT_UNAVAILABLE() 括号里填一段字符串, 如果 Swift 侧调了这个函数, 会编译出错,然后报错的内容就会打印出括号里的字符串.
+
+![](https://i-blog.csdnimg.cn/direct/47898ded84b44b9c85f199cc59439aa7.png)
+
+#### 2.3. NS_UNAVAILABLE
+
+NS_UNAVAILABLE 就是声明这个 Objective-C 侧的函数对除 Objective-C 以外的其他所有语言都无效. NS_UNAVAILABLE() 括号里填一段字符串, 如果其他语言侧调了这个函数, 会编译出错,然后报错的内容就会打印出括号里的字符串.
+
+## 三、Nullability
+
+下面的可空和非空都是针对引入 Swift 而言的. 如果在 oc 侧对一个变量声明非空, 那么在引入到 Swift 后会变成普通类型(非 Optional), 而如果在 oc 侧对一个变量声明可空,那么在引入到 Swift 后会变成显式可选类型(Optional).
+
+而下面的可空和非空对 oc 侧的代码都没有影响.因为 oc 在指针方面就和 C 语言一样, 无论怎么修饰,都是可以赋 nil 的; 同样如果在 oc 用空指针调函数或访问属性,那必然会报错的.
+
+### 1、nonnull + nullable
+
+用两个东西修饰的函数形参和一级指针都可以. 但 nonnull + nullable 对于标记多级指针和 id * 指针的非空性非常不方便. 所以在开发的角度来看, 尽量别用 nonnull & nullable; 而应该用 _Nullable & _Nonnull.
+
+```
+
+@interface MyClass : NSObject
+
+@property (nonatomic, strong) NSString *name;              // nonnull，默认不可空
+@property (nonatomic, strong, nullable) NSString *nickname; // nullable，可空
+
+@end
+
+
+typedef void (^CompletionHandler)(nullable NSString *result, nullable NSError *error);
+
+@interface MyClass (Blocks)
+
+// 参数不可空，返回值可空
+- (nullable NSString *)fetchDataWithParam:(nonnull NSString *)param
+                               completion:(nonnull CompletionHandler)completion;
+
+// 参数可空，返回值不可空
+- (nonnull NSString *)processData:(nullable NSString *)data
+                       completion:(nullable CompletionHandler)completion;
+
+@end
+```
+
+### 2、_Nonnull + _Nullable
+
+_Nonnull & _Nullable 除了和上面的 nonnull 和 nullable 功能一样外, 在多级指针方面也比上面的组合要方便不少:
+
+```
+
+// out 参数：必须传一个有指向的指针,但指着的内存可以没有值
+- (void)fillString:(NSString * _Nullable * _Nonnull)outString;
+```
+
+需要注意的是: 如果你要指定 id* 的非空性, 只能用 _Nullable & _Nonnull, 不能用 nonnull 和 nullable.
+
+### 3、某片区域默不可空
+
+使用 NS_ASSUME_NONNULL_BEGIN + NS_ASSUME_NONNULL_END 包围不可空区域，其他地方默认可空
+
+```
+
+NS_ASSUME_NONNULL_BEGIN
+
+
+@interface MyList : NSObject
+- (nullable MyListItem *)itemWithName:(NSString *)name;
+- (nullable NSString *)nameForItem:(MyListItem *)item;
+@property (copy) NSArray<MyListItem *> *allItems;
+@end
+
+
+NS_ASSUME_NONNULL_END
+```
+
+需要注意的是: `typedef` 类型即使在 NS_ASSUME_NONNULL_BEGIN + NS_ASSUME_NONNULL_END 区域内也不会被假定为非空，因为它们本质上不是可空类型。
+
+
+