JumpList 类

定义

表示作为菜单显示在 Windows 7 任务栏按钮上的项和任务的列表。Represents a list of items and tasks displayed as a menu on a Windows 7 taskbar button.

public ref class JumpList sealed : System::ComponentModel::ISupportInitialize
[System.Security.SecurityCritical]
[System.Windows.Markup.ContentProperty("JumpItems")]
public sealed class JumpList : System.ComponentModel.ISupportInitialize
type JumpList = class
    interface ISupportInitialize
Public NotInheritable Class JumpList
Implements ISupportInitialize
继承
JumpList
属性
实现

示例

下面的示例演示具有跳转列表的应用程序。The following example shows an application with a Jump List. 该应用程序有三个按钮,可用于向当前跳转列表中添加任务,清除 "跳转列表" 的内容,并将新的跳转列表应用于应用程序。The application has three buttons that enable you to add a task to the current Jump List, clear the contents of the Jump List, and apply a new Jump List to the application.

下面的示例演示如何在标记中声明 JumpListThe following example shows how to declare a JumpList in markup. JumpList 包含两个 JumpTask 链接和一个 JumpPathThe JumpList contains two JumpTask links and one JumpPath. 如果未注册应用程序来处理 .txt 文件扩展名,则将 JumpPath 应用到 shell 将会失败。Applying the JumpPath to the shell will fail if the application is not registered to handle the .txt file name extension.

<Application x:Class="JumpListSample.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             StartupUri="MainWindow.xaml">
    <JumpList.JumpList>
        <JumpList ShowRecentCategory="True"
                  ShowFrequentCategory="True"
                  JumpItemsRejected="JumpList_JumpItemsRejected"
                  JumpItemsRemovedByUser="JumpList_JumpItemsRemovedByUser">
            <JumpTask Title="Notepad" 
                      Description="Open Notepad." 
                      ApplicationPath="C:\Windows\notepad.exe"
                      IconResourcePath="C:\Windows\notepad.exe"/>
            <JumpTask Title="Read Me" 
                      Description="Open readme.txt in Notepad." 
                      ApplicationPath="C:\Windows\notepad.exe"
                      IconResourcePath="C:\Windows\System32\imageres.dll"
                      IconResourceIndex="14"
                      WorkingDirectory="C:\Users\Public\Documents"
                      Arguments="readme.txt"/>
            <JumpPath Path="C:\Users\Public\Documents\readme.txt" />
        </JumpList>
    </JumpList.JumpList>
</Application>

下面的示例演示了 App.xaml的代码隐藏页。The following example shows the code-behind page for App.xaml. 此代码处理 JumpItemsRejectedJumpItemsRemovedByUser 事件。This code handles the JumpItemsRejected and JumpItemsRemovedByUser events.

using System.Text;
using System.Windows;
using System.Windows.Shell;

namespace JumpListSample
{
    /// <summary>
    /// Interaction logic for App.xaml
    /// </summary>
    public partial class App : Application
    {
        private void JumpList_JumpItemsRejected(object sender, System.Windows.Shell.JumpItemsRejectedEventArgs e)
        {
            StringBuilder sb = new StringBuilder();
            sb.AppendFormat("{0} Jump Items Rejected:\n", e.RejectionReasons.Count);
            for (int i = 0; i < e.RejectionReasons.Count; ++i)
            {
                if (e.RejectedItems[i].GetType() == typeof(JumpPath))
                    sb.AppendFormat("Reason: {0}\tItem: {1}\n", e.RejectionReasons[i], ((JumpPath)e.RejectedItems[i]).Path);
                else
                    sb.AppendFormat("Reason: {0}\tItem: {1}\n", e.RejectionReasons[i], ((JumpTask)e.RejectedItems[i]).ApplicationPath);
            }

            MessageBox.Show(sb.ToString());
        }

        private void JumpList_JumpItemsRemovedByUser(object sender, System.Windows.Shell.JumpItemsRemovedEventArgs e)
        {
            StringBuilder sb = new StringBuilder();
            sb.AppendFormat("{0} Jump Items Removed by the user:\n", e.RemovedItems.Count);
            for (int i = 0; i < e.RemovedItems.Count; ++i)
            {
                sb.AppendFormat("{0}\n", e.RemovedItems[i]);
            }

            MessageBox.Show(sb.ToString());
        }
    }
}

下面的示例演示用于创建应用程序用户界面的标记。The following example shows the markup used to create the application user interface.

<Window x:Class="JumpListSample.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Jump List Sample" Height="240" Width="500">
    <Window.Resources>
        <Style TargetType="Button">
            <Setter Property="Width" Value="200" />
            <Setter Property="Margin" Value="5" />
        </Style>
    </Window.Resources>
    <Grid>
        <StackPanel>
            <Button Content="Add Task to JumpList" Click="AddTask" />
            <Button Content="Clear Jump List" Click="ClearJumpList"/>
            <Button Content="Set New Jump List" Click="SetNewJumpList" />
        </StackPanel>
    </Grid>
</Window>

下面的示例演示了 MainWindow.xaml的代码隐藏页。The following example shows the code-behind page for MainWindow.xaml. 此代码演示如何在程序代码中修改、清除和创建 JumpListThis code demonstrates how to modify, clear, and create a JumpList in procedural code. 对于新的跳转列表,将调用静态 SetJumpList 方法,将 JumpList 与当前应用程序相关联,并将 JumpList 应用于 Windows shell。For the new Jump List, the static SetJumpList method is called to associate the JumpList with the current application and apply the JumpList to the Windows shell.

using System;
using System.IO;
using System.Windows;
using System.Windows.Shell;

namespace JumpListSample
{
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }
        private void AddTask(object sender, RoutedEventArgs e)
        {
            // Configure a new JumpTask.
            JumpTask jumpTask1 = new JumpTask();
            // Get the path to Calculator and set the JumpTask properties.
            jumpTask1.ApplicationPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.SystemX86), "calc.exe");
            jumpTask1.IconResourcePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.SystemX86), "calc.exe");
            jumpTask1.Title = "Calculator";
            jumpTask1.Description = "Open Calculator.";
            jumpTask1.CustomCategory = "User Added Tasks";
            // Get the JumpList from the application and update it.
            JumpList jumpList1 = JumpList.GetJumpList(App.Current);
            jumpList1.JumpItems.Add(jumpTask1);
            JumpList.AddToRecentCategory(jumpTask1);
            jumpList1.Apply();
        }
        private void ClearJumpList(object sender, RoutedEventArgs e)
        {
            JumpList jumpList1 = JumpList.GetJumpList(App.Current);
            jumpList1.JumpItems.Clear();
            jumpList1.Apply();
        }
        private void SetNewJumpList(object sender, RoutedEventArgs e)
        {
            //Configure a new JumpTask
            JumpTask jumpTask1 = new JumpTask();
            // Get the path to WordPad and set the JumpTask properties.
            jumpTask1.ApplicationPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.System), "write.exe");
            jumpTask1.IconResourcePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.System), "write.exe");
            jumpTask1.Title = "WordPad";
            jumpTask1.Description = "Open WordPad.";
            jumpTask1.CustomCategory = "Jump List 2";
            // Create and set the new JumpList.
            JumpList jumpList2 = new JumpList();
            jumpList2.JumpItems.Add(jumpTask1);
            JumpList.SetJumpList(App.Current, jumpList2);
        }
    }
}

注解

Windows 7Windows 7 任务栏通过使用跳转列表,为直接从任务栏按钮启动程序提供了增强的功能。The Windows 7Windows 7 taskbar provides enhanced functionality for starting programs directly from the taskbar button by using Jump Lists. "跳转列表" 也用于 Windows 7Windows 7 "开始" 菜单。Jump Lists are also used in the Windows 7Windows 7 Start menu. 您可以通过右键单击任务栏按钮或单击 "开始" 菜单中的程序旁边的箭头来访问跳转列表。You access a Jump List by right-clicking a taskbar button or by clicking the arrow next to a program in the Start menu. 有关 "跳转列表" 的详细信息,请参阅 Windows 用户体验交互指南的 "任务栏" 部分。For more information about Jump Lists, see the Taskbar section of the Windows User Experience Interaction Guidelines.

JumpList 类为 Windows 7Windows 7 任务栏中的跳转列表功能提供托管包装,并管理传递到 WindowsWindows shell 的数据。The JumpList class provides a managed wrapper for the Jump List functionality in the Windows 7Windows 7 taskbar and manages the data passed to the WindowsWindows shell. JumpList 类公开的功能在 Windows 7Windows 7之前的 WindowsWindows 版本中不可用。The functionality exposed by the JumpList class is not available in versions of WindowsWindows earlier than Windows 7Windows 7. 使用 JumpList 类的应用程序将在 WindowsWindows的其他版本中运行,但跳转列表将不可用。Applications that use the JumpList class will run in other versions of WindowsWindows, but the Jump List will not be available. 有关 Windows shell 和本机跳转列表 Api 的详细信息,请参阅任务栏扩展For more information about the Windows shell and native Jump List APIs, see Taskbar Extensions.

下图显示了 Windows Media Player 的跳转列表,其中包含 "任务" 和 "常用" 类别中的项。The following illustration shows the Jump List for Windows Media Player, with items in the Tasks and Frequent categories.

Windows Media Player 跳转列表Windows Media Player Jump List
Windows Media Player 跳跃菜单Windows Media Player Jump List

配置跳转列表Configuring a Jump List

跳转列表可以包含两种类型的项: JumpTaskJumpPathJump Lists can contain two types of items, a JumpTask and a JumpPath. JumpTask 是指向程序的链接,JumpPath 是指向文件的链接。A JumpTask is a link to a program and a JumpPath is a link to a file. 您可以通过创建没有 TitleCustomCategory 指定的 JumpTask,直观地分隔跳转列表中的项。You can visually separate items in a Jump List by creating a JumpTask that does not have a Title and CustomCategory specified. 此空 JumpTask 将在跳转列表中显示为水平线。This empty JumpTask will be displayed as a horizontal line in the Jump List.

备注

如果未向应用程序注册 JumpPath 中指定的文件类型,则该文件将不会显示在跳转列表中。If the type of the file specified in a JumpPath is not registered with your application, the file will not appear in the Jump List. 例如,如果添加指向 .txt 文件的 JumpPath,则必须注册应用程序以处理 .txt 文件。For example, if you add a JumpPath that points to a .txt file, your application must be registered to handle .txt files. 有关详细信息,请参阅文件关联简介For more information, see Introduction to File Associations.

跳转项置于 JumpList的类别中。Jump items are placed into categories in the JumpList. 默认情况下,JumpItem 显示在“任务”类别中。By default, a JumpItem is displayed in the Tasks category. 或者,您可以为 JumpItem指定 CustomCategoryAlternatively, you can specify a CustomCategory for the JumpItem.

通过设置 ShowRecentCategoryShowFrequentCategory 属性,可以指定是否在 JumpList 中显示标准的最近频繁的类别。You can specify whether the standard Recent and Frequent categories are displayed in the JumpList by setting the ShowRecentCategory and ShowFrequentCategory properties. 这些类别的内容由 WindowsWindows shell 管理。The contents of these categories are managed by the WindowsWindows shell. 由于这些类别可能包含很多相同的数据,因此你通常会在 JumpList中显示其中一种,但不能同时显示两者。Because these categories might contain much of the same data, you typically display one or the other in your JumpList, but not both. 如果通过公共文件对话框打开最近的项,或通过文件类型关联来打开应用程序,WindowsWindows 会自动管理这些项。WindowsWindows automatically manages recent items if they are opened through a common file dialog box or used to open an application through file type association. 通过跳转列表访问项时,可以通过调用 AddToRecentCategory 方法通知 WindowsWindows shell 将该项添加到最近的类别。When an item is accessed through the Jump List, you can notify the WindowsWindows shell to add the item to the Recent category by calling the AddToRecentCategory method.

将跳转列表应用于 Windows ShellApplying a Jump List to the Windows Shell

不能直接访问 shell 的跳转列表,也不能将其内容读入到 JumpList 类中。You cannot access the shell's Jump List directly or read its contents into the JumpList class. 相反,JumpList 类提供可以使用的跳转列表的表示形式,然后应用于 WindowsWindows shell。Instead, the JumpList class provides a representation of a Jump List that you can work with, and then apply to the WindowsWindows shell. 通常创建一个 JumpList 并在应用程序首次运行时将其设置一次。You typically create a JumpList and set it one time when the application is first run. 不过,您可以在运行时修改或替换 JumpListHowever, you can modify or replace the JumpList at run time.

设置 JumpList 属性后,必须先将 JumpList 应用到 Windows shell,然后它的内容才会显示在任务栏跳转列表中。When you have set the JumpList properties, you must apply the JumpList to the Windows shell before its contents appear in the taskbar Jump List. JumpList 首次附加到应用程序时(在 XAML 中或在调用 SetJumpList 方法时),将自动执行此操作。This is done automatically when the JumpList is first attached to an application, either in XAML or in a call to the SetJumpList method. 如果在运行时修改 JumpList 的内容,则必须调用 Apply 方法将其当前内容应用到 Windows shell。If you modify the contents of the JumpList at run time, you must call the Apply method to apply its current contents to the Windows shell.

在 XAML 中设置跳转列表Setting a Jump List in XAML

JumpList 不会自动附加到 Application 对象。A JumpList is not automatically attached to an Application object. 通过使用附加的属性语法,可以在 XAML 中将 JumpList 附加到 Application 对象。You attach a JumpList to an Application object in XAML by using the attached property syntax. JumpList 类实现 ISupportInitialize 接口以支持 JumpList的 XAML 声明。The JumpList class implements the ISupportInitialize interface to support XAML declaration of a JumpList. 如果 JumpList 在 XAML 中声明并附加到当前 Application,则在初始化该 JumpList 时,它会自动应用到 WindowsWindows shell。If the JumpList is declared in XAML and attached to the current Application, it is automatically applied to the WindowsWindows shell when the JumpList is initialized.

设置和修改代码中的跳转列表Setting and Modifying a Jump List in Code

通过调用静态 SetJumpList 方法,在代码中将 JumpList 附加到 Application 对象。You attach a JumpList to an Application object in code by calling the static SetJumpList method. 这还会将 JumpList 应用到 WindowsWindows shell。This also applies the JumpList to the WindowsWindows shell.

若要在运行时修改 JumpList,请调用 GetJumpList 方法以获取当前附加到 ApplicationJumpListTo modify a JumpList at run time, you call the GetJumpList method to get the JumpList that is currently attached to an Application. 在修改了 JumpList的属性后,必须调用 Apply 方法将更改应用到 Windows shell。After you have modified the properties of the JumpList, you must call the Apply method to apply the changes to the Windows shell.

备注

通常会创建一个附加到 Application 并应用于 WindowsWindows shell 的 JumpListYou typically create one JumpList that is attached to the Application and applied to the WindowsWindows shell. 但是,可以创建多个 JumpList 对象。However, you can create multiple JumpList objects. 一次只能将一个 JumpList 应用于 WindowsWindows shell,一次只能将一个 JumpListApplication关联。Only one JumpList at a time can be applied to the WindowsWindows shell, and only one JumpList at a time can be associated with an Application. .NET Framework 不要求这些是相同的 JumpListThe .NET Framework does not require that these be the same JumpList.

备注

此类包含类级别的链接要求,该请求应用于所有成员。This class contains a link demand at the class level that applies to all members. 当直接调用方不具有完全信任权限时,将引发 SecurityExceptionA SecurityException is thrown when the immediate caller does not have full-trust permission. 有关安全要求的详细信息,请参阅链接要求继承要求For more information about security demands, see Link Demands and Inheritance Demands.

构造函数

JumpList()

初始化 JumpList 类的新实例。Initializes a new instance of the JumpList class.

JumpList(IEnumerable<JumpItem>, Boolean, Boolean)

使用指定的参数初始化 JumpList 类的新实例。Initializes a new instance of the JumpList class with the specified parameters.

属性

JumpItems

获取在跳转列表中显示的 JumpItem 对象的集合。Gets the collection of JumpItem objects that are displayed in the Jump List.

ShowFrequentCategory

获取或设置一个值,该值指示常用项是否显示在跳转列表中。Gets or sets a value that indicates whether frequently used items are displayed in the Jump List.

ShowRecentCategory

获取或设置一个值,该值指示最近使用的项是否显示在跳转列表中。Gets or sets a value that indicates whether recently used items are displayed in the Jump List.

方法

AddToRecentCategory(JumpPath)

将指定的跳转路径添加到跳转列表的“最近”类别中。Adds the specified jump path to the Recent category of the Jump List.

AddToRecentCategory(JumpTask)

将指定的跳转任务添加到跳转列表的“最近”类别中。Adds the specified jump task to the Recent category of the Jump List.

AddToRecentCategory(String)

将指定的项路径添加到跳转列表的“最近”类别中。Adds the specified item path to the Recent category of the Jump List.

Apply()

在其当前状态下将 JumpList 发送到 Windows shell 中。Sends the JumpList to the Windows shell in its current state.

BeginInit()

用信号通知 JumpList 初始化开始。Signals the start of the JumpList initialization.

EndInit()

用信号通知 JumpList 初始化结束。Signals the end of the JumpList initialization.

Equals(Object)

确定指定的对象是否等于当前对象。Determines whether the specified object is equal to the current object.

(继承自 Object)
GetHashCode()

用作默认哈希函数。Serves as the default hash function.

(继承自 Object)
GetJumpList(Application)

返回与某个应用程序关联的 JumpList 对象。Returns the JumpList object associated with an application.

GetType()

获取当前实例的 TypeGets the Type of the current instance.

(继承自 Object)
MemberwiseClone()

创建当前 Object 的浅表副本。Creates a shallow copy of the current Object.

(继承自 Object)
SetJumpList(Application, JumpList)

设置与应用程序关联的 JumpList 对象。Sets the JumpList object associated with an application.

ToString()

返回一个表示当前对象的 string。Returns a string that represents the current object.

(继承自 Object)

事件

JumpItemsRejected

在 Windows shell 将跳转项添加到跳转列表中失败时发生。Occurs when jump items are not successfully added to the Jump List by the Windows shell.

JumpItemsRemovedByUser

在用户从跳转列表中移除以前位于该列表中的跳转项时发生。Occurs when jump items previously in the Jump List are removed from the list by the user.

安全性

UIPermission
用于修改 Windows shell 的完全访问权限。for full access to modify the Windows shell. 安全操作: LinkDemandSecurity action: LinkDemand. 关联的枚举: AllWindowsAssociated enumeration: AllWindows

适用于