Artykuł techniczny

Znaki wypełnienia Excela (*) w eksporcie PDF i druku

Wyeksportuj arkusz w księgowym formacie Excela 44 własnym formatterem, a PDF pokaże $1,234.50 sklejone albo $* 1,234.50 z błądzącą gwiazdką. Ten odstęp to wypełnienie * wymiarowane szerokością kolumny i fontem, a jego pozycja w tekście, którą HotXLS zwraca z TXLSXCell.GetFormattedTextFill, to wszystko, czego renderer potrzebuje, żeby policzyć powtórzenia

Jak działają * i _ w formacie liczbowym Excela?

ECMA-376 Part 1 §18.8.30 definiuje oba znaki w swojej tabeli symboli kodu formatu. * powtarza następny znak „wystarczająco razy, żeby wypełnić kolumnę do jej bieżącej szerokości”; sekcja może trzymać jedną gwiazdkę, a jeśli pojawi się kilka, wszystkie poza ostatnią są ignorowane. _ „pomija szerokość następnego znaku”, więc _) zostawia puste tak szerokie jak nawias zamykający i kwoty dodatnie układają się w linii z ujemnymi pokazywanymi jako (1,234.50). Przykłady standardu są krótkie. 0*- stawia kreski za liczbą aż do krawędzi komórki, *0 przed formatem daje zera wiodące, a 0*x pokazuje 3 jako 3xxxxxx w kolumnie jednej konkretnej szerokości. Formaty łączące oba znaki to wbudowane formaty księgowe Excela, o ID od 41 do 44. Te numery są własnością Excela: tabela wbudowanych w §18.8.30 skacze z 40 prosto na 45, a HotXLS rejestruje cztery poniższe kody pod numeracją Excela

Excel IDKod formatuSymbolMiejsca dziesiętne
41_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)brak0
42_("$"* #,##0_);_("$"* (#,##0);_("$"* "-"_);_(@_)$0
43_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)brak2
44_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)$2

Przeczytaj sekcję dodatnią 44, _("$"* #,##0.00_), od lewej do prawej: puste o szerokości (, znak dolara, spacja powtarzana aż wypełni kolumnę, liczba i puste o szerokości ). Sekcja ujemna zamienia to końcowe puste na prawdziwe nawiasy. Sekcja zerowa drukuje kreskę, po której idzie ?? — dwa puste o szerokości cyfry, które stawiają kreskę w kolumnie punktu dziesiętnego. To, którą z czterech sekcji wybierze wartość, i to, co robi sekcja pusta, podąża za regułami sekcji formatu liczbowego Excela. Wytnij wypełnienie, a znak dolara spadnie na cyfry. Wydrukuj gwiazdkę, a czytelnik patrzy na składnię formatu

Anatomia sekcji dodatniej księgowego formatu Excela 44 w HotXLS dla Delphi: puste o szerokości nawiasu, znak dolara, powtarzana spacja wypełnienia i liczba
Jedna gwiazdka każe następnemu znakowi powtarzać się do szerokości kolumny, a każde puste w sekcji księgowej pochodzi z podkreślnika

Dlaczego formatter nie może sam wstawić powtórzeń?

Nie zna liczby. Liczba powtórzeń to szerokość kolumny minus szerokość wszystkiego innego, podzielone przez szerokość jednego znaku wypełnienia. Każdy składnik zależy od fontu, rozmiaru, zoomu i urządzenia wyjściowego. Formatter zwracający goły string musiałby wybrać liczbę, a każda sztywna liczba jest zła, jak tylko ktoś zmieni szerokość kolumny. HotXLS dzieli robotę. TXLSXCell.FormattedText zwraca tekst wyświetlany bez żadnej kopii znaku wypełnienia, a GetFormattedTextFill zwraca ten sam tekst plus znak wypełnienia i indeks: liczbę znaków przed punktem, w którym należą się powtórzenia. Metoda zwraca False, gdy format nie ma wypełnienia, i dla komórki rich text, której runy są rysowane takimi, jakimi są

Automatyczny znak minusa przychodzi przed wypełnieniem. Przy formacie **0 i wartości -5 tekstem jest -5, znakiem wypełnienia *, a indeksem 1. Szeroka komórka wyświetla więc -****5, ten sam string, który dla tej komórki daje Range.Text Excela. Wywołujący bez kolumny nie dostaje wypełnienia wcale. Funkcja arkuszowa TEXT to właśnie taki wywołujący, więc w silniku obliczeń HotXLS TEXT(A1, "$* #,##0") z 1234 w A1 liczy się do $1,234. Kod poniżej ustawia trzy formaty i drukuje to, co renderer dostaje dla każdego

Kontrakt GetFormattedTextFill w HotXLS dla Delphi: tekst prefiksu, znak wypełnienia i indeks podziału, które pozwalają rendererowi policzyć powtórzenia dla dowolnej szerokości kolumny
Komórka raportuje punkt podziału zamiast liczby powtórzeń, bo tylko kanwa rysująca zna prawdziwą szerokość kolumny
uses
  SysUtils, lxHandleX;

procedure InspectFills;
const
  Formats: array[0..2] of WideString = (
    // ten sam kod co wbudowany format Excela 44
    '_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)',
    '0*-',     // kreski za liczbą
    '**0');    // gwiazdki przed liczbą
  Values: array[0..2] of Double = (1234.5, 42, -5);
  // Każdy wiersz powinien wydrukować:
  //   [ $] fill " " [1,234.50 ]
  //   [42] fill "-" []
  //   [-] fill "*" [5]
var
  Book: TXLSXWorkbook;
  Sheet: TXLSXWorksheet;
  Text: WideString;
  Fill: WideChar;
  FillIndex, I: Integer;
begin
  Book := TXLSXWorkbook.Create;
  try
    Sheet := Book.Sheets.Add('Fills');
    for I := 0 to High(Formats) do
    begin
      Sheet.Cells[I + 1, 1].NumberFormat := Formats[I];
      Sheet.Cells[I + 1, 1].Value := Values[I];
      if Sheet.Cells[I + 1, 1].GetFormattedTextFill(Text, Fill, FillIndex) then
        Writeln(Format('[%s] fill "%s" [%s]', [
          Copy(Text, 1, FillIndex), string(Fill),
          Copy(Text, FillIndex + 1, MaxInt)]))
      else
        Writeln('no fill: ', string(Sheet.Cells[I + 1, 1].FormattedText));
    end;
    Sheet.SaveAsPDF('fills.pdf');   // eksport PDF rozkłada wypełnienie per kolumna
  finally
    Book.Free;
  end;
end;

Każdy wiersz pokazuje prefiks, znak wypełnienia i sufiks w nawiasach kwadratowych. Zwróć uwagę na puste: w pierwszym wierszu prefiksem jest spacja i znak dolara, a sufiks kończy się spacją, oba wyprodukowane przez pary _. SaveAsPDF pracuje z tych samych trzech części i liczy liczbę powtórzeń z prawdziwej szerokości kolumny. W fills.pdf znak dolara powinien siedzieć na lewym wypełnieniu pierwszej komórki, a kreski za 42 powinny biec do prawej krawędzi drugiej. Ustawienia strony, marginesy i fonty tego pliku załatwiają zwykłe ustawienia eksportu PDF arkusza

Która strona dostaje resztkowy ułamek znaku?

Dla komórek General i wyrównanych do lewej — przestrzeń między wypełnieniem a sufiksem. Liczba powtórzeń to liczba całkowita, więc ułamek znaku prawie zawsze zostaje, a §18.8.30 nie mówi o nim nic. Własne wyjście PDF Excela i jego Range.Text pokazują następujące rozmieszczenie, zależne od wyrównania poziomego:

Matryca rozmieszczenia resztkowego ułamka dla znaków wypełnienia w HotXLS dla Delphi, od wyrównania general i lewego do center, right i shrink to fit
Wyrównanie general i lewe wkładają zapasowy ułamek między wypełnienie a sufiks, co trzyma kolumnę znaków dolara w bezruchu
  • General i lewe: prefiks przylega do lewego wypełnienia, sufiks do prawego, a resztka siedzi między wypełnieniem a sufiksem (na końcu wiersza, gdy sufiksu brak)
  • Center: prefiks i wypełnienie przesuwają się w prawo o połowę resztki; wyrównanie do prawej przesuwa je o całość
  • Fill, justify, distributed i tekst zawijany: trzy części biegną od lewej, z resztką na końcu wiersza
  • Wcięcie zawęża dostępną szerokość jak zwykle, a komórka „shrink to fit” nie dostaje wypełnienia

Wyrównanie General to miejsce, w którym renderery zrób-to-sam się mylą. Liczby pod General są normalnie wyrównane do prawej. Komórka z wypełnieniem nie jest. Trzymaj regułę „liczby idą w prawo”, a resztka wyląduje przed wypełnieniem, odpychając znak dolara od lewego wypełnienia o do jednej szerokości spacji. W dół kolumny kwot formatu 44 znaki dolara kołyszą się wtedy od wiersza do wiersza. Rzadsze układy podążają za tym samym modelem:

  • Tekst obrócony: długość wypełnienia pochodzi z najdłuższego wiersza, który po obróceniu wciąż mieści się w komórce
  • Rich text: powtarzany znak bierze swój styl ze znaku tuż przed pozycją wypełnienia
  • Center across selection: wypełnienie obejmuje całą rozpiętość
  • Tekst wielowierszowy: powtórzenia dostaje tylko wiersz zawierający pozycję wypełnienia

Arkusze od prawej do lewej to przypadek, którego HotXLS nie kopiuje z eksportu PDF Excela. Tamten eksport wyrzuca wypełnienie i glify prefiksu, choć Range.Text dla tych samych komórek nadal je zawiera. HotXLS rozkłada takie komórki tak, jak pokazuje je siatka, z wypełnieniem na miejscu

Rysowanie wypełnienia na kanwie VCL

Mierz kanwą, na której będziesz rysować. To obowiązuje tak samo dla własnej siatki, bandy raportu i miniatury. Kanwa VCL przy skalowaniu wybiera całkowity rozmiar fontu, więc szerokość policzona z metryk fontu przy rozmiarze ułamkowym wychodzi odrobinę węższa niż to, co maluje GDI. Błąd na znak jest znikomy. Na ciągu powtórzeń się składa. Policzysz z węższej szerokości, a lewa część przeleje się ze swojego prostokąta; przy DT_END_ELLIPSIS wśród flag rysowania GDI wkrada wtedy wielokropek na sufiks. Procedura poniżej ogarnia typowy przypadek jednowierszowy z wyrównaniem General albo lewym, a wszystko inne wysyła gołą ścieżką TextRect:

uses
  Windows, Types, Graphics, lxHandleX;

procedure DrawFilledCell(Canvas: TCanvas; const R: TRect; Cell: TXLSXCell);
const
  Pad = 2;                                   // wewnętrzny padding komórki, piksele
var
  Text: WideString;
  Fill: WideChar;
  FillIndex, Avail, Used, FillWidth, Count: Integer;
  Prefix, Suffix: string;
begin
  if not Cell.GetFormattedTextFill(Text, Fill, FillIndex) then
  begin
    Canvas.TextRect(R, R.Left + Pad, R.Top + Pad, Cell.FormattedText);
    Exit;
  end;
  Prefix := Copy(Text, 1, FillIndex);
  Suffix := Copy(Text, FillIndex + 1, MaxInt);

  // Mierz tą samą kanwą, fontem i rozmiarem, które narysują tekst
  Avail := (R.Right - R.Left) - 2 * Pad;
  Used := Canvas.TextWidth(Prefix) + Canvas.TextWidth(Suffix);
  FillWidth := Canvas.TextWidth(string(Fill));
  Count := 0;
  if (FillWidth > 0) and (Used < Avail) then
    Count := (Avail - Used) div FillWidth;   // tylko znaki całkowite

  // General / lewe: prefiks + wypełnienie przy lewej, sufiks przy prawej,
  // resztkowy ułamek zostaje między wypełnieniem a sufiksem
  Canvas.TextOut(R.Left + Pad, R.Top + Pad, Prefix + StringOfChar(Fill, Count));
  Canvas.TextOut(R.Right - Pad - Canvas.TextWidth(Suffix), R.Top + Pad, Suffix);
end;

Rysowanie obu połówek osobnymi wołaniami trzyma kwotę przypiętą do prawej krawędzi, jakkolwiek zaokrągli dzielenie całkowite. Dla komórek wyśrodkowanych albo wyrównanych do prawej przesuń pierwsze TextOut o połowę albo całość Avail - Used - Count * FillWidth. Komórki obrócone i wielowierszowe prościej załatwić inaczej: wstaw policzone powtórzenia do tekstu na FillIndex i narysuj wynik jako jeden string twoim zwykłym kodem rotacji albo zawijania. W ręcznie budowanej siatce jak ta własna siatka arkusza w Delphi ta sama kanwa powinna napędzać też wysokości wierszy i złączenia zakresów

Wypełnienie i podkreślnik w tekście o stałej szerokości i CSV

Wyjście czysto tekstowe nie ma pikseli, ale nadal może mieć szerokość. TXLSXCell.FormattedText zapisuje każde _x jako jedną zwykłą spację, więc sekcja dodatnia formatu 44 wraca jako $1,234.50 z pustym na każdym końcu. W foncie proporcjonalnym spacja jest zwykle odrobinę węższa od nawiasu, wystarczająco blisko dla podglądu. W monospacjowym raporcie tekstowym każdy znak ma ten sam przyrost, więc spacja jest dokładnym zastępnikiem, a liczba wypełnień to zwykła arytmetyka: szerokość kolumny w znakach minus długość tekstu. CSV jest inny. Arkusz albo baza danych czytająca plik chce liczbę, więc zapisz tam Value komórki i trzymaj wyściełany tekst dla raportów, które czytają ludzie:

uses
  lxHandleX;

// Kolumna raportu o stałej szerokości: format 44, wartość 1234.5 i Width 14
// dają ' $   1,234.50 ' (trzy powtórzone spacje po znaku dolara)
function PadToWidth(Cell: TXLSXCell; Width: Integer): WideString;
var
  Text: WideString;
  Fill: WideChar;
  FillIndex, Count: Integer;
begin
  if not Cell.GetFormattedTextFill(Text, Fill, FillIndex) then
    Exit(Cell.FormattedText);
  Count := Width - Length(Text);
  if Count < 0 then
    Count := 0;                    // tekst szerszy niż kolumna: bez powtórzeń
  Result := Copy(Text, 1, FillIndex) + StringOfChar(Fill, Count) +
    Copy(Text, FillIndex + 1, MaxInt);
end;

Zacznij od jednej komórki: format 44, wartość 1234.5 i wołanie GetFormattedTextFill, które powinno raportować spację na indeksie 2. Zmień szerokość kolumny dwa razy i sprawdź, że znak dolara zostaje na lewym wypełnieniu, podczas gdy 1,234.50 zostaje na prawej krawędzi. Jak twój renderer to przejdzie, pozostałe wyrównania to przesunięcia pierwszego TextOut, a strona SaveAsPDF z komponentu HotXLS Delphi Excel to odniesienie, z którym je porównasz