有没有办法找到实际的 SwiftUI API 文档(而不仅仅是开发人员文档)? [英] Is there a way to find actual SwiftUI API Documentation (and not just the developer documentation)?

问题描述

我目前正在观看 WWDC 2019 的 SwiftUI Essentials 视频，演示者提出了 VStack 的实际 API，其中(难以置信，至少对我而言)详细说明了这个特定结构的实际工作原理.

有没有地方可以让开发者找到这种关于 Apple 提供的特定功能的详细、深入的文档?

Matt Stevens 有一个很棒的 AP​​Idiff (

打开SwiftUI.h".没什么好说的:

//版权所有 © 2015 Apple Inc. 保留所有权利.#import 

现在单击编辑器左上角的相关项目"图标，然后从菜单中选择生成的接口">SwiftUI":

然后，点击编辑器顶部跳转栏中SwiftUI"右侧的No Selection"，并在跳转菜单打开时输入vstack":

Xcode跳转到struct VStack的定义:

////将其子项排列在垂直线上的视图.@available(iOS 13.0, OSX 10.15, tvOS 13.0, watchOS 6.0, *)公共结构 VStack其中内容:查看{///使用给定的 `spacing` 和 Y 轴 `alignment` 创建一个实例.//////- 参数:///- 对齐:将具有相同水平屏幕的指南///坐标所有孩子.///- 间距:相邻孩子之间的距离，如果///堆栈应该为每对孩子选择一个默认距离.@inlinable public init(alignment: Horizo​​ntalAlignment = .center, pitch: Length? = nil, content: () -> Content)///表示此视图主体的视图类型.//////当您创建自定义视图时，Swift 会从您的///所需的`body` 属性的实现.公共类型别名正文 = 从不}

不幸的是，此(综合)声明省略了 content 参数上的 @ViewBuilder 属性.这个遗漏可能是一个错误.

除了省略注解之外，Swift 生成的接口还省略了以 _ 开头的类型、方法和属性.(省略这些是因为它们被认为是出于某种原因必须公开的实现细节.)例如，请注意 VStack 的生成接口也没有提到 VStack 符合 View.(参考文档 也没有提及.)

生成的界面和参考文档都没有告诉我们VStack符合View的原因是因为VStack没有直接符合View.VStack符合_UnaryView，_UnaryView是View的子协议.

您可以通过跟踪 .swiftinterface 来查看 VStack 的真实、诚实的公共接口——当您的源代码导入 SwiftUI 时编译器实际使用的接口> 模块文件.您可以在此路径中找到它，相对于您的 Xcode.app:

<块引用>

Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/SwiftUI.framework/Modules/SwiftUI.swiftmodule/arm64.swiftinterface

(因此，如果您尚未重命名 Xcode 11 beta 并将其放在 /Applications 中，请将 /Applications/Xcode-beta.app/ 放在该路径的前面代码>).

如果您在该文件中搜索 struct VStack，您将找到 VStack 的真正公共接口:

@available(iOS 13.0, OSX 10.15, tvOS 13.0, watchOS 6.0, *)@_fixed_layout 公共结构 VStack<Content>:_UnaryView 其中内容:SwiftUI.View {@usableFromInline内部变量 _tree: _VariadicView.Tree<_VStackLayout, Content>@inlinable public init(alignment: Horizo​​ntalAlignment = .center, spatial: Length? = nil, @SwiftUI.ViewBuilder content: () -> Content) {_tree = .init(根:_VStackLayout(对齐:对齐，间距:间距)，内容:内容())}public static func _makeView(视图:_GraphValue<VStack>，输入:_ViewInputs)->_视图输出public static func _makeViewList(视图:_GraphValue<VStack>，输入:_ViewListInputs)->_ViewListOutputspublic typealias Body = Swift.Never}

请注意，.swiftinterface 文件不合并扩展.VStack 没有任何扩展，但是(例如)Color 有，所以如果你想看到 Color 真正的公共接口，您需要同时搜索 struct Color 和 extension Color.

I’m currently watching the SwiftUI Essentials video from WWDC 2019 and the presenter pulled up the actual API for a VStack, which (incredibly, at least to me) details how this particular struct actually works.

Is there a place for developers to find this sort of detailed, in-depth documentation about particular features provided by Apple?

Matt Stevens has an awesome APIdiff (http://codeworkshop.net/objc-diff/sdkdiffs/) site that he provides, but it all links back to Apple’s standard developer documentation pages.

Sample code provided by the presenter:

public struct VStack<Content : View> : View {
     public init(
          alignment: HorizontalAlignment = .center,
          spacing: Length? = nil,
          @ViewBuilder content: () -> Content
     )
}

Actual provided documentation code:

struct VStack<Content> where Content : View

The specifics above regarding the alignment defaults, and the spacing length alone, while super simple, are already being asked as separate SO questions across the site in regards to what and why default behaviors are what they are.

I guess what I’m asking, is for current, more well-established classes in UIKit for example, is there a way to see the actual implementation details of the class themselves such as displayed in this WWDC for a SwiftUI VStack? I’m not sure if this is information that Apple just never gives out and is something that people have learned over time (this acts in a certain way "just because" and we know that from experience) or if this is just the fact that SwiftUI is new and hasn’t had time for Apple solidify SwiftUI and the documentation yet.

Sorry if this has been asked, or if it’s a super obvious question, I’m still pretty new to software development overall.

Thanks!

解决方案

What you've shown from that presentation isn't an implementation detail. It is the public init method of VStack. Note that it doesn't have a method body—it is not the implementation of the init method, only its type signature.

You can find the same information linked from the VStack documentation under the "Creating a Stack" target. Here's the documentation page for that init method.

You can also see method signatures like this, with doc comments if there are any, in Xcode.

In Xcode 11, choose File > Open Quickly… from the menu bar (default shortcut: ⇧⌘O). Type "swiftui" in the Open Quickly bar:

Open "SwiftUI.h". It doesn't say much:

// Copyright © 2015 Apple Inc. All rights reserved.

#import <AppKit/AppKit.h>

Now click the Related Items icon in the top left corner of the editor and choose Generated Interface > SwiftUI from the menu:

Then, click on "No Selection" to the right of "SwiftUI" in the jump bar at the top of the editor and type "vstack" while the jump menu is open:

Xcode jumps to the definition of struct VStack:

/// A view that arranges its children in a vertical line.
@available(iOS 13.0, OSX 10.15, tvOS 13.0, watchOS 6.0, *)
public struct VStack<Content> where Content : View {

    /// Creates an instance with the given `spacing` and Y axis `alignment`.
    ///
    /// - Parameters:
    ///     - alignment: the guide that will have the same horizontal screen
    ///       coordinate for all children.
    ///     - spacing: the distance between adjacent children, or nil if the
    ///       stack should choose a default distance for each pair of children.
    @inlinable public init(alignment: HorizontalAlignment = .center, spacing: Length? = nil, content: () -> Content)

    /// The type of view representing the body of this view.
    ///
    /// When you create a custom view, Swift infers this type from your
    /// implementation of the required `body` property.
    public typealias Body = Never
}

Unfortunately, this (synthesized) declaration omits the @ViewBuilder attribute on the content argument. This omission is probably a bug.

In addition to omitting annotations, Swift's generated interface also omits types, methods, and properties that start with _. (It omits these because they are considered implementation details that for whatever reason have to be made public.) For example, notice that the generated interface of VStack also doesn't mention that VStack conforms to View. (The reference documentation also doesn't mention it.)

The reason that both the generated interface and the reference documentation don't tell us VStack conforms to View is because VStack doesn't conform directly to View. VStack conforms to _UnaryView, and _UnaryView is a subprotocol of View.

You can see the real, honest-to-dog public interface of VStack—what the compiler actually uses when your source code imports SwiftUI—by tracking down the .swiftinterface file for the module. You can find it at this path, relative to your Xcode.app:

Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/SwiftUI.framework/Modules/SwiftUI.swiftmodule/arm64.swiftinterface

(So, put /Applications/Xcode-beta.app/ on the front of that path if you haven't renamed the Xcode 11 beta and have it in /Applications).

If you search that file for struct VStack, you'll find the true public interface of VStack:

@available(iOS 13.0, OSX 10.15, tvOS 13.0, watchOS 6.0, *)
@_fixed_layout public struct VStack<Content> : _UnaryView where Content : SwiftUI.View {
  @usableFromInline
  internal var _tree: _VariadicView.Tree<_VStackLayout, Content>
  @inlinable public init(alignment: HorizontalAlignment = .center, spacing: Length? = nil, @SwiftUI.ViewBuilder content: () -> Content) {
        _tree = .init(
            root: _VStackLayout(alignment: alignment, spacing: spacing), content: content())
    }
  public static func _makeView(view: _GraphValue<VStack>, inputs: _ViewInputs) -> _ViewOutputs
  public static func _makeViewList(view: _GraphValue<VStack>, inputs: _ViewListInputs) -> _ViewListOutputs
  public typealias Body = Swift.Never
}

Note that the .swiftinterface file does not consolidate extensions. VStack doesn't have any extensions, but (for example) Color does, so if you want to see the true public interface of Color, you need to search for both struct Color and extension Color.

这篇关于有没有办法找到实际的 SwiftUI API 文档(而不仅仅是开发人员文档)?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！