SHAddToRecentDocs 函数 (shlobj_core.h)

  • 项目

通知系统已访问某个项，以便跟踪最近和最常用的项。 此函数还可用于清除所有使用情况数据。

语法

void SHAddToRecentDocs(
                 UINT    uFlags,
  [in, optional] LPCVOID pv
);

参数

uFlags

类型： UINT

SHARD 枚举中的一个值，该值指示 pv 参数指向的信息的形式。

[in, optional] pv

类型： LPCVOID

指向标识已访问的项的数据的指针。 可以在此参数中指定以下形式之一的项：

将此参数设置为 NULL 可清除所有项的所有使用情况数据。

返回值

无

备注

通过调用此方法收集的使用情况统计信息用于确定最近和最常访问的项目列表。 这些列表显示在 “开始” 菜单和 Windows 7 及更高版本中的应用程序跳转列表中。

调用此方法时，它会影响以下方面：

  • 汇报关联应用程序的跳转列表的“最近”和“常用”列表。
  • 将快捷方式添加到用户的“最近”文件夹 (FOLDERID_Recent，CSIDL_RECENT) 。 这反映在 “我最近使用的文档 ” (Windows XP) 和 Windows Vista (“ 最近使用的项目 ”和“ 开始 ”菜单中的“) ”菜单中。
  • 向经典 “开始 ”菜单的“ 文档 ”子菜单添加快捷方式。 (请注意，经典 “开始 ”菜单选项在 Windows 7 及更高版本中不可用。)
由 IShellLink 表示的项目不会添加到 “最近” 文件夹中，尽管它们反映在应用程序的跳转列表中。

在某些情况下，尤其是当用户通过 Windows 资源管理器打开项或使用通用文件对话框打开、保存或创建文件时，Shell 代表应用程序调用 SHAddToRecentDocs 。 具有用于选择项的自定义 UI 的应用程序应显式调用 SHAddToRecentDocs 以确保准确的统计信息。 重复调用由系统负责，因此不存在通过这样做扭曲数据的风险。

可执行 (.exe) 文件从 Windows XP 及更高版本中最近使用的文档列表进行筛选。 尽管 SHAddToRecentDocs 将接受可执行文件的路径，但该文件不会显示在“ 最近使用的项目” 列表中。

SHAddToRecentDocs 也接受文件夹，但仅显示在 Windows 资源管理器任务栏按钮的跳转列表中。 文件夹不会显示在任何其他应用程序的跳转列表中。

在某些情况下， SHAddToRecentDocs 会尝试注册应用程序来处理它未注册要处理的文件类型。 这种情况在以下情况下发生：

  • 应用程序使用未注册处理的文件类型显式调用 SHAddToRecentDocs 。 这也适用于代表应用程序的通用文件对话框对 SHAddToRecentDocs 的调用，但仅当对话框用于打开文件时，而不是用于保存文件时。
  • 用户删除应用程序未在应用程序的任务栏按钮上注册要处理的类型的文件。
此注册按用户完成。

必须满足一组要求才能成功完成注册：

  • 应用程序必须在 HKEY_CLASSES_ROOT\Applications 下注册。
  • 该注册不能包含 NoOpenWith 值。 有关 NoOpenWith 的详细信息，请参阅 文件类型 。
  • 该注册不能在 SupportedTypes 子项下提供数据。 有关 SupportedTypes 子项的详细信息，请参阅文件类型。
  • 无法在此处找到的 KillList 值中列出应用程序的可执行文件：
    HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  FileAssociation
                     KillList
    注意 第三方应用程序不应修改 KillList 值。 它应被视为只读。
     
  • 应用程序的 HKEY_CLASSES_ROOT\Applications 注册必须具有在 下定义的一组默认谓词 HKEY_CLASSES_ROOT\Applications\ExampleApp.exe\shell 子项。

    如果 SHAddToRecentDocs 由于拖放到任务栏按钮上而尝试注册，则只要现有应用程序注册不包含 NoOpenWith 值且应用程序的可执行文件未在 KillList 值中列出，则创建 shell 子项（如果尚不存在）。

禁止调用 SHAddToRecentDocs

在 Windows 7 之前的 Windows 版本中，文件类型可以设置 FTA_NoRecentDocs 标志，以防止将文件类型添加到“ 最近” 文件夹中。 Windows 7 及更高版本也支持此机制。 有关详细信息，请参阅 文件类型 。

SHAddToRecentDocs 通过为访问这些文档而调用的谓词跟踪文档使用情况统计信息。 将跟踪已注册 的 IContextMenu 处理程序提供的谓词，这些项显示在 Windows XP) (“最近使用的文档 ”和“ 最近使用的项 ” (Windows Vista) 中。 在 Windows 7 中，文档的父文件夹显示在 Windows 资源管理器任务栏按钮的跳转列表中。 但是，通过这些 IContextMenu 谓词访问的文档不会显示在应用程序 Jump Lists中。 要使这些项显示在应用程序的跳转列表中，应用程序必须显式调用 SHAddToRecentDocs 。

在 Windows 7 之前，只有 open 谓词导致调用 SHAddToRecentDocs。 在 Windows 7 及更高版本中，其他谓词也可以生成使用情况统计信息。 此信息用于使跳转列表的目标更加完整和准确。

但是，某些文件类型关联注册类或单个 IContextMenu 实现不适用于此类跟踪。 使用情况跟踪的要点是生成用户可能希望再次访问的项列表。 如果特定谓词（delete例如）在用户无法再次访问的项上被调用，或者是辅助操作（例如对文件进行病毒扫描），则该谓词不适合跟踪。 文件类型类应通过注册表项 NoRecentDocs 从此跟踪中删除自身。 NoRecentDocs 的类型为 REG_SZ，没有关联的数据。 其存在是阻止调用 SHAddToRecentDocs 所需的全部内容。

例如，不应跟踪在类“*”、“AllFileSystemObjects”或“Folder”等 HKEY_CLASSES_ROOT 下注册的上下文菜单扩展和静态谓词。 在此类情况下，NoRecentDocs 条目将添加到类键的根目录中，如下所示，以禁止跟踪通过注册到该类的任何谓词或扩展启动的文档：

HKEY_CLASSES_ROOT
   AllFileSystemObjects
      NoRecentDocs

NoRecentDocs 条目默认 *分配给 、 AllFileSystemObjects、 Folder、 Directory 和 DesktopBackground 类子项。

单个 IContextMenu 实现可以选择退出跟踪，方法是在其 shellex 子项中将 NoRecentDocs 子项添加到其组件对象模型 (COM) 对象的注册，如下所示：

HKEY_CLASSES_ROOT
   CLSID
      {093C7AAB-5E72-454f-A91D-CA1BC991FCEC}
         shellex
            NoRecentDocs

默认情况下，此子项在任何 IContextMenu 实现中都不存在。

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 shlobj_core.h (包括 Shlobj.h)
Library Shell32.lib
DLL Shell32.dll (版本 4.0 或更高版本)
API 集 Windows 10版本 10.0.14393 中引入的 ext-ms-win-shell-shell32-l1- (2-2)

另请参阅

SHGetFolderLocation

SHGetFolderPath