在VSTO中以编程方式访问功能区控件 [英] Programmatic access to Ribbon controls in VSTO

问题描述

我正在Visual Studio 2008中使用VSTO编写C#，以便为Office 2007创建外接程序.

I am writing C# with VSTO in Visual Studio 2008 in order to create an add-in for Office 2007.

使用XML定义自定义功能区选项卡后，如何获得对功能区中各种控件的引用?我希望能够以编程方式操作EditBox的内容.

After I have defined a custom ribbon tab using XML, how do I obtain references to the various controls in the Ribbon? I would like to be able to do things like programatically manipulate the content of an EditBox.

推荐答案

无法通过回调直接以编程方式访问功能区控件属性.但是，Visual Studio具有可视的功能区设计器，该设计器确实允许直接访问.我将在下面介绍这两个主题.

Direct programmatic access to ribbon control properties through callbacks is not possible. However, Visual Studio has a visual ribbon designer that does allow direct access. I'll describe both topics below.

使用功能区回调时，项目代码无法与控件对话，而只能侦听.这是一条单向路，并且代码只能等待 IRibbonUI 发送针对用户触发的控制功能的回调请求.

When using ribbon callbacks, project code cannot talk to the controls, it can only listen. It's a one-way street, and the code can only wait for IRibbonUI to send callback requests for whichever control function was triggered by the user.

更改控件属性的唯一方法是重新引导"它.正确的说法是 Invalidate .单个控件或整个程序员定义的自定义功能区都可能无效.这可以通过以下两种方法完成:

The only way to change the properties of a control is to "reboot" it. The proper term for this is Invalidate. Either a single control or the entire programmer-defined custom ribbon may be invalidated. This is done with the following two methods:

Microsoft.Office.Core.IRibbonUI.Invalidate() 
Microsoft.Office.Core.IRibbonUI.InvalidateControl(String) '"SomeControlName"

控件的属性是在首次创建或无效时设置的.首次初始化时，可以在 Ribbon.XML 中设置大多数属性.同样，大多数属性可以在触发控件失效时设置.

The properties of the controls are set when they are first created, or when they are invalidated. Most properties can be set in the Ribbon.XML when they are first initialized. Likewise, most properties can be set when control invalidation is triggered.

这就是诀窍.好吧，实际上这是两个技巧中的第一个.

And that's the trick. Well, actually it's the first of two tricks.

当控件或功能区失效时，其所有回调均被同时触发；这些是 onAction ， getPressed ， getImage ， getLabel 等，或者专门针对此OP:它是用于查询 Microsoft.Office.Tools.Ribbon.RibbonEditBox 控件或任何其他具有文本内容的控件的内容的getText .

When a control or ribbon is invalidated, all of its callbacks are triggered simultaneously; those being onAction, getPressed, getImage, getLabel, etc, or specifically for this OP: it's getText that asks for the contents of a Microsoft.Office.Tools.Ribbon.RibbonEditBox control, or any of the other controls with textual contents.

那是第二个窍门.

类或模块代码必须保留自己的私有变量，以表示功能区控件属性的当前值.然后，当触发控件回调时， IRibbonUI 本质上是在询问属性应该是什么，并且代码应使用所需的值进行回复.

The class or module code must keep its own private variables to represent the current values of ribbon control properties. Then when control callbacks are triggered, IRibbonUI is essentially asking what the properties should be, and the code should reply back with the desired values.

Voilà！简而言之，这就是整个过程.

Voilà!  That's the entire process in a nutshell.

但是...如上所述，还有另一种方法:Ribbon Visual Designer(RVD)，它使用Microsoft Visual Studio Tools for Office(VSTO)作为 wrapper 处理与Ribbon有关的所有事情.这样，它提供了创建事件处理程序的经典"point& doubleclick"技术，这是每个程序员都习惯的.它的作用就像 Windows窗体.只需双击RVD中的任何控件即可直接进入代码中该控件的 _Click 事件.RVD甚至添加了其他功能，例如 Ribbon_Close()事件，可用于诸如保存控件的当前状态之类的事情.

However...as stated above, there's another way: the Ribbon Visual Designer (RVD), which uses Microsoft Visual Studio Tools for Office (VSTO) as a wrapper for everything to do with ribbons. In doing so, it provides the classic "point & doubleclick" technique of creating event handlers which every programmer is accustomed to. It works just like Windows Forms. Simply double-click any control in the RVD to be taken directly to that control's _Click event in the code. The RVD even adds additional functionality, such as the Ribbon_Close() event, which can be used for things like saving the current states of controls.

但是，关于RVD有一个重要意义:仅在针对其设计的应用程序中设置了 RibbonType 属性的情况下，功能区才会出现，未记录..！

But there's an important point to make about the RVD: a ribbon will only appear if its RibbonType property is set for the application in which it's designed for, and some of the values are undocumented..!

RibbonType 值遵循以下常规格式: Microsoft.AppName.MainCommandBarName .记录的值显示在RVD的属性"面板的 RibbonType 框的下拉列表中.其中一些值是:

The RibbonType values follow this general format: Microsoft.AppName.MainCommandBarName. The documented values are seen in the drop-down list of the RibbonType box of the Properties panel the RVD. Some of the values are:

Microsoft.Excel.Workbook
Microsoft.Word.Document
Microsoft.Outlook.Contact 
Microsoft.Outlook.Mail.Read

要在所有这些应用程序中显示RVD功能区，只需启动RVD，设置 RibbonType 属性，添加控件并为事件编写代码.RVD可以处理所有这一切；与 Ribbon.XML 相比，它使使用功能区更加容易.

To have an RVD ribbon appear in any of these apps, one need only start the RVD, set the RibbonType property, add controls, and write code for the events. The RVD handles it all; it makes working with ribbons so much easier than Ribbon.XML.

但是，VSTO仅被提升为可与某些Microsoft Office应用程序一起使用，例如Excel，Word，Outlook等.我提到上述未记录"部分是被提升".VSTO可与许多甚至所有的Microsoft Office应用程序一起使用.只需知道主命令栏名称即可.

But VSTO is only promoted to work with certain Microsoft Office apps, such as Excel, Word, Outlook, etc. I say "promoted" in reference to the "undocumented" part mentioned above. VSTO works with many, perhaps even all of the Microsoft Office apps. One need only know the main commandbar name.

多年来，使用Microsoft Office命令栏和功能区的大多数程序员可能都意识到功能区是从命令栏系统中发展出来的，并采用了某些相同的术语，方法和值.每个命令栏都有一个 Name .如果右键单击命令栏区域，则可以在Visual Studio中看到.有用于 Debug ， Build ， Standard 和其他许多目的的命令栏.而且所有版本的Microsoft Office都有VBA编辑器，该编辑器仍使用经典的命令栏.

Most programmers who've worked with Microsoft Office commandbars and ribbons over the years are probably aware that ribbons grew out of the commandbar system, and adopted some of the same terminology, methods, and values. And every commandbar has a Name. This can be seen right in Visual Studio if the commandbar area is right-clicked. There are commandbars for Debug, Build, Standard, and many other purposes. And all versions of Microsoft Office have the VBA editor, which still uses classic commandbars.

Name 属性是为任何 MSO应用程序创建功能区(不仅仅是已记录的功能区)的关键.名称是将功能区链接到应用程序窗口的名称.大多数窗口都有一个默认的命令栏，该命令栏是几十年前的原始版本的后继命令，在大多数情况下，自Microsoft Office 2003以来是看不到的.我只用Access测试过.将来我可能会对其他一些应用程序大吃一惊.

That Name property is the key to creating ribbons for any MSO application, not just the documented ones. The name is what links a ribbon to the window of the application. Most windows have a default commandbar that descended from the originals decades ago, in most cases not seen since Microsoft Office 2003. Well...maybe. I've only tested it with Access. I may take a whack at some of the other apps in the future.

我将提供一个我现在正在研究的项目的示例:一个用于Word的VSTO加载项，该项目已转换为用于访问的VSTO加载项(

I'll provide an example from a project I'm working on right now: a VSTO Add-In for Word that converted to a VSTO Add-In for Access (process described here). The project has an RVD, and the RibbonType property is set to Microsoft.Access.Database.

注意: RibbonType 的下拉清单可能很棘手.它不喜欢未记录的值.如果键盘焦点在该字段之间切换，并且该值未记录，则将其删除.为了使它固定住，必须通过在其他地方单击鼠标来单击"焦点.可能可以通过某种方式将 Ribbon.Designer.VB 中的 Me.RibbonType =" 重新编码为其他语法，但这可能会干扰设计师，而我还没有尝试过.

Note: The drop-down checklist for RibbonType can be tricky. It doesn't like undocumented values. If the keyboard focus tabs through that field and the value is undocumented, it will be deleted. To make it stick, focus must be "clicked-out" by clicking the mouse somewhere else. It may be possible to somehow re-code Me.RibbonType = "" in Ribbon.Designer.VB to some other syntax, but this may interfere with the normal operation of the designer, and I haven't experimented with it.

我发现这个细节隐藏在设计人员为Visual Studio COM共享加载项创建的原始代码中:

I discovered this detail buried in the original code created by the designer for a Visual Studio COM Shared Add-In:

'Set up a custom button on the "Standard" commandbar.
Try
    oStandardBar = oCommandBars("Standard")
Catch ex As Exception
    'Access names its main toolbar Database.
    oStandardBar = oCommandBars("Database")
End Try

就在那里.大多数MSO应用程序都有一个默认工具栏，称为 Standard ，但对于Access，它是 Database .我一直在为Access RVD尝试各种字符串，但是没有一个起作用:

And there it was. Most of the MSO apps have a default toolbar called Standard, but for Access it's Database. I'd been experimenting with various strings for my Access RVD, but none were working:

Microsoft.Access
Microsoft.Access.Application
Microsoft.Access.Application.ActiveWindow
Etc.

然后我突然有了一个主意，并想起了共享COM加载项中的那段代码，并尝试了以下方法:

Then I had a sudden idea and remembered that bit of code from the Shared COM Add-in and tried these:

Microsoft.Access.Standard
Microsoft.Access.Database

还有宾果游戏..！当我按下 F5 时，我的RVD功能区神奇地出现在Access中.

And bingo..! My RVD ribbon magically appeared in Access when I pressed F5.

很抱歉，如果这篇文章冗长.我希望它可以帮助其他人.

Sorry if this post got long-winded. I hope it may help others.

这篇关于在VSTO中以编程方式访问功能区控件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！