Метод ICustomDestinationList::AppendKnownCategory (shobjidl_core.h)

Статья
03/02/2024

Указывает, что категория "Частые" или "Последние " должна быть включена в настраиваемый список переходов.

Синтаксис

HRESULT AppendKnownCategory(
  [in] KNOWNDESTCATEGORY category
);

Параметры

[in] category

Тип: KNOWNDESTCATEGORY

Одно из следующих значений, указывающих, какую известную категорию добавить в список:

KDC_FREQUENT (1)

0x1. Добавьте категорию Часто .

KDC_RECENT (2)

0x2. Добавьте категорию Последние .

Возвращаемое значение

Тип: HRESULT

Возвращает S_OK в случае успешного выполнения или значение ошибки в противном случае.

Если имеется групповая политика конфиденциальности или параметр конфиденциальности пользователя, это может повлиять на результат этого метода. Категории, содержащие элементы для конкретных пользователей, основанные на индивидуальном использовании, не допускаются в соответствии с этими параметрами конфиденциальности. В связи с этим категории Последние или Частые , добавленные с помощью этого метода, не будут содержать данных, а категории без данных не отображаются. Однако в такой ситуации этот вызов метода не приведет к сбою кода.

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

При использовании AppendCategory и AppendKnownCategory настраиваемый список переходов должен быть разработан таким образом, чтобы избежать появления элементов в нескольких категориях. Если две категории представляют собой просто разные представления одних и тех же данных, одну из этих категорий следует удалить, так как она использует пространство списка переходов, не способствуя удобству пользователя. Дубликаты не скрыты системой, за исключением случаев закрепленного назначения. В этом случае это назначение отображается в категории Закрепленные и скрыто во всех остальных.

Категории "Часто" и "Последние ", скорее всего, содержат определенную степень перекрытия, поэтому не следует добавлять обе категории в один список переходов. Какой из двух вариантов лучше подходит для вашего приложения, зависит от его характера. Приложение, которое создает файлы, например Microsoft Word или Microsoft Paint, должно использовать категорию Последние, так как пользователи, скорее всего, захотят вернуться к файлам, с которыми они недавно работали. Приложение, которое больше используется для просмотра или воспроизведения данных, созданных в другом месте, должно использовать категорию Часто, так как пользователь с большей вероятностью сможет получить доступ к большему количеству элементов, многие из которых будут доступны только один раз. Иными словами, если ваше приложение, скорее всего, будет обращаться к большому количеству элементов только несколько раз, что приводит к помехам для меньшего набора элементов, к которым пользователи хотят получить доступ много раз, то лучшим вариантом будет частый . Если приложение с большей вероятностью будет получать доступ к меньшему количеству новых элементов большую часть времени, следует выбрать последние.

Категории в настраиваемом списке переходов, включая известную категорию "Последние " или "Частые ", отображаются в порядке их добавления, а последние добавленные категории находятся в нижней части списка.

Любое количество назначений, добавленных над значением, на которое указывает параметр pcMinItems в ICustomDestinationList::BeginList , не отображается.

Пустые категории не отображаются.

Содержимое категорий "Частые" и "Последние " вычисляется для каждого приложения, которое напрямую использует SHAddToRecentDocs . В некоторых случаях действий пользователя, таких как открытие файла через Windows Обозреватель или использование общего диалогового окна файла для открытия, сохранения или создания файла, оболочка вызывает SHAddToRecentDocs от имени приложения, и эти вызовы также учитываются в статистике использования. Оболочка также вызывает SHAddToRecentDocs от имени приложения при запуске назначения из его списка переходов. Однако для приложения рекомендуется явным образом вызывать shAddToRecentDocs , даже если ожидается, что оболочка выполнит вызов. Это гарантирует, что использование будет записано, а алгоритмы отслеживания недавнего или частого использования будут исправляться для всех повторяющихся вызовов.

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	shobjidl_core.h (включая Shobjidl.h)
Библиотека	Shell32.lib
DLL	Shell32.dll (версия 6.1 или более поздняя)