ICustomDestinationList：：AppendCategory 方法 (shobjidl_core.h)

  • 项目

定义自定义类别及其包含的目标，以包含在自定义跳转列表中。

语法

HRESULT AppendCategory(
  [in] LPCWSTR      pszCategory,
  [in] IObjectArray *poa
);

参数

[in] pszCategory

类型： LPCWSTR

指向包含自定义类别的显示名称的字符串的指针。 此字符串显示在跳转列表的类别标头中。 字符串可以直接保存显示名称，也可以是间接字符串表示形式，例如“@shell32.dll，-1324”，以使用存储的字符串。 间接字符串允许以用户所选语言显示类别标头。

注意 每个自定义类别必须具有唯一的名称。 重复的类别名称将导致跳转列表中出现呈现问题。
 

[in] poa

类型： IObjectArray*

指向 IObjectArray 的指针，该 IObjectArray 代表类别中目标的一个或多个 IShellItem 对象。 列表中的某些目标也可能由 IShellLink 对象表示，尽管频率较低。

注意 此处使用的任何 IShellLink 都必须通过 SetArguments 声明参数列表。 不支持将没有参数的 IShellLink 对象添加到自定义类别，因为用户无法从跳转列表中固定或取消固定此类项，也不能添加或删除它们。
 

返回值

类型： HRESULT

如果成功，则返回 S_OK，否则返回错误值。

如果对 AppendCategory 的调用尝试添加由启动会话的 BeginList 调用检索的已删除目标列表中的项，则对 AppendCategory 的调用将失败。

如果 AppendCategory 尝试添加应用程序未注册处理的 IShellItem ，调用将失败。

如果启用了隐私组策略或用户隐私设置，AppendCategory 可能会失败。 自定义类别包含基于个人使用情况的用户特定项目，这些隐私设置不允许这些项。

隐私组策略或用户隐私设置不会导致任何其他 ICustomDestinationList 方法失败。 任务不是特定于用户的。 AppendKnownCategory 不会导致显示 “最近” 或“ 常用 ”类别，因为它们没有数据，但方法调用不会返回失败代码。

如果 AppendCategory 中由于隐私组策略或用户隐私设置 (E_ACCESSDENIED) 导致代码失败，应用程序应继续更新任务并调用 CommitList。

如果未找到关联应用程序的文件类型注册， AppendCategory 将返回 HRESULT 0x80040F03。 这可能导致应用程序未注册它尝试添加到跳转列表的文件类型，或者注册中存在问题，例如，当应用程序使用显式 AppUserModelID 时未提供 AppUserModelID。

注解

在调用此方法之前，必须调用 BeginList 。

如果应用程序提供自定义类别，该应用程序负责填充它。 类别内容仍应特定于用户且基于用户的历史记录和操作，但通过使用自定义类别，应用程序可以确定要跟踪的内容和要忽略的内容。 例如，选择不同的应用程序选项时，可能会涉及不同的方案。 例如，音频程序可能会选择仅包含最近播放的专辑，并忽略最近播放的单个曲目。 应用程序可能也只是具有一种针对其特定用途定制的使用情况跟踪算法，该算法提供的结果比系统的默认算法更好。

应用程序可以在列表生成会话中多次调用 AppendCategory 以添加多个自定义类别。 在这种情况下，应设计类别，使其内容互斥。 每个自定义类别都应围绕特定方案构建，以便项目不会在它们之间重复。

自定义跳转列表中的类别（包括已知的 “最近” 或“ 常用 ”类别）按添加顺序显示，最新项将添加到列表末尾。 如果空间不足，无法显示所有条目，列表中的最后一个条目将首先消失在屏幕上。 因此，应首先添加最重要的类别，以确保始终显示它们的最佳机会。 类别中的目标按 poa 指向的 IObjectArray 对象中的存储顺序显示。

用户可能决定将自定义类别中提供的一个或多个目标固定到跳转列表。 固定目标列表对应用程序不可用，但 UI 会阻止重复，因此不需要对应用程序执行额外的操作。 从视觉上看，固定项将移动到跳转列表的 “固定 ”部分，并从其原始位置消失。

成功调用 AppendCategory 并不能保证显示这些项目。 不显示通过 ICustomDestinationList：：BeginList 中的 pcMinItems 参数指向的值添加的任意数量的目标。 固定类别优先于所有其他目标列表。 显示 “固定 ”列表，然后将剩余空间分配给其他目标列表。 用户可以将足够多的目标固定到跳转列表，以阻止显示任何其他目标。 其他因素（如屏幕分辨率降低或字号增加）也可能导致应用程序提供的目标从列表中截断。 应用程序无法预测这些情况，并且不会在发生这些情况时收到通知。 应用程序必须知道存在这种可能性。 由于从下到上截断了一个或多个目标列表，因此应用程序应将其最重要的类别和目标置于列表顶部，以便它们最有可能被显示。

在以 BeginList 开始并以 CommitList 结束的会话期间，可以多次调用 AppendCategory 。 如果其中任一调用因尝试添加包含已删除项目列表中的项的类别而失败，则对 CommitList 的调用不会清除已删除的项目列表。 要清除已删除的项列表，会话中对 AppendCategory 的所有调用都必须成功返回。

通过 poa 指向的 IObjectArray 提供的 IShellLink 实例必须提供以下内容：

必须通过项目的 System.Title (PKEY_Title) 属性设置显示名称。 属性可以直接保存显示名称，也可以是间接字符串表示形式（如“@shell32.dll，-1324”）以使用存储的字符串。 间接字符串允许以用户所选语言显示项名称。

（可选）可以将 SetDescription) (说明字段设置为为跳转列表中的项提供自定义工具提示。

要求

   
最低受支持的客户端 Windows 7 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 R2 [仅限桌面应用]
目标平台 Windows
标头 shobjidl_core.h (包括 Shobjidl.h)
Library Shell32.lib
DLL Shell32.dll (6.1 或更高版本)

另请参阅

ICustomDestinationList

ICustomDestinationList：：AddUserTasks

ICustomDestinationList：：AppendKnownCategory

任务栏扩展