ITaskbarList3：：SetProgressState 方法 (shobjidl_core.h)

项目
08/26/2023

设置任务栏按钮上显示的进度指示器的类型和状态。

语法

HRESULT SetProgressState(
  [in] HWND    hwnd,
  [in] TBPFLAG tbpFlags
);

参数

[in] hwnd

类型：HWND

显示操作进度的窗口的句柄。此窗口的关联任务栏按钮将显示进度栏。

[in] tbpFlags

类型： TBPFLAG

控制进度按钮当前状态的标志。仅指定以下标志之一：所有状态都是相互排斥的。

TBPF_NOPROGRESS (0x00000000)

停止显示进度并将按钮返回到其正常状态。使用此标志调用此方法，以在操作完成或取消时关闭进度栏。

TBPF_INDETERMINATE (0x00000001)

进度指示器的大小不会增加，但会重复沿任务栏按钮的长度循环。这表示活动未指定完成进度的比例。正在取得进展，但无法预测操作需要多长时间。

TBPF_NORMAL (0x00000002)

进度指示器的大小从左到右增长，与估计完成的操作量成比例。这是一个确定的进度指示器：正在对操作持续时间进行预测。

TBPF_ERROR (0x00000004)

进度指示器变为红色，表示在其中一个正在广播进度的窗口中发生了错误。这是一个确定的状态。如果进度指示器处于不确定状态，则会切换到红色确定性显示，其中泛型百分比不指示实际进度。

TBPF_PAUSED (0x00000008)

进度指示器变为黄色，表示进度当前在其中一个窗口中已停止，但用户可以恢复。不存在错误条件，并且没有任何内容阻止进度继续。这是一个确定的状态。如果进度指示器处于不确定状态，则会切换到黄色确定性显示，其中泛型百分比不指示实际进度。

返回值

类型： HRESULT

如果该方法成功，则返回 S_OK。否则，将返回 HRESULT 错误代码。

注解

进度栏信息不会以高对比度配色方案显示，以确保不会泄露辅助功能需求。

习惯于现有进度栏控件的开发人员应发现任务栏按钮进度指示器在概念和视觉对象方面都是类似的体验。在这里，任务栏按钮本身将成为进度栏。任务栏按钮的进度指示器应反映关联窗口中更详细的进度栏。这允许用户查看无法显示在任务栏按钮中的细节，例如百分比数字和剩余时间量。此外，由于任务栏按钮只能显示组中单个窗口的进度，因此允许用户检查单个窗口的进度。当任务栏按钮无法显示时，它还向用户提供进度信息，例如采用高对比度配色方案。

请注意，任务栏按钮进度栏不适用于通常的外围操作，例如加载网页或打印文档。该类型的进度应继续显示在窗口的状态栏中。

进度指示器显示在任务栏按钮的图标或文本与背景之间。如果同时显示活动任务栏按钮和非活动按钮的进度，则相应进度栏中的底纹使用户仍然清楚地看到活动按钮。此外，当按钮用于显示进度时，按钮功能（例如缩略图的显示）将继续正常工作。

退出错误或暂停状态时，请使用 TBPF_NORMAL 或 TBPF_INDETERMINATE 标志再次调用此方法，以继续处于原始状态;如果取消操作， 则TBPF_NOPROGRESS 。

任务栏按钮如何为组选择进度指示器

任务栏按钮一次只能显示一个窗口的进度指示器。这包括任务栏按钮表示组且该组中的多个窗口正在广播进度信息的情况。在这种情况下，任务栏按钮会根据状态优先级选择其进度显示。下表显示了状态优先级，优先级 1 为最高。

优先级	状态
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

更改窗口的状态会相对于组中其他窗口更改其优先级，这反过来又可能会更改组中哪个窗口用于任务栏按钮中的进度指示器。

在广播确定进度的两个窗口之间发生优先级冲突时，将使用进度最少的窗口。

基于此优先级，不确定进度指示器只能在以下情况下显示在任务栏按钮中：

任务栏按钮不表示组，它所代表的单个窗口已设置TBPF_INDETERMINATE。
任务栏按钮表示一个组，该组中只有一个窗口正在广播进度信息，并且该窗口已设置 TBPF_INDETERMINATE。
任务栏按钮表示一个组，该组中的多个窗口正在广播进度信息，所有这些窗口都设置了 TBPF_INDETERMINATE。

在以下情况下，可以显示确定性进度指示器：

任务栏按钮不表示组，它表示的单个窗口正在广播确定的进度信息。
任务栏按钮表示一个组，该组中只有一个窗口正在广播进度信息，该窗口正在广播确定的进度信息。
任务栏按钮表示一个组，该组中的多个窗口正在广播进度信息，其中至少有一个窗口正在广播确定的进度信息，并且没有设置 TBPF_ERROR 或 TBPF_PAUSED窗口。

请注意，调用 SetProgressValue 会将当前处于不确定模式的进度指示器 (TBPF_INDETERMINATE) 切换到正常 (确定) 显示并清除 TBPF_INDETERMINATE 标志。

要求


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