快速访问工具栏
快速访问工具栏 (QAT) 是一个可自定义的小型工具栏，用于公开由应用程序指定或用户选择的一组命令。
简介
默认情况下，快速访问工具栏 (QAT) 位于应用程序窗口的标题栏中，但可以配置为显示在功能区下方。 除了公开命令外，快速访问工具栏 (QAT) 还包括一个可自定义的下拉菜单，其中包含完整的默认快速访问工具栏 (QAT) 命令 (在快速访问工具栏 (QAT) ) 中隐藏或显示，以及一组快速访问工具栏 (QAT) 和功能区选项。
以下屏幕截图显示了 QAT) (功能区快速访问工具栏的示例。
快速访问工具栏 (QAT) 由应用程序 (称为应用程序默认列表) 或用户选择的最多 20 个命令组成。 快速访问工具栏 (QAT) 可以包含功能区 UI 中其他位置不可用的唯一命令。
实现快速访问工具栏
与所有 Windows 功能区框架控件一样，充分利用快速访问工具栏 (QAT) 既需要控制功能区内呈现的标记组件，又需要控制其功能的代码组件。
标记
快速访问工具栏 (QAT) 控件通过 QuickAccessToolbar 元素在标记中声明并与命令 ID 相关联。 命令 ID 用于标识快速访问工具栏 (QAT) 并将其绑定到应用程序定义的命令处理程序。
除了主要快速访问工具栏的基本命令处理程序 (QAT) 功能外，声明可选的 CustomizeCommandNameQuickAccessToolbar 元素属性会导致框架将 更多命令 项添加到快速访问工具栏 (QAT) 下拉菜单中，该菜单需要定义辅助命令处理程序。
为了跨功能区应用程序保持一致，建议 CustomizeCommandName 命令处理程序启动快速访问工具栏 (QAT) 自定义对话框。 由于功能区框架仅在 UI 中提供启动点，因此当收到此命令的回调通知时，应用程序仅负责提供自定义对话框实现。
以下屏幕截图显示了一个快速访问工具栏 (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) Command 集合通过 UI_PKEY_ItemsSource 属性键作为 IUICollection 对象进行检索。 通过将 IUISimplePropertySet 对象添加到 IUICollection，可在运行时将命令添加到快速访问工具栏 (QAT) 。
与命令库不同，快速访问工具栏 (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 持久性
快速访问工具栏 (QAT) 命令项和设置可以使用 IUIRibbon：：SaveSettingsToStream 和 IUIRibbon：：LoadSettingsFromStream 函数跨应用程序会话持久保存。 有关详细信息，请参阅 持久保存功能区状态。
快速访问工具栏属性
功能区框架定义快速访问工具栏 (QAT) 控件 的属性键 集合。
通常，快速访问工具栏 (QAT) 属性通过调用 IUIFramework：：InvalidateUICommand 方法使与控件关联的命令失效，从而在功能区 UI 中更新。 无效事件由 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) 下拉菜单的 “更多命令 ”命令项相关联
相关主题
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈