macOS Apple 帮助创作 - anchor

Question

我正在尝试为我准备发布的 macOS 应用程序制作 Apple 帮助手册。但是，我正在尝试使 anchor 在我的 HTML 中工作。按照苹果的定义:

"Anchors allow you to uniquely identify topics in your help book. When a user follows a link to an anchor, Help Viewer loads the page containing the anchor. ... You can also use anchors to load an anchored page from within your application by calling the the NSHelpManager method openHelpAnchor:inBook: ..."

来自 Apple 的示例: <a name="ArrivalTimesUsingStopID"></a>
在我的 Apple 中，我有一个 NSAlert，它具有以下代码来显示帮助按钮，以便当您单击它时，它会打开指定的 anchor 字符串。

alert.showsHelp = true
alert.helpAnchor = NSHelpManager.AnchorName(stringLiteral: "ArrivalTimesUsingStopID")

运行代码确实会显示帮助按钮，并且 Mac 帮助确实会打开，但是会出现一个错误，指出找不到指定的内容。不知道为什么 anchor 不工作，因为如果我转到帮助菜单并从那里打开它，我可以访问帮助手册。

此外，Apple 的文件指出:

The NSAlert, SFChooseIdentityPanel, SFCertificatePanel classes provide help buttons for dialogs. To display such a help button and link it to an anchor in your help book, use the methods setShowsHelp: and setHelpAnchor: in those classes.

以及 NSAlert 中的这些属性的文档状态:

-setShowsHelp:YES adds a help button to the alert panel. When the help button is pressed, the delegate is first consulted. If the delegate does not implement alertShowHelp: or returns NO, then -[NSHelpManager openHelpAnchor:inBook:] is called with a nil book and the anchor specified by -setHelpAnchor:, if any. An exception will be raised if the delegate returns NO and there is no help anchor set.

...所以我知道我正在正确使用这两个。

我还了解每次更新 Apple 帮助手册 HTML 文档时都需要创建一个 .helpindex 文件。我正在使用 developer.apple.com 上的 Additional Xcode Tools 中的“Help Indexer.app”。我确保:

我设置了索引所有 anchor 的选项。

任何带有 anchor 的 HTML 页面都有 <meta name="ROBOTS" content="ANCHORS">在标题中，因此 anchor 被索引。

我的 Apple 帮助书 plist 文件正确指向由“Help Indexer.app”创建的 .helpindex 文件。

但即使有了所有这些，我也无法将 Apple 帮助书打开到正确的 anchor ，甚至无法打开 Apple 帮助书的标题页。

我读了
https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/user_help_intro/user_assistance_intro.html#//apple_ref/doc/uid/TP30000903-CH204-CHDIDJFE

从封面到封面多次，我无法在网上找到解决方案或任何地方。

我也尝试过手动打开它，但它只是打开相同的错误，说无法使用以下代码找到指定的内容:

let bookName = Bundle.main.object(forInfoDictionaryKey: "CFBundleHelpBookName") as! String
NSHelpManager.shared.openHelpAnchor("ArrivalTimesUsingStopID", inBook: bookName)

使用 nil对于 inBook 参数也不起作用:

NSHelpManager.shared.openHelpAnchor("ArrivalTimesUsingStopID", inBook: nil)

有任何想法吗？

Answer 1

我不确定这是否是此时的答案，但这是一个答案，而且似乎可以解决问题。我无法获得 helpAnchor在 Alert to work 中，但使用帮助委托(delegate)，下面概述的方法有效。
我开始我的一天，试图打开一个简单的 anchor 帮助手册。我确定这曾经使用 NSHelpManager过去，但在最新版本的操作系统中似乎没有。
在打开我正在开发的应用程序的帮助手册时观看控制台导致以下结果:

Opening URL help:openbook=%22com.ClueTrust.Cartographica.help*1.5.2d1%22 with application <FSNode 0x6000006a1b40> { isDir = y, path = '/System/Library/CoreServices/HelpViewer.app' }

使用 NSHelpManager 打开我的 anchor 导致:

Opening URL help:anchor=SpatialJoinOperation%20bookID=%22com.ClueTrust.Cartographica.help%22%20appID=%22com.ClueTrust.Cartographica%22 with application <FSNode 0x6000006a8260> { isDir = y, path = '/System/Library/CoreServices/HelpViewer.app' }

而且，它并没有导致我的 anchor 打开。
我尝试附加 *<version>到我的网址:

Opening URL help:anchor=SpatialJoinOperation%20bookID=%22com.ClueTrust.Cartographica.help*1.5.2d1%22%20appID=%22com.ClueTrust.Cartographica%22 with application <FSNode 0x600000682c20> { isDir = y, path = '/System/Library/CoreServices/HelpViewer.app'

但是，深入查看控制台，我注意到这肯定会触发网络请求，并且有一个 unsupported URL回来。
我不清楚 help:anchor=...不再起作用，但我确实找到了一种相对简单但令人讨厌的解决问题的方法。
使用 help: 时肯定会打开帮助中的 anchor 。格式类似于 file: 的 URL URL 并包含一个 anchor ；它们将打开到正确的 anchor 位置。
这需要找到特定的帮助手册和 HTML 文件，以便您可以准确指定打开的位置。

    NSURL *helpBookURL = [NSBundle.mainBundle URLForResource:@"Cartographica" withExtension:@"help"];
    NSBundle *helpBundle = [NSBundle bundleWithURL:helpBookURL];
    NSURL *helpPageURL = [helpBundle URLForResource:@"Spatial_Join" withExtension:@"html"];
    NSURLComponents *urlParts = [NSURLComponents componentsWithURL:helpPageURL resolvingAgainstBaseURL:NO];
    urlParts.scheme=@"help";
    urlParts.fragment=@"SpatialJoinOperation";
    NSURL *finalHelpURL = urlParts.URL;
    [NSWorkspace.sharedWorkspace openURL:finalHelpURL];

基本上:

获取帮助手册的 URL(需要以从资源路径获取它的方式执行此操作，因此我们使用 NSBundle)

根据先验知识找到包含引用的页面(在这种情况下，Spatial_Join.html 是我们的文件名，因此我们让捆绑包按名称和扩展名查找它。

使用 NSURLComponents改变NSURL的接口(interface)通过从 file 更改方案至help并在 fragment 中添加我们的主播.

最后打开新建的网址

它并不漂亮，但它似乎确实有效且安全，至少在 10.15 以下的非沙盒 macOS 应用程序中是这样。
请注意，我可以在这里对帮助书名称做出一些假设，但出于说明目的，这似乎更清楚，并且由于资源的工作方式，不清楚这些关于名称的假设是否适用于所有情况。
我的最终结果是这个辅助方法:

- (void)openHelpPage:(NSString*)pageName anchor:(NSString  * _Nullable)anchor bookName:(NSString * _Nullable)bookName
{
    NSURL *helpBookURL = [NSBundle.mainBundle URLForResource:bookName withExtension:@"help"];
    NSBundle *helpBundle = [NSBundle bundleWithURL:helpBookURL];
    NSURL *helpPageURL = [helpBundle URLForResource:pageName withExtension:@"html"];
    NSURLComponents *urlParts = [NSURLComponents componentsWithURL:helpPageURL resolvingAgainstBaseURL:NO];
    urlParts.scheme=@"help";
    if (anchor)
        urlParts.fragment=anchor;
    NSURL *finalHelpURL = urlParts.URL;
    [NSWorkspace.sharedWorkspace openURL:finalHelpURL];
}

调用站点语法是:

// to specific anchor on a page
[self openHelpPage: @"Spatial_Join" anchor: @"SpatialJoinOperation" helpBook: nil];
// to specific page
[self openHelpPage: @"Spatial_Join" anchor: nil helpBook: nil];

我尝试使用 [NSBundle bundleWithIdentifier:] 获取帮助包使用帮助包 ID，但返回 nil。但是， [NSBundle URLForResource:withExtension]将采取 nil resourceName 的参数并获取与扩展名匹配的第一个项目。在我的情况下(我相信很多)只有一个 help资源，因此这允许一种不需要了解应用程序帮助书名称的方法。