Vláknové komentáre v súboroch Excel s Delphi a HotXLS

HotXLS zapisuje skutočné vláknové komentáre (threaded comments) pre Excel 365 prostredníctvom metód AddThreadedComment a AddThreadedReply v XLSX engine, pričom generuje vyhradenú časť xl/threadedComments/threadedCommentN.xml pre každý hárok a registruje každého autora v časti person na úrovni zošita, takže konverzácia vytvorená vaším kódom predstavuje rovnaký objekt, na ktorý reaguje posudzovateľ v Exceli

Tento rozdiel je dôležitý, pretože obe funkcie vyzerajú rovnako len na prvý pohľad. Poznámka (note) je plávajúce textové pole; vláknový komentár je konverzačný záznam so stabilnými identifikátormi, stromom odpovedí, registrom autorov a príznakom vyriešenia (resolved flag) — čiže prvkami, na ktorých reálne stojí proces posudzovania. Tento článok sa najprv zaoberá štruktúrou OOXML, pretože keď uvidíte tieto dva modely ukladania vedľa seba, rozdiely v správaní Excelu prestanú byť záhadou

Prečo sa moje komentáre v Exceli 365 zobrazujú ako poznámky?

Stručná odpoveď: dve generácie komentárov zdieľajú rovnakú mriežku a nachádzajú sa v úplne odlišných častiach balíka. Pôvodný model, na ktorý mieri AddComment, ukladá text v súbore xl/comments1.xml (typ obsahu application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml) and positions the balloon through a companion VML drawing part, xl/drawings/vmlDrawing1.vml. Táto dvojica vznikla ešte pred zavedením pásu kariet (ribbon); Excel 365 ju síce stále verne číta, ale výsledok zobrazuje ako „poznámku“ a neponúka pre ňu rozhranie pre vlákna, pretože v úložisku nie je nič, čo by sa dalo zreťaziť do vlákna. Autor je len textový reťazec, pozícia je tvar VML a to je celý model

Vláknové komentáre zavedené v Exceli 365 úplne ignorujú vrstvu VML. Každý hárok s konverzáciou nesie vlastnú časť xl/threadedComments/threadedCommentN.xml pod typom obsahu application/vnd.openxmlformats-officedocument.spreadsheetml.threadedComments+xml a zošit obsahuje jednu časť xl/person/person.xml (typ obsahu ...spreadsheetml.people+xml) so zoznamom všetkých účastníkov. HotXLS sprístupňuje oba modely na rovnakom hárku: AddComment naďalej zapisuje pôvodnú dvojicu, AddThreadedComment writes the new parts. Ak sa váš výstup zobrazuje ako poznámka, zavolali ste prvé rozhranie API namiesto druhého. Pôvodný model je stále správnym nástrojom pre niektoré úlohy — predchádzajúci článok o komentároch buniek a hyperodkazoch v procesoch posudzovania sa ním podrobne zaoberá, vrátane formátu XLS — nič z neho sa však nedá povýšiť na diskusné vlákno

Čo HotXLS zapisuje do balíka

HotXLS modeluje každú odpoveď ako objekt TXLSXThreadedComment nesúci ukotvenie bunky (Ref), identifikátor v štýle GUID (Id), voliteľný ParentId, identifikátor AuthorId vyhodnocovaný cez zoznam osôb, zrkadlené meno DisplayName, text tela komentára, príznak vyriešenia Done a časovú pečiatku ISO-8601 DateTime. Pri uložení sa každá položka zmení na element <threadedComment>, ktorého atribút t nesie identifikátor, atribút dT časovú pečiatku a atribút parentT — prítomný len na odpovediach — pomenúva identifikátor rodiča. Excel rekonštruuje strom konverzácie spájaním parentT s t; v XML nie je žiadne vnorenie, len plochý zoznam a odkazy

Časť person (osoba) je presne tá časť, na ktorú väčšina vlastnoručne napísaných implementácií zabúda. Každý identifikátor authorId vo vláknovom komentári sa musí vyhodnotiť na položku <person> v súbore xl/person/person.xml, zapojenú do vzťahov zošita s vlastným preťažením typu obsahu — inak Excel nemá ako zobraziť meno autora. HotXLS toto registrovanie rieši automaticky: metóda AddThreadedComment vyhľadá autora v zoznamu zošita Persons podľa zobrazovaného mena a ak neexistuje, vytvorí položku s novým GUID, takže po sebe nasledujúce komentáre od rovnakého autora zdieľajú rovnakú identitu. Vzťahy hárka získajú vzťah threadedComments, vzťahy zošita získajú vzťah pre osobu a manifest typov obsahu (content-types) získa obe preťaženia bez toho, aby sa niečo z toho muselo objaviť vo vašom kóde

Vytvorenie reťazca odpovedí pomocou AddThreadedComment a AddThreadedReply

Metóda AddThreadedComment vytvára koreň konverzácie: jej kľúč ParentId zostáva prázdny, čo ho označuje ako začiatok vlákna. Metóda AddThreadedReply prijíma parameter ParentRef — odkaz na bunku, kde koreň konverzácie sídli — vyhľadá koreň na tomto ukotvení a označí ParentId novej odpovede identifikátorom Id koreňa. Obe metódy vracajú nový objekt TXLSXThreadedComment, takže na vytvorenom objekte môžete nastaviť časovú pečiatku alebo stav vyriešenia:

var
  Book: TXLSXWorkbook;
  Sheet: TXLSXWorksheet;
  Root: TXLSXThreadedComment;
begin
  Book := TXLSXWorkbook.Create;
  try
    Book.Open('forecast.xlsx');
    Sheet := Book.Sheets[0];

    // Conversation root; ParentId stays empty
    Root := Sheet.AddThreadedComment(8, 3,
      'Q3 figure looks low against the pipeline export', 'Maria Ortiz');
    Root.DateTime := '2026-07-06T09:12:00Z';

    // Replies anchor at the same cell; ParentRef names the root cell
    Sheet.AddThreadedReply(8, 3, Root.Ref,
      'Pipeline export missed the EMEA renewals, re-running', 'Jan Kowalski');
    Sheet.AddThreadedReply(8, 3, Root.Ref,
      'Confirmed, refreshed figure lands tomorrow', 'Maria Ortiz');

    Book.SaveAs('forecast-reviewed.xlsx');
  finally
    Book.Free;
  end;
end;

Dva detaily vo výpise si zaslúžia pozornosť. Po prvé, odovzdáva sa Root.Ref namiesto manuálne zostaveného reťazca: odkaz vygenerovaný knižnicou garantuje zhodu s tým, čo bude AddThreadedReply vyhľadávať, čým sa predchádza chybám nesprávneho ukotvenia. Po druhé, obaja autori boli odovzdaní ako prosté mená — register osôb, identity GUID a prepojenie authorId prebehli na pozadí volaní. Otvorte uložený súbor v Exceli 365 a ukotvenie buniek, poradie odpovedí aj dvaja odlišní účastníci sú plne funkční: kliknite na Odpovedať a Excel pridá odpoveď do rovnakého vlákna, aké začal váš kód

Čtanie konverzácie späť: prechod tam a späť

HotXLS od verzie v2.122.0 plne podporuje prechod vláknových komentárov tam a späť: opätovné otvorenie uloženého balíka znovu zostaví zoznam konverzácií pre každý hárok a zoznam účastníkov zošita z príslušných častí, so identifikátory, odkazy na odpovede a mená prežijú kompletný cyklus čítania a zápisu. Čítač analyzuje súbor person.xml pred akýmkoľvek obsahom hárka, čo umožňuje priradiť každý authorId k zobrazovanému menu už pri načítaní; analyzované identifikátory osôb sa zachovávajú bez zmien namiesto ich opätovného generovania, so zošit prechádzajúci medzi vaším kódom a Excelom si zachováva stabilné identity autorov počas ľubovoľného počtu úprav

var
  i: Integer;
  Cmt: TXLSXThreadedComment;
begin
  Book.Open('forecast-reviewed.xlsx');
  Sheet := Book.Sheets[0];
  for i := 0 to Sheet.ThreadedComments.Count - 1 do
  begin
    Cmt := Sheet.ThreadedComments[i];
    if Cmt.ParentId = '' then
      Writeln('Root at ', Cmt.Ref, ' by ', Cmt.DisplayName, ': ', Cmt.Text)
    else
      Writeln('  reply by ', Cmt.DisplayName, ': ', Cmt.Text);
  end;
  Writeln('Participants: ', Book.Persons.Count);
end;

Ukladanie vo forme plochého zoznamu s odkazmi sa tu prejavuje zámerne: ThreadedComments vymenúva odpovede v poradí častí a prázdne pole ParentId identifikuje každý začiatok (koreň) vlákna. Ak potrebujete stromovú štruktúru — napríklad pre export denníka posudzovania — zoskupte ich najprv podľa Ref a potom v rámci každej skupiny bunky prepojte ParentId s Id. Toto zachovanie pôvodnej štruktúry je príkladom širšieho prístupu v knižnici; článok o bezstratovom prenose tém, zoznamov rozšírení a kalkulačného reťazca podrobne popisuje, ako sa rovnaký princíp uplatňuje na zvyšok balíka

Stav vyriešenia, časové pečiatky a identita autora

Tri atribúty nesú sémantiku posudzovania a všetky tri sú na vrátených objektoch zapisovateľné. Done sa mapuje na atribút done — Excel zobrazuje vyriešené vlákno zbalené s odkazom na Znovu otvoriť. DateTime je časová pečiatka vytvorenia ISO-8601 UTC (dT); HotXLS pri jej vynechaní doplní fixnú hodnotu, aby časť zostala platná, no skutočná pečiatka robí históriu čitateľnou, preto ju nastavujte. Na strane identity každý TXLSXPerson sprístupňuje vlastnosť ProviderId — zvyčajne None pre lokálne vytvorené záznamy — a UserId, ktorý môžete naplniť UPN menom alebo e-mailom, ak ho vaša aplikácia pozná:

var
  Root: TXLSXThreadedComment;
  Person: TXLSXPerson;
begin
  Root := Sheet.ThreadedComments.FindAt('D9');
  if Root <> nil then
    Root.Done := True;   // saved as done="1"; Excel shows the thread resolved

  Person := Book.Persons.FindByDisplayName('Maria Ortiz');
  if Person <> nil then
    Person.UserId := 'maria.ortiz@example.com';
end;

Ešte jedno obmedzenie, ktoré treba uviesť priamo: HotXLS zapisuje element <mentions> prázdny. Záznamy @-mention — mechanizmus, ktorý zvýrazňuje meno kolegu v texte komentára a spúšťa notifikáciu v Microsoft 365 — nie sú modelované, takže text obsahujúci znak @ sa ukladá ako prostý text. Pri vygenerovanom zošite pre recenzie je to málokedy prekážkou, no ak váš proces závisí od notifikácií zmienok, počítajte s tým, že ich bude musieť doplniť človek priamo v Exceli. Identita autora v časti person sa prirodzene spája s poľami pôvodu na úrovni zošita, popísanými v metadátach zošita a vlastnostiach dokumentu, kde sa nachádza aj zvyšok auditnej stopy vygenerovaného súboru

Čo robia staršie verzie Excelu s vláknovými komentármi?

Excel 2016 a staršie verzie vznikli pred zavedením vláknového modelu a časti, ktorým nerozumejú, jednoducho ignorujú. Keď samotný Excel 365 ukladá vláknovú konverzáciu, zapisuje aj tieň staršieho komentára — zástupnú poznámku s textom „[Threaded comment]...“ — presne preto, aby staršie verzie zobrazili aspoň niečo na priradenej bunke. HotXLS generuje iba vláknové časti bez tohto tieňa, takže súbor vytvorený vaším kódom nezobrazí pri otvorení v Exceli 2016 žiadnu indikáciu komentára. Ak vaše cieľové publikum zahŕňa verzie staršie ako 365 a poznámka tam musí byť viditeľná, kompatibilným kanálom zostáva pôvodné API AddComment; vyhnite sa však kombinovaniu oboch modelov na rovnakej bunke bez otestovania verzií Excelu, pretože to, ako sa čítač vyrovná s poznámkou a vláknom na jednej bunke, závisí od samotného programu a nie od vás

Druhou pevnou hranicou je samotný formát súboru. Vláknové komentáre sú štruktúrou formátu OOXML bez ekvivalentu v BIFF8, takže .xls časť knižnice HotXLS neobsahuje vláknové API — zošit, ktorý musí zostavať v pôvodnom binárnom formáte, je obmedzený len na klasické poznámky. Rozhodovacia tabuľka v praxi je krátka: pri zápise .xlsx pre Excel 365 alebo webové/mobilné čítačky použite AddThreadedComment a získate skutočné konverzácie; ak mierite na Excel 2016 alebo .xls, použite AddComment a akceptujte poznámky; ak kontrolujete prijatý súbor, preverte ako ThreadedComments tak aj Comments, pretože zošit prechádzajúci oboma svetmi môže legitímne niesť obe formy. Celé rozhranie API pre obe generácie je zdokumentované na produktovej stránke HotXLS Delphi Excel Component