自動查詢提供者

自版本 2.384.99 起，可透過 Windows 上的 XLSX 活頁簿外觀層使用；自動 provider 選擇只會在明確的查詢重新整理時發生

重新整理既有查詢

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 公開一個由活頁簿持有的 dispatcher；不要自行釋放這個 dispatcher

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer 以及接受以零為基底 AIndex 的多載，會選定一個既有查詢並使用這個 dispatcher

接受明確 TXLSQueryTableProvider 的既有多載仍直接使用該 provider，包括原本對 provider 缺失的拒絕行為；它們不會退回自動分派

重新整理在成功時傳回 1、取消時傳回 0、失敗時傳回 -1，並在 xlsOperationRefresh 下記錄 1401 與 1400 兩個診斷碼；既有的交易式結果套用、結構描述驗證、文字字面值與格式化行為都照舊生效

這兩個診斷分別名為 xlsDiagnosticQueryRefreshCancelled 與 xlsDiagnosticQueryRefreshFailed；取得活頁簿寫入防護發生在狀態轉換之前，因此凍結的讀取檢視或其他寫入防護拒絕會擲出例外

開啟與儲存活頁簿絕不會抓取連線資料、評估查詢，也不會處理保留的 RefreshOnLoad 中繼資料；請在儲存結果之前，明確重新整理每個需要的查詢

支援的內建 provider

• xlckText 以嚴格的 UTF-8、UTF-16LE、UTF-16BE、Windows-1252 或 Latin-1 解碼讀取本機分隔或固定寬度文字，支援設定的起始列，以及包含六種日期順序與可略過欄位在內的支援欄位型別；分隔輸入也支援以引號包覆的多列記錄
• xlckAdo、xlckOleDb 與 xlckOdbc 使用已安裝的 Windows ADO 與資料庫驅動程式，連線與 recordset 皆為唯讀；CommandType = 2 選擇 SQL 文字命令，CommandType = 3 選擇資料表命令
• xlckWeb 使用 Windows WinHTTP 發出匿名 HTTP 或 HTTPS GET，取得以其正整數索引或名稱選定的一個非空矩形 HTML 表格；支援的回應字元集為 UTF-8、UTF-16、Windows-1252 與 Latin-1

BaseDirectory 只作為相對本機文字路徑的基準；資料庫連線字串與 Web URL 仍是明確的連線中繼資料

未指定文字編碼時，除非有受支援的位元組順序記號能識別編碼，否則只接受純 ASCII 輸入；含非 ASCII 字元的輸入必須明確指定受支援的編碼或位元組順序記號

對分隔文字連線，設定 TextPrompt = False、TextDelimited = True 並只設定一個分隔符，且不合併連續分隔符；新建連線預設會提示使用者並使用 tab 分隔符，因此改選其他分隔符時記得清空 TextTab

固定寬度文字

設定 TextPrompt = False 與 TextDelimited = False，接著以嚴格遞增、以零為基底的 Position 順序加入 TextFields，從零開始；每個欄位結束於下一個位置或實際的記錄結束符，xltiftSkip 則把該欄位排除在結果之外

位置以解碼後的 UTF-16 代碼單位計算，而非輸入位元組；切開代理對（surrogate pair）的邊界會被拒絕，CRLF、LF 與 CR 各自都能終止記錄，不受分隔符與限定符設定影響

欄位填充會在轉換前修剪，包含明確指定為文字型別者，與已驗證的原生固定寬度匯入行為一致；欄位內的引號、tab 與分隔符字元維持為字面輸入，不足長度的記錄會補上空的尾端欄位而不改變宣告的結構描述

沒有 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'；受支援的請求會拒絕內嵌憑證、片段、驗證與重新導向

內建 provider 會在其各自的連線類型中拒絕不支援的中繼資料；資料庫重新整理拒絕 OLAP 或伺服器端命令、連線檔間接參照、儲存的密碼與憑證提示，文字重新整理拒絕檔案提示，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 null；陣列、參照型 Variant、錯誤、非有限數值、不支援的 SQL 型別，以及會損失整數精度的轉換都會被拒絕，NUMERIC 或 DECIMAL 則需要這個繫結 API 未提供的精度與小數位數中繼資料

ADO 收到的是具型別的值與宣告大小，空文字至少配置一個代碼單位；SQL 方言、支援的參數型別與結果轉換仍由原生驅動程式負責，因此已安裝的 provider 仍可能拒絕合法的繫結，或只有較窄的數值與日期能力

Jet 與 ACE 對驗證過的 DATE、TIME 與 TIMESTAMP 值使用具型別的 OLE DATE 繫結，讓日期與時間獨立於隨地區而變的時間戳記文字投影；DATE 與 TIME 的驗證規則仍然適用，null 投影能力則依 provider 而定

參數需要 SQL 文字命令，每次擷取上限 1024 個、每個名稱 255 個代碼單位、每個文字值 32767 個代碼單位；命令文字、參數參照、名稱與承載也計入輸入位元組預算

提示與未知的參數擴充屬性會被拒絕；RefreshOnChange 仍是保留的中繼資料，不會觸發背景重新整理，開啟或儲存也不會解析儲存格或執行命令

直接 Fetch 支援字面值；FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) 接受 TXLSQueryParameterCellResolver 回呼來取得儲存格值，其布林回傳值表示已儲存的值是否存在

回呼的效力範圍限於該次呼叫，不會被保留；自動工作表重新整理會提供自己的本機 resolver，已註冊的自訂 provider 仍然優先，並擁有自己的參數語意

Web 重新整理支援沒有跨欄儲存格、巢狀選定表格或指令碼驅動內容的純 text/html 表格；不支援的版面與實體（entity）會被拒絕，而不是產出部分資料

註冊自訂 provider

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

TXLSQueryProviderDispatcher.Create 會建構一個獨立持有的 dispatcher 供直接使用；活頁簿會建立並持有自己的實例

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) 為宣告的連線類型安裝借用的處理常式，傳入 nil 則取消註冊；處理常式的存活時間必須長於註冊期間

已註冊的處理常式優先於內建 provider，可支援應用程式專屬的驗證或連線類型；擷取期間的註冊變更、組態變更與遞迴分派都會被拒絕，無效的列舉值則在存取陣列前就被拒絕

Fetch(Connection, Query, MaxRows, out Data, var Abort) 在工作表重新整理期間收到分離的中繼資料，並傳回矩形的 TXLSQueryResultData；取消或例外會在往外傳遞之前清空暫存結果

資源上限

MaxInputBytes 預設 67108864 位元組，約束文字或 Web 輸入與受支援的資料庫結果承載；MaxResultCells 預設 2000000 儲存格，約束矩形結果

TimeoutSeconds 預設 30，設定受支援的原生資料庫或 HTTP 階段；它不是整個作業的保證期限，也不約束自訂 provider

這三個設定與 MaxRows 都必須為正，逾時也必須能放進原生的毫秒整數；dispatcher 會拒絕超量的列、欄或儲存格而不截斷，位元組與輸入上限由內建 provider 強制執行，自訂擷取則由註冊的處理常式自行負責

工作表重新整理會驗證所有結果值，並在取消或套用錯誤後還原儲存格與查詢或資料表中繼資料；自訂 provider 仍須自行遵守其外部作業上限

原生 XLSX 結果繫結

以資料表為後盾的資料庫查詢使用 table 對 query table 的關聯、連貫的欄位 ID、欄識別與一個隱藏的本機目的地名稱；獨立且受支援的文字與 Web 目的地保留其結果範圍

TXLSXTable.ColumnUniqueNames[Index]: WideString 公開以零為基底的原生欄識別，並與 ColumnQueryTableFieldIds 一起在指派、複製與重新開啟時保留

直接綁定為外部資料表的舊式文字連線不是受支援的原生匯出形狀，儲存時會在輸出前被拒絕；明確重新整理過的文字值可以填入普通資料表，或由已安裝的 ADO/ODBC 文字驅動程式提供原生資料表後盾的資料庫查詢

無關或不支援的已匯入關聯與擴充 XML 照樣保留；這項功能不會把不透明的外部圖形轉換成受支援且可重新整理的查詢

目的地驗證、進度回呼與周邊的中繼資料模型，請參閱連線與交易式查詢 API