自动查询提供程序

版本 2.384.99 起经由 Windows 上的 XLSX 工作簿门面可用；自动提供程序选择只在显式查询刷新期间发生

刷新既有查询

Workbook.QueryProviders.BaseDirectory := 'C:\Data';
Workbook.QueryProviders.MaxInputBytes := 64 * 1024 * 1024;
Workbook.QueryProviders.MaxResultCells := 2000000;
Workbook.QueryProviders.TimeoutSeconds := 30;
Status := Sheet.RefreshQueryTable('ImportedData', 1000000);

TXLSXWorkbook.QueryProviders: TXLSQueryProviderDispatcher 从 lxQueryProviders 暴露一个工作簿持有的调度器；不要释放该调度器

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer 与接受从零开始 AIndex 的重载会选中既有查询并使用这个调度器

接受显式 TXLSQueryTableProvider 的既有重载继续直接使用该提供程序，包括它们对缺失提供程序的既有拒绝行为；不会回退到自动调度

刷新在成功时返回 1，取消时返回 0，失败时返回 -1，并在 xlsOperationRefresh 下给出诊断码 1401 与 1400；既有的事务性结果应用、模式校验、字面字符串与格式化行为保持不变

这些诊断的名称是 xlsDiagnosticQueryRefreshCancelled 与 xlsDiagnosticQueryRefreshFailed；工作簿写入保护在状态转换之前获取，因此冻结的读取视图或其他写入保护拒绝会抛出异常

打开和保存工作簿从不抓取连接数据、不求值查询，也不会处理保留的 RefreshOnLoad 元数据；保存前请显式刷新每个需要的查询

受支持的内置提供程序

xlckText 读取本地分隔符或固定宽度文本，严格按 UTF-8、UTF-16LE、UTF-16BE、Windows-1252 或 Latin-1 解码，支持配置的起始行，字段类型包括六种日期顺序和可跳过的字段；分隔符输入还支持带引号的多行记录
xlckAdo、xlckOleDb 与 xlckOdbc 使用已安装的 Windows ADO 和数据库驱动，连接与记录集均为只读；CommandType = 2 选择 SQL 文本，CommandType = 3 选择表命令
xlckWeb 使用 Windows WinHTTP 对一个非空矩形 HTML 表做匿名 HTTP 或 HTTPS GET，按正索引或名称选中该表；支持的响应字符集为 UTF-8、UTF-16、Windows-1252 与 Latin-1

BaseDirectory 只为相对本地文本路径提供基目录；数据库连接字符串与 Web URL 仍是显式的连接元数据

未指定文本编码时只接受纯 ASCII 输入，除非受支持的字节顺序标记识别出了编码；非 ASCII 输入需要显式给出受支持的编码或字节顺序标记

对分隔符类 Text 连接，设置 TextPrompt = False、TextDelimited = True 并恰好指定一个分隔符，不折叠连续分隔符；新建连接默认提示并使用制表符分隔，所以换用其他分隔符时要清掉 TextTab

固定宽度文本

设置 TextPrompt = False 与 TextDelimited = False，然后按严格递增的从零开始 Position 顺序添加 TextFields，从零开始；每个字段在下个位置或物理记录终止符处结束，xltiftSkip 会把其字段排除在结果之外

位置按解码后的 UTF-16 码元计数，而不是输入字节；切开代理对的位置会被拒绝，CRLF、LF 与 CR 终止记录时独立于分隔符和限定符设置

转换前会先裁剪字段填充，包括显式指定为文本类型的字段，与经过验证的原生固定宽度导入行为一致；字段内部的引号、制表符和分隔符字符保持字面输入，不足的记录以空尾部字段补齐，不改变声明的模式

没有 TextFields 时每条记录就是一个常规字段；TextFirstRow 选择首条模式记录，Query.Headers 跳过该记录的值，显式的空白记录仍是行

既有的行数、输入字节、结果单元格与 32767 码元字段限制照常适用；无效元数据、转换失败或超限输入会在事务性工作表更新之前清掉暂存数据，取消则保留旧的结果单元格

Connection.TextPrompt := False;
Connection.TextDelimited := False;
Connection.TextFields.Add(xltiftGeneral, 0);
Connection.TextFields.Add(xltiftText, 8);
Status := Sheet.RefreshQueryTable('Imported');

对 Web 连接，设置 WebHtmlTables = True 与 WebHtmlFormat = 'none'；受支持的请求会拒绝内嵌凭据、片段、身份验证和重定向

内置提供程序会在各自连接类别内拒绝不受支持的元数据；数据库刷新拒绝 OLAP 或服务器命令、连接文件间接引用、存储密码和凭据提示，Text 刷新拒绝文件提示，Web 刷新要求匿名的表元数据

类型化数据库参数

SQL 文本命令支持经 ADO Command 绑定的位置 ? 标记，顺序按 Connection.Parameters；参数值从不替换 SQL 文本，名称只用于标注绑定，不改变位置顺序

预检会统计单引号字符串、双引号或反引号标识符、方括号标识符、行注释与嵌套块注释之外的标记，包括成双的引号或方括号转义；引号或注释不匹配、标记数不匹配都会在打开连接前拒绝

使用 ParameterType = 'value' 配显式 ValueKind（xlcpvInteger、xlcpvDouble、xlcpvBoolean 或 xlcpvString）及对应的值属性；零、False 和空字符串都是值，xlcpvNone 在执行期间不推断值

Connection.CommandType := 2;
Connection.CommandText := 'SELECT Amount FROM Sales WHERE Amount > ?';
with Connection.Parameters.Add do
begin
  Name := 'MinimumAmount';
  ParameterType := 'value';
  ValueKind := xlcpvInteger;
  IntegerValue := 0;
  SqlType := 4;
end;
Status := Sheet.RefreshQueryTable('SalesQuery');

单元格绑定使用 ParameterType = 'cell'、ValueKind = xlcpvCell 与 CellReference，指向完全限定的本地工作表引用，例如 Inputs!$A$1 或 'Sales Input'!B2；带引号的表名使用成双撇号，而区域、外部工作簿、名称和未限定的单元格引用都会被拒绝

工作表刷新会在不重算、不物化打包单元格的前提下对存储的标量值和可用的公式缓存做快照；缺失公式缓存与错误单元格会被拒绝，缺失或空白的单元格只有在显式给出受支持 SQL 类型时才提供 SQL null

单元格快照保留其 Variant 类型，可以有符号 Int64、Currency、类型化日期和 null 输入，不会被降级成持久化的 32 位整数或 Double 字面量字段；直接存储的日期、null 与 Int64 字面量超出原生参数元数据模型，这类值请使用类型化单元格绑定

SqlType 使用 ODBC SQL 类型代码，并显式映射到 ADO 类型；它不是 ADO DataTypeEnum 值

SQL 类型代码	接受的值与绑定契约
`0`	从显式字面量类别或原始单元格 Variant 推断：整数、有符号 Int64、Single、Double、Currency、Boolean、日期或 Unicode 字符串；null 需要显式 SQL 类型
`4`, `5`, `-5`	INTEGER、SMALLINT 与 BIGINT，要求精确的整数值并做有符号目标范围校验
`7`, `8`, `6`	REAL、DOUBLE 与 FLOAT；仅接受数值输入，整数到浮点无损转换，REAL 要求精确的 Single 转换
`-7`	BIT 接受布尔值，不做数字或字符串强制转换
`-8`, `-9`, `-10`	Unicode 的 CHAR、VARCHAR 与 LONGVARCHAR 保留 UTF-16 字符串，包括空字符串
`1`, `12`, `-1`	非 Unicode 的 CHAR、VARCHAR 与 LONGVARCHAR 只接受 ASCII 字符串；其他字符请使用 Unicode 类型
`91`, `92`, `93`, 或旧式 `9`, `10`, `11`	DATE、TIME 与 TIMESTAMP 接受类型化日期 Variant，不解析文本也不猜测 Excel 纪元；DATE 拒绝时间分量，TIME 要求值落在零（含）到一（不含）之间

受支持的显式类型同样接受 SQL null；数组、引用 Variant、错误、非有限数、不受支持的 SQL 类型以及会丢失整数精度的转换都会被拒绝，NUMERIC 与 DECIMAL 需要这份绑定 API 不提供的精度与小数位元数据

ADO 收到类型化值与声明大小，空文本也至少分配一个码元；SQL 方言、受支持的参数类型和结果转换仍由原生驱动负责，因此已安装的提供程序仍可能拒绝一个合法绑定，或只有更窄的数值、日期能力

Jet 与 ACE 对通过校验的 DATE、TIME 与 TIMESTAMP 值使用类型化 OLE DATE 绑定，使日期与时间独立于依赖区域的时间戳文本投影；DATE 与 TIME 的校验规则仍然适用，null 投影能力则取决于具体提供程序

参数要求 SQL 文本命令，且每次抓取最多 1024 个参数、每个名称 255 码元、每个文本值 32767 码元；命令文本、参数引用、名称和负载同样计入输入字节预算

提示与未知的参数扩展属性会被拒绝；RefreshOnChange 仍是保留元数据，不会触发后台刷新，打开或保存也不会解析单元格或执行命令

直接 Fetch 支持字面量；FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) 接受 TXLSQueryParameterCellResolver 回调提供单元格值，其布尔结果表示存储值是否可用

回调的作用域限于本次调用，不会被保留；自动工作表刷新提供自己的本地解析器，注册的自定义提供程序仍优先并拥有自己的参数语义

Web 刷新支持不带跨列单元格、嵌套选中表或脚本驱动内容的纯 text/html 表；不受支持的布局和实体会被拒绝，而不是产出部分数据

注册自定义提供程序

Workbook.QueryProviders.RegisterProvider(xlckWeb, CustomProvider);
try
  Status := Sheet.RefreshQueryTable('RemoteData');
finally
  Workbook.QueryProviders.RegisterProvider(xlckWeb, nil);
end;

TXLSQueryProviderDispatcher.Create 构造一个独立持有的调度器供直接使用；工作簿会创建并持有自己的实例

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) 为声明的连接类别安装一个借用的处理器，传入 nil 即注销；处理器必须比注册存活得更久

已注册的处理器优先于内置提供程序，可以支持应用专属的身份验证或连接类别；抓取期间的注册变更、配置变更和递归调度都会被拒绝，无效枚举值在数组访问前被拒绝

Fetch(Connection, Query, MaxRows, out Data, var Abort) 在工作表刷新期间收到分离的元数据并返回矩形 TXLSQueryResultData；取消或异常会在传播前清掉暂存结果

资源限制

MaxInputBytes 默认 67108864 字节，约束文本或 Web 输入以及受支持的数据库结果负载；MaxResultCells 默认 2000000 个单元格，约束矩形结果

TimeoutSeconds 默认 30，配置受支持的原生数据库或 HTTP 阶段；它不是整个操作的截止保证，也不适用于自定义提供程序

这三个设置与 MaxRows 都必须为正，超时值必须能放进原生的毫秒整数；调度器拒绝超限的行、列或单元格而不做截断，字节与输入限制由内置提供程序执行，自定义抓取则由注册的处理器自行负责

工作表刷新会校验所有结果值，并在取消或应用错误后恢复单元格与查询/表元数据；自定义提供程序仍须自行遵守其外部操作限制

原生 XLSX 结果绑定

表支撑的数据库查询使用表与查询表的关系、一致的字段 ID、列身份以及一个隐藏的本地目标名称；独立的受支持 Text 与 Web 目标保留其结果区域

TXLSXTable.ColumnUniqueNames[Index]: WideString 暴露从零开始的原生列身份，并在赋值、复制和重新打开时与 ColumnQueryTableFieldIds 一起保留

作为外部表直接绑定的旧式 Text 连接不是受支持的原生导出形态，保存会在输出前拒绝它；显式刷新得到的文本值可以填充普通表格，或者由已安装的 ADO/ODBC 文本驱动提供原生表支撑的数据库查询

无关或不受支持的导入关系与扩展 XML 保持原样保留；本特性不会把不透明的外部图转换成受支持的可刷新查询

目标校验、进度回调以及周围的元数据模型参见连接与事务性查询 API