Tri značajke u HotXLS-u dijele radni list, ali rade na potpuno različitim objektima, a problemi nastaju kada pretpostavite da rade slične stvari. Validacija podataka (data validation) vezuje pravilo za raspon koje ograničava što korisnik može upisati u njega. AutoFilter pridružuje definiciju pohranjenih kriterija regiji i mijenja koje retke preglednik prikazuje. Tablica omotava raspon u imenovanu, tipiziranu strukturu s trakastim oblikovanjem (banded styling). Jedna ograničava unos, jedna bilježi prikaz, jedna nameće shemu. Nijedna od njih sama po sebi ne pomiče vrijednost niti jedne ćelije, a AutoFilter posebno vara ljude jer ta riječ sugerira akciju, dok zapravo pohranjuje samo definiciju. Znati koji objekt svaki poziv dotiče i kada se učinak stvarno materijalizira ono je što odvaja radnu knjigu koja se u Excelu ponaša isto kao i u vašim testovima od one koja tiho odstupa.
AutoFilter pohranjuje definiciju, on ne izrezuje retke
AutoFilter u spremljenoj datoteci je zapis o kriterijima. Skrivanje redaka događa se kasnije, kada Excel otvori radnu knjigu i procijeni kriterije u odnosu na podatke. HotXLS vjerno zapisuje taj zapis i ništa ne izrezuje: svaki redak koji ste filtrirali i dalje je fizički prisutan u datoteci. Cjevovod koji primjenjuje filtar za odbacivanje odbijenih narudžbi i zatim ponovno čita radnu knjigu vidjet će ih sve, uključujući i odbijene, pa je kôd točan prema API-ju, ali pogrešan prema mentalnom modelu autora. Na XLSX radnom listu, SetAutoFilter deklarira filtriranu regiju, a AddAutoFilterColumn pridružuje kriterije jednom njenom stupcu. Kada poslužiteljski kôd treba stvarni ishod, primjerice za broj redaka u sažetku ili za prosljeđivanje samo podudarnih redaka, knjižnica procjenjuje kriterije za vas umjesto da se pretvara da se datoteka promijenila:
var
Book: TXLSXWorkbook;
Sheet: TXLSXWorksheet;
R, Visible: Integer;
begin
Book := TXLSXWorkbook.Create;
try
Book.Open('orders.xlsx');
Sheet := Book.Sheets[0];
Sheet.SetAutoFilter('A1:E500');
// Column id 3 = fourth column INSIDE the filter range (0-based offset)
Sheet.AddAutoFilterColumn(3, xlsxAfOpGreaterOrEqual, '1000');
Visible := 0;
for R := 2 to 500 do
if Sheet.AutoFilterRowVisible(R) then
Inc(Visible);
// Visible now matches what Excel will show after opening the file
Book.SaveAs('orders-filtered.xlsx');
finally
Book.Free;
end;
end;Metoda AutoFilterRowVisible daje odgovor po retku, a PreviewAutoFilterRows prolazi kroz cijela regiju putem povratnog poziva (callback) kada trebate podudarni skup u jednom prolazu. Postoji slučaj u kojem nijedno od toga nije ispravno rješenje: ako je zahtjev da isključeni redci uopće ne smiju postojati u datoteci, što je sigurnosni rez, a ne samo prikaz, izbrišite te retke u potpunosti. Filtar je tu pogrešan alat, jer ga bilo koji primatelj može ukloniti jednim klikom i podaci koje ste htjeli zatajiti ponovno su na zaslonu.
ID stupca je pomak, a ne broj stupca
Komentar u gornjem isječku koda označava zamku koja košta najviše vremena za uklanjanje pogrešaka u ovom API-ju. AddAutoFilterColumn identificira svoj cilj prema položaju na bazi 0 unutar raspona filtra, a ne prema stupcu radnog lista. Za filtar na A1:E500 ta se dva sustava numeriranja slučajno razlikuju za jedan, što je točno ona vrsta promašaja koja preživi brzi test i puca onog trenutka kada kolega filtrira drugi stupac. Za filtar koji počinje na stupcu C, ID 0 znači stupac C, i nepodudaranje brzo postaje očito. Kada se raspon filtra izračunava u vrijeme izvođenja, izvedite ID stupca iz iste varijable koja je izgradila niz raspona, nikada iz konstante stupca radnog lista. Svaki stupac prihvaća drugi uvjet kroz preopterećenje koje prima dva operatora, dva kriterija i and/or poveznicu, što odražava Excelov prilagođeni dijaloški okvir filtra. XLS fasada pokriva isto područje s SetAutoFilter i ApplyAutoFilter, čiji parametri kriterija i operatora prate starije konvencije u stilu COM-a i numeriraju polje od 1. Promjena fasada znači promjenu baze indeksa, pa mjesto poziva zaslužuje komentar koji govori koja je fasada u igri.
Pravila validacije su ugovor pod kojim vaši korisnici uređuju
Od ove tri značajke, validacija je jedina koja aktivno ograničava budući unos i zaslužuje najviše pažnje pri dizajniranju radnih knjiga koje se šalju na popunjavanje i vraćaju na obradu. Varijanta popisa (list variant) nosi većinu tog posla:
var
Idx: Integer;
begin
Idx := Sheet.AddListValidation('C2:C500', 'New,Approved,Blocked');
Sheet.DataValidations[Idx].SetPrompt('Status',
'Pick one of the listed states');
Sheet.DataValidations[Idx].SetError('Invalid status',
'Type or paste only listed values', xlsxDvErrStop);
Sheet.DataValidations[Idx].AllowBlank := False;
// Quantities: whole numbers, zero or more
Sheet.AddWholeNumberValidation('D2:D500', xlsxDvOpGreaterOrEqual, '0');
end;Osim popisa i cijelih brojeva, ista obitelj pokriva decimale, datume, vremena, duljinu teksta i formule slobodnog oblika putem AddCustomValidation, a generička metoda AddDataValidation izlaže punu matricu tipova i operatora za graditelje pravila vođene konfiguracijom. Stil pogreške važniji je nego što njegovo ime sugerira. xlsxDvErrStop izravno odbija loš unos; stilovi upozorenja (warning) i informacija propuštaju vrijednost nakon jednog klika. Odaberite po stupcu na temelju toga može li kôd koji ponovno čita radnu knjigu tolerirati vrijednost izvan pravila. Dvije granice pripadaju tekstu upita ili README datoteci koju šaljete s datotekom. Validacija u Excelu štiti tipkanje, ali lijepljenje bloka preko validiranog raspona prolazi pokraj pravila, pa svaki kôd koji ponovno čita podatke mora ponovno provesti validaciju umjesto da vjeruje ćelijama. Također, pravilo pokriva točan raspon koji ste mu predali, što znači da dodavanje validacije prije nego što saznate konačni broj redaka ostavlja dodani rep nezaštićenim. Najprije zapišite podatke, a zatim prilagodite veličinu pravila stvarnom opsegu.
Naslijeđena fasada nudi iste obitelji pravila s jednom ergonomskom razlikom. Metode na XLS strani, odnosno AddWholeNumberValidation, AddDecimalValidation, AddDateValidation, AddTimeValidation, AddTextLengthValidation i AddCustomValidation, vraćaju objekt TDataValidation izravno, a ne indeks, pa se konfiguracija prompta i pogreške nadovezuje na vraćenu referencu umjesto preko pretraživanja. Nabrajanje operatora (xlsDvBetween, xlsDvGreaterThan i ostali) odražava XLSX skup, pa se kôd za izgradnju pravila prenosi između fasada bez obzira na razliku u stilu povrata. Sam tekst prompta zaslužuje jednaku pažnju kao i pravilo. Padajući izbornik koji odbija unos s praznim okvirom za pogrešku uči korisnike da pišu IT podršci; onaj koji navodi dopuštena stanja uči ih da poprave ćeliju i nastave dalje.
Jedan obrat polariteta koji knjižnica preuzima za vas
Svatko tko je ručno čitao OOXML validacijski XML susreo se s obrnutim atributom showDropDown: u ISO/IEC 29500 istinita vrijednost (true) znači 'potisni strelicu padajućeg izbornika', što je suprotno od onoga kako naziv glasi. HotXLS to interno preokreće, tako da svojstvo ShowDropDown na validacijskom pravilu znači ono što kaže, pri čemu true prikazuje padajući izbornik. Jedini način da pogriješite jest miješanje razina istine, postavljanjem svojstva iz koda dok kolega provjerava spremljeni XML i 'ispravlja' atribut koji mu se čini naopako postavljenim. Odlučite jesu li svojstvo ili sirovi XML mjerodavni za alate za reviziju i zapišite to preokretanje tamo gdje ta odluka živi.
Tablice rasponu daju shemu i naziv
Tablica radnog lista, ListObject u Excel terminima, omotava raspon u naziv, tipizirane stupce, trakasto oblikovanje i podršku za strukturirane reference. To je značajka koja čini da generirana radna knjiga izgleda dovršeno čim korisnici počnu sortirati i proširivati podatke. Stvaranje je simetrično na obje fasade, pri čemu AddTable prima naziv, raspon i popis stupaca:
var
Cols: TStringList;
begin
Cols := TStringList.Create;
try
Cols.CommaText := 'OrderId,Customer,Status,Amount,Owner';
Sheet.AddTable('Orders', 'A1:E500', Cols);
finally
Cols.Free;
end;
end;Na XLSX strani, rezultirajući objekt tablice izlaže svojstvo StyleName (ugrađena obitelj TableStyleMedium2 i njezini srodnici), prekidače traka i zastavicu retka s ukupnim vrijednostima, pa je primjena kućnog stila dodjela svojstva radije nego ručni prolaz oblikovanja. U naslijeđenim .xls datotekama isti poziv zapisuje BIFF8 zapise tablice, a fasada također nudi AddPivotTable za sažete prikaze izgrađene od polja redaka, stupaca i podataka, što je podsjetnik da se 'tablice' u starijem formatu protežu dalje nego što to ListObject u OOXML-u čini. Imenujte tablice onako kako imenujete poglede baze podataka. Kasniji kôd koji čita Orders[Amount] pomoću strukturirane reference preživljava promjenu redoslijeda stupaca koja lomi pozicijski kôd.
Dvije konvencije štede čišćenje kasnije. Excel zahtijeva da nazivi tablica budu jedinstveni u cijeloj radnoj knjizi, pa generator koji emitira jedan list po regiji treba shemu poput Orders_EMEA umjesto ponovne upotrebe Orders. Duplikat ne uzrokuje neuspjeh u vrijeme zapisivanja; negativno se očituje kao dijaloški okvir za popravak kada korisnik otvori datoteku, što je najgore mjesto za njegovo otkrivanje. Druga konvencija odnosi se na redak s ukupnim iznosima: kada je omogućen, on se nalazi izravno ispod raspona podataka, pa bilo koji kôd koji kasnije dodaje po principu 'zadnji korišteni redak plus jedan' piše u traku s ukupnim iznosima umjesto nakon nje. Pratite opseg podataka odvojeno od opsega tablice i dodavanja će sletjeti tamo gdje očekujete.
Ove tri značajke prirodno se spajaju u izlaznim datotekama za unos podataka. Tablica definira područje koje se može uređivati, validacija ograničava stupce u koje korisnici tipkaju, a unaprijed postavljeni filtar štedi primatelju prvih nekoliko klikova. Postoji valjan argument za slanje već primijenjenog filtra kako bi se radna knjiga otvorila usredotočena na retke koji su važni, sve dok se sjećate da su isključeni redci i dalje u datoteci i da ih znatiželjni primatelj može otkriti. Učinkovito dobivanje rezultata upita u list, što je uzvodna polovica ovog cjevovoda, pokriveno je u članku izvoz rezultata baze podataka u Excel iz Delphija, a radne knjige u kojima formule sažimaju validirane podatke imaju koristi od članka definirani nazivi za stabilne reference među listovima.
Validacija, filtri i tablice čine razliku između slanja mreže vrijednosti i slanja male aplikacije. Potpuna referenca pravila, filtara i tablica nalazi se na stranici proizvoda HotXLS Component.