快速访问工具栏

项目
07/22/2024

快速访问工具栏 (QAT) 是一个小的可自定义工具栏，它公开由应用程序指定或用户选择的一组命令。

介绍
实现快速访问工具栏
- 标记
- 代码
暂留 QAT
快速访问工具栏属性
相关主题

简介

默认情况下，快速访问工具栏 (QAT) 位于应用程序窗口的标题栏中，但可以配置为显示在功能区下方。除了公开命令，快速访问工具栏 (QAT) 还包括一个可自定义的下拉菜单，其中包含完整的默认快速访问工具栏 (QAT) 命令集（无论是隐藏的还是显示在快速访问工具栏 (QAT) 和一组快速访问工具栏 (QAT) 和功能区选项。

以下屏幕截图显示了功能区快速访问工具栏 (QAT) 的示例。

快速访问工具栏 (QAT) 由应用程序（称为应用程序默认列表）或用户选择的最多 20 个命令组合组成。快速访问工具栏 (QAT) 可以包含功能区 UI 中其他地方不可用的唯一命令。

注意

虽然几乎所有功能区控件都允许通过以下屏幕截图中显示的上下文菜单将其关联的命令添加到快速访问工具栏 (QAT)，但上下文弹出窗口中公开的命令不提供此上下文菜单。

Microsoft 画图功能区中命令上下文菜单的屏幕截图。

与所有 Windows 功能区框架控件一样，充分利用快速访问工具栏 (QAT) 需要一个标记组件，该组件控制功能区中的演示文稿，以及控制其功能的代码组件。

标记

快速访问工具栏 (QAT) 控件通过 QuickAccessToolbar 元素在标记中声明并与命令 ID 相关联。命令 ID 用于标识快速访问工具栏 (QAT) 并将其绑定到应用程序定义的命令处理程序。

除了用于主要快速访问工具栏 (QAT) 功能的基本命令处理程序之外，声明可选的 CustomizeCommandName QuickAccessToolbar 元素属性还会导致框架向快速访问工具栏 (QAT) 下拉菜单的命令列表添加 更多命令项，这需要定义辅助命令处理程序。

为了在功能区应用程序中保持一致性，建议使用 CustomizeCommandName 命令处理程序启动快速访问工具栏 (QAT) 自定义对话框。由于 Ribbon 框架只提供用户界面中的启动点，因此当收到该命令的回调通知时，应用程序应自行负责提供自定义对话框的实现。

以下屏幕截图显示了包含更多命令 命令项的快速访问工具栏 (QAT) 下拉菜单。

包含更多命令...命令项的 qat 菜单截图。

快速访问工具栏 (QAT) 的应用程序默认列表是通过 QuickAccessToolbar.ApplicationDefaults 属性指定的，该属性标识建议命令的默认列表，所有这些列表都列在快速访问工具栏 (QAT) 下拉菜单中。

若要在快速访问工具栏 (QAT) 工具栏中显示应用程序默认列表中的命令，每个控件元素的 ApplicationDefaults.IsChecked 属性必须具有一个 true 值。前面的图像显示了将此属性设置为true保存、撤消和重做命令的结果。

QuickAccessToolbar.ApplicationDefaults 支持三种类型的功能区控件：按钮、切换按钮和复选框。

注意

Windows 8 和更新：支持所有基于库的控件（ComboBox、InRibbonGallery、SplitButtonGallery 和 DropDownGallery）。

库控件中的项可以支持悬停时突出显示。若要支持悬停突出显示，库必须是项库并使用 VerticalMenuLayout 类型的 FlowMenuLayout。

以下示例演示了 QuickAccessToolbar 元素的基本标记。

此代码部分显示快速访问工具栏 (QAT) 元素的命令声明。

<Command Name="cmdQAT"
         Symbol="ID_QAT"
         Id="40000"/>
<Command Name="cmdCustomizeQAT"
         Symbol="ID_CUSTOM_QAT"
         Id="40001"/>

此代码部分显示快速访问工具栏 (QAT) 元素的控制声明。

      <Ribbon.QuickAccessToolbar>
        <QuickAccessToolbar CommandName="cmdQAT"
                            CustomizeCommandName="cmdCustomizeQAT">
          <QuickAccessToolbar.ApplicationDefaults>
            <Button CommandName="cmdButton1"/>
            <ToggleButton CommandName="cmdMinimize"
                          ApplicationDefaults.IsChecked="false"/>
          </QuickAccessToolbar.ApplicationDefaults>
        </QuickAccessToolbar>
      </Ribbon.QuickAccessToolbar>

代码

功能区框架应用程序必须提供用于操作快速访问工具栏 (QAT) 的命令处理程序回调方法。此处理程序的工作方式与命令库处理程序类似，但快速访问工具栏 (QAT) 不支持类别。有关详细信息，请参阅使用库。

快速访问工具栏 (QAT) 命令集合通过 UI_PKEY_ItemsSource 属性键作为 IUICollection 对象进行检索。在运行时将命令添加到快速访问工具栏 (QAT) 是通过向 IUICollection 添加 IUISimplePropertySet 对象来完成的。

与命令库不同，快速访问工具栏 (QAT) IUISimplePropertySet 对象不需要命令类型属性 (UI_PKEY_CommandType)。但是，命令必须存在于功能区或快速访问工具栏 (QAT) 应用程序默认列表中；无法在运行时创建新命令，并且无法添加到快速访问工具栏(QAT)。

注意

功能区应用程序无法将快速访问工具栏 (QAT) IUICollection 替换为派生自 IEnumUnknown 的自定义集合对象。

以下示例演示了基本的快速访问工具栏 (QAT) 命令处理程序实现。

/* QAT COMMAND HANDLER IMPLEMENTATION */
class CQATCommandHandler
      : public CComObjectRootEx<CComMultiThreadModel>
      , public IUICommandHandler
{
  public:
    BEGIN_COM_MAP(CQATCommandHandler)
      COM_INTERFACE_ENTRY(IUICommandHandler)
    END_COM_MAP()

    // QAT command handler's Execute method
    STDMETHODIMP Execute(UINT nCmdID,
                         UI_EXECUTIONVERB verb, 
                         const PROPERTYKEY* key,
                         const PROPVARIANT* ppropvarValue,
                         IUISimplePropertySet* pCommandExecutionProperties)
    {
      UNREFERENCED_PARAMETER(nCmdID);
      UNREFERENCED_PARAMETER(verb);
      UNREFERENCED_PARAMETER(ppropvarValue);
      UNREFERENCED_PARAMETER(pCommandExecutionProperties);

      // Do not expect Execute callback for a QAT command
      return E_NOTIMPL;
    }

    // QAT command handler's UpdateProperty method
    STDMETHODIMP UpdateProperty(UINT nCmdID,
                                REFPROPERTYKEY key,
                                const PROPVARIANT* ppropvarCurrentValue,
                                PROPVARIANT* ppropvarNewValue)
    {
      UNREFERENCED_PARAMETER(nCmdID);
      UNREFERENCED_PARAMETER(ppropvarNewValue);

      HRESULT hr = E_NOTIMPL;

      if (key == UI_PKEY_ItemsSource)
      {
        ATLASSERT(ppropvarCurrentValue->vt == VT_UNKNOWN);

        CComQIPtr<IUICollection> spCollection(ppropvarCurrentValue->punkVal);

        UINT nCount;
        if (SUCCEEDED(hr = spCollection->GetCount(&nCount)))
        {
          if (nCount == 0)
          {
            // If the current Qat list is empty, then we will add a few items here.
            UINT commands[] =  { cmdSave, cmdUndo};

            int count = _countof(commands);

            for (int i = 0; i < count; i++)
            {
              PROPERTYKEY keys[1] = {UI_PKEY_CommandId};
              CComObject<CItemProperties> *pItem = NULL;
              if (SUCCEEDED(CComObject<CItemProperties>::CreateInstance(&pItem)))
              {
                PROPVARIANT vars[1];

                InitPropVariantFromUInt32(commands[i], &vars[0]);

                pItem->Initialize(NULL, _countof(vars), keys, vars);

                CComPtr<IUnknown> spUnknown;
                pItem->QueryInterface(&spUnknown);
                spCollection->Add(spUnknown);
                            
                FreePropVariantArray(_countof(vars), vars);
              }
            }
          }
          else
          {
            // Do nothing if the Qat list is not empty.
            // Return S_FALSE to indicate the callback succeeded.
            return S_FALSE; 
          }
        }
      }
    return hr;
  }
};

暂留 QAT

可以使用 IUIRibbon::SaveSettingsToStream 和 IUIRibbon::LoadSettingsFromStream 函数跨应用程序会话保留快速访问工具栏(QAT) 命令项和设置。有关详细信息，请参阅保留功能区状态。

功能区框架定义快速访问工具栏 (QAT) 控件的属性键集合。

通常，通过调用 IUIFramework::InvalidateUICommand 方法使与控件关联的命令失效，在功能区 UI 中更新快速访问工具栏 (QAT) 属性。 IUICommandHandler::UpdateProperty 回调方法处理无效事件并定义属性更新。

IUICommandHandler::UpdateProperty 回调方法不会被执行，并且应用程序会查询更新的属性值，直到框架需要该属性。例如，当选项卡被激活并在功能区 UI 中显示控件时，或显示工具提示时。

注意

在某些情况下，可以通过 IUIFramework::GetUICommandProperty 方法检索属性，并使用 IUIFramework::SetUICommandProperty 方法进行设置。

下表列出了与快速访问工具栏 (QAT) 控件关联的属性键。

属性键	备注
UI_PKEY_ItemsSource	支持 IUIFramework::GetUICommandProperty （不支持 IUIFramework::SetUICommandProperty）。IUIFramework::GetUICommandProperty 返回指向表示 QAT 中命令的 IUICollection 对象的指针。每个命令都由其命令 ID 标识，该 ID 通过调用 IUISimplePropertySet::GetValue 方法并传入属性键 UI_PKEY_CommandId 获取。

没有与快速访问工具栏 (QAT) 下拉菜单中更多命令命令项关联的属性键

通过

简介

标记

代码

暂留 QAT

反馈

其他资源

通过

简介

实现快速访问工具栏

标记

代码

暂留 QAT

快速访问工具栏属性

相关主题

反馈

其他资源