Share via

ICustomDestinationList：：AppendCategory 方法 (shobjidl_core.h)

  • 發行項

定義自訂類別及其包含的目的地，以包含在自訂跳躍清單中。

語法

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

參數

[in] pszCategory

類型： LPCWSTR

字串的指標，其中包含自訂類別的顯示名稱。 此字串會顯示在跳躍清單的類別標頭中。 字串可以直接保存顯示名稱，也可以是間接字串標記法，例如 「@shell32.dll，-1324」。 間接字串可讓類別標頭以使用者的選取語言顯示。

注意 每個自訂類別都必須有唯一的名稱。 重複的類別名稱會導致跳躍清單中的簡報問題。
 

[in] poa

類型： 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)
程式庫 Shell32.lib
Dll Shell32.dll (6.1 版或更新版本)

另請參閱

ICustomDestinationList

ICustomDestinationList：：AddUserTasks

ICustomDestinationList：：AppendKnownCategory

工作列延伸模組