Справка по macOS для Apple - Авторы

Question

Справка по macOS для Apple - Авторы

Я пытаюсь создать справочную книгу Apple для моего приложения macOS, которую я готов выпустить. Однако я пытаюсь заставить работать якоря в моем HTML. По определению Apple:

"Якоря позволяют однозначно определять темы в вашей справочной книге. Когда пользователь переходит по ссылке на привязку, средство просмотра справки загружает страницу, содержащую привязку.... Вы также можете использовать привязки для загрузки привязанной страницы из приложения, вызов метода NSHelpManager openHelpAnchor:inBook: ..."

Пример от Apple: <a name="ArrivalTimesUsingStopID"></a>

В моем Apple у меня есть NSAlert, у которого есть следующий код для отображения кнопки справки, чтобы при нажатии на нее она открывала указанную строку привязки.

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

При запуске кода отображается кнопка справки, и справка Mac открывается, но с ошибкой, указывающей, что указанное содержимое не может быть найдено. Не уверен, почему якоря не работают, потому что я могу получить доступ к Справочной книге, если я иду в меню Справки и открываю ее оттуда.

Кроме того, в документе Apple говорится:

Классы NSAlert, SFChooseIdentityPanel, SFCertificatePanel предоставляют кнопки справки для диалогов. Чтобы отобразить такую кнопку справки и связать ее с привязкой в вашей справочной книге, используйте методы setShowsHelp: и setHelpAnchor: в этих классах.

и документация для этих свойств в NSAlert государство:

-setShowsHelp: ДА добавляет кнопку справки на панель предупреждений. Когда кнопка помощи нажата, делегат сначала консультируется. Если делегат не реализует alertShowHelp: или возвращает NO, тогда -[NSHelpManager openHelpAnchor:inBook:] вызывается с нулевой книгой и привязкой, указанной в -setHelpAnchor:, если таковые имеются. Будет сгенерировано исключение, если делегат вернет NO, а якорь справки не установлен.

... так что я знаю, что использую эти два правильно.

Я также понимаю, что мне нужно создавать файл.helpindex каждый раз, когда я обновляю HTML-документы своей справочной книги Apple. Я использую "Help Indexer.app", который находится в Дополнительных инструментах XCode на developer.apple.com. Я уверен, что:

У меня есть опция для индексации всех якорей.
Любая HTML-страница с привязкой имеет <meta name="ROBOTS" content="ANCHORS"> в заголовке так якоря индексируются.
Плист-лист моей книги справки Apple правильно указывает на файл.helpindex, созданный "Help Indexer.app".

Но даже несмотря на все это, я не могу заставить его открыть справочную книгу Apple на правильном якоре или даже на титульном листе моей справочной книги Apple.

Я прочитал https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/user_help_intro/user_assistance_intro.html

от обложки до обложки несколько раз, и я не могу найти решение или где-либо в Интернете.

Я также попытался открыть его вручную, но он просто открывает ту же ошибку, говоря, что указанное содержимое не может быть найдено с помощью следующего кода:

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

С помощью nil для параметра inBook тоже не работает:

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

Есть идеи?

5

macos appkit nsalert apple-help

Источник

user2020101 05 дек '18 в 17:30

0 ответов

Другие вопросы по тегам macos appkit nsalert apple-help

user147037 09 авг '20 в 15:16 2020-08-09 15:16 · Answer 1 · 2020-08-09 15:16

Я не уверен, если это ответ на данный момент, но это ответ и один, который, кажется, сделать трюк. Я не смог получитьhelpAnchor в Alert to work, но с помощью делегата справки работает метод, описанный ниже.

Я начал свой день с попытки открыть Справочную книгу с помощью простого якоря. Я уверен, что раньше это работало, используя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 привело к:

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' }

И это не привело к открытию моего якоря.

Я попытался добавить *<version> на мой URL:

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: URL-адрес в формате file:URL и содержит привязку; и они откроются в правильном месте якоря.

Для этого необходимо найти конкретную справочную книгу и файл 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 изменив схему с file к help и добавляем наш ахор в fragment.
Наконец, откройте вновь созданный URL

Это некрасиво, но кажется эффективным и безопасным, по крайней мере, в приложении macOS без песочницы до версии 10.15.

Обратите внимание, что я мог бы сделать здесь некоторые предположения относительно названия справочной книги, но для целей иллюстрации это кажется более ясным, и из-за того, как работают ресурсы, неясно, будут ли эти предположения относительно имен уместны во всех ситуациях.

Моим окончательным результатом был вспомогательный метод:

- (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:]используя идентификатор пакета справки, но он вернул ноль. Однако,[NSBundle URLForResource:withExtension] займет nil аргумент в пользу resourceNameи получите первый элемент, соответствующий расширению. В моем случае (а я верю многим) есть только одинhelp ресурс, поэтому это позволяет использовать метод, который не требует знания названия справочной книги приложения.

user2020101 06 сен '20 в 21:44 2020-09-06 21:44 · Answer 2 · 2020-09-06 21:44

Наконец-то я смог заставить это работать в изолированном приложении.

Если вы используете кнопку "Справка" напрямую, вы можете использовать что-то вроде:

@IBAction func helpButtonAction(_ sender: Any)
{
    if  let bookName = Bundle.main.object(forInfoDictionaryKey: "CFBundleHelpBookName") as? String {
        NSHelpManager.shared.openHelpAnchor("MY_ANCHOR_HERE", inBook: bookName)
    }
}

Если вы используете NSAlert(), вы можете использовать его кнопку справки с привязкой следующим образом:

let alert = NSAlert()
...
alert.showsHelp = true
alert.helpAnchor = NSHelpManager.AnchorName("MY_ANCHOR_HERE")

Несколько вещей, которые я усвоил на собственном горьком опыте:

Убедитесь, что ваша HTML-страница для вашей Справочной книги имеет правильную настройку для привязки:

<meta name="robots" content="anchors"> в <head> раздел, а также правильный тег заголовка в виде:

<a name="MY_ANCHOR_HERE"></a> в вашем <body> раздел.

Убедитесь, что вы используете "Help Indexer.app" для индексации своей справочной книги. Я обнаружил, что это не сработает, если вы не проиндексируете справочную книгу с помощью этого приложения. Это приложение можно скачать с developer.apple.comв разделе "Другие загрузки". Обычно они выпускают новую версию с каждым обновлением Xcode. Вы хотите найти "Дополнительные инструменты", и конкретное приложение индексатора будет расположено в
Дополнительные инструменты> Утилиты> Справка Indexer.app
Кроме того, macOS не любит, когда у вас есть несколько справочных книг. Это означает наличие нескольких копий вашего приложения на вашем Mac независимо от того, где они находятся. Это может быть ваша папка отладки и папка приложения в качестве наиболее часто используемых мест. Я обнаружил, что удаление копии в папке "Приложения" обычно помогает macOS не запутаться при открытии Справочной книги. Я также обнаружил, что он открывает более старые версии Справочной книги, поэтому лучше убедиться, что у вас есть только одна копия вашего приложения на Mac при отладке справочных книг.

Но кроме этого, они должны нормально открываться с помощью простой строки привязки и нескольких строк кода в зависимости от того, как вы отображаете кнопку справки!