DataRecordsets.Add 方法 (Visio)
通过连接到 OLEDB 或 ODBC 数据源并从中检索数据，将 DataRecordset 对象添加到 DataRecordsets 集合。
注意
此 Visio 对象或成员仅供 Visio Professional 2013 的授权用户使用。
语法
表达式。添加 (ConnectionIDOrString、 CommandString、 AddOptions、 Name)
表达 一个代表 DataRecordsets 对象的变量。
参数
| 名称 | 必需/可选 | 数据类型 | 说明 |
|---|---|---|---|
| ConnectionIDOrString | 必需 | Variant | 现有 DataConnection 对象的 ID 或用于指定新数据源连接的连接字符串。 |
| CommandString | 必需 | 字符串 | 用于指定数据库表或 Excel 工作表以及表或工作表中包含您要查询的数据的域（列）的查询字符串。 |
| AddOptions | 必需 | Long | 用于确定要添加的数据记录集的属性的选项。 VisDataRecordsetAddOptions 中的一个或多个枚举值的组合。 有关详细信息，请参阅“备注”。 |
| Name | 可选 | 字符串 | 将显示名称分配给要添加的 DataRecordset 对象。 |
返回值
DataRecordset
备注
您可以利用以下方法确定用于传递到 ConnectionIDOrString 参数的适当连接字符串：首先使用 Visio 用户界面 (UI) 中的“数据选取器向导”建立相同的连接，在运行该向导时录制宏，然后从宏代码中复制连接字符串。
重用现有数据连接的一种简单方法是为 ConnectionIDOrString 参数传递现有 DataRecordset 对象的 DataConnection 属性值。 使用以下语法:
NewDataRecordset = DataRecordsets.Add(ExistingDataRecordset .DataConnection.ID, CommandString, AddOptions, Name)
对于 ConnectionIDOrString 参数，如果传递当前由一个或多个其他数据记录集使用的现有 DataConnection 对象的 ID，则所有数据记录集都将成为已处理的组记录集。 每当发生数据刷新操作时，都会刷新组中的所有数据记录集。
AddOptions 参数可以是 VisDataRecordsetAddOptions 枚举（在 Visio 类型库中声明）中的下列值的一个或多个的组合。 默认值是零 (0)，它指定不设置任何选项。
| 常量 | 值 | Description |
|---|---|---|
| visDataRecordsetNoExternalDataUI | 1 | 防止新数据记录集中的数据在“外部数据”窗口中显示。 |
| visDataRecordsetNoRefreshUI | 2 | 防止数据记录集在“刷新数据”对话框中显示。 |
| visDataRecordsetNoAdvConfig | 4 | 防止数据记录集在“配置刷新”对话框中显示。 |
| visDataRecordsetDelayQuery | 8 | 添加数据记录集，但在您下次调用 Refresh 方法之前不执行 CommandString 查询。 |
| visDataRecordsetDontCopyLinks | 16 | 添加数据记录集，但在复制或剪切形状时，形状数据链接不会复制到剪贴板。 |
分配这些值后，在 DataRecordset 对象的生存期内您不能对其进行更改。
Name 参数是一个可选字符串，您可以通过它为数据记录集分配显示名称。 如果您指定在 Visio UI 中显示“外部数据”窗口，您为此参数传递的名称将会出现在“外部数据”窗口中对应于所添加的数据记录集的选项卡上。
如果 Add 方法成功，它将执行以下操作：
创建一个 DataRecordset 对象并为其分配在 Name 参数中指定的名称。 如果未指定名称，Visio 会将作为数据源的数据库表的名称分配给数据记录集。
将一个新的或现有的 DataConnection 对象与 DataRecordset 对象相关联。
除非已设置 visDataRecordsetNoExternalDataUI，否则在 Visio UI 中打开“外部数据”窗口。
除非您将 visDataRecordsetDelayQuery 作为 AddOptions 参数的一部分传递，否则 Add 方法还将执行下列操作：
执行 CommandString 参数中指定的查询字符串并检索生成的数据。
将数据源的列的数据类型映射到等效的 Visio 数据类型，同时筛选结果以删除因没有等效的 Visio 数据类型而无法链接到 Visio 形状的数据源列。 具体而言，您不能导入二进制数据或使用范围很小的数据类型，如 UserDefined、Chapter 和 IDispatch。
将行 ID 分配给数据记录集中的每一行。 有关行 ID 的详细信息，请参阅 DataRecordset.GetDataRowIDs 主题。
注意
当 Add 方法遇到网络连接错误、网络超时或数据库权限错误时，它将失败并返回异常。 如果设置了 visDataRecordsetDelayQuery 选项，则在同样的情况下，Add 可能会成功添加新的数据记录集，而刷新可能会失败。
示例
以下 Microsoft Visual Basic for Applications (VBA) 宏说明了如何使用 Add 方法将 Visio 绘图连接到 ORGDATA.XLS（一个 Microsoft Office Excel 工作簿，在默认文件路径中安装 Visio 时会在 C:\Program Files\Microsoft Office\OFFICE12\SAMPLES\2052\ 中安装它）中的数据。
在此示例中，没有现有数据连接，因此对于 Add 方法的第一个参数，我们将传递 strConnection （连接字符串）。 对于第二个参数，我们传递 strCommand （命令字符串），该字符串指示 Visio 从我们指定的工作表中选择所有列。 对于 Add 方法的第三个参数，我们传递零以指定数据记录集的默认行为，对于最后一个参数，传递 “组织数据” ，即我们要分配给数据记录集的显示名称。
Public Sub AddDataRecordset_Example()
Dim strConnection As String
Dim strCommand As String
Dim strOfficePath As String
Dim vsoDataRecordset As Visio.DataRecordset
strOfficePath = Visio.Application.Path
strConnection = "Provider=Microsoft.ACE.OLEDB.12.0;" _
& "User ID=Admin;" _
& "Data Source=" + strOfficePath + "SAMPLES\1033\ORGDATA.XLS;" _
& "Mode=Read;" _
& "Extended Properties=""HDR=YES;IMEX=1;MaxScanRows=0;Excel 12.0;"";" _
& "Jet OLEDB:Engine Type=34;"
strCommand = "SELECT * FROM [Sheet1$]"
Set vsoDataRecordset = ActiveDocument.DataRecordsets.Add(strConnection, strCommand, 0, "Org Data")
End Sub
支持和反馈
有关于 Office VBA 或本文档的疑问或反馈？ 请参阅 Office VBA 支持和反馈，获取有关如何接收支持和提供反馈的指南。