📊 Práce s XLSX tabulkami

CLua obsahuje sadu funkcí pro načítání, čtení a úpravu .xlsx souborů. Tyto funkce využívají backend v C# přes knihovnu ClosedXML a jsou dostupné přes jednoduché Lua API.

📁 Struktura souborů

• Excelové tabulky se nachází ve složce:

  Tables/

• Jsou načítány podle potřeby jednotlivými makry.

📥 Načtení a vytvoření sešitu

Načtení existujícího sešitu

local wb = Workbook("NazevSouboru.xlsx");

• Workbook(path) vytvoří objekt pracovního sešitu (wb).
• Cesta musí být relativní ke složce Tables/.

Vytvoření nového sešitu

local wb = NewWorkbook("NovySesit.xlsx");

• Vytvoří nový prázdný sešit.
• Pokud soubor již existuje, vrátí chybu.

Vytvoření nebo načtení sešitu

local wb = NewWorkbook("Sesit.xlsx", true);

• Druhý parametr true znamená: pokud soubor existuje, načti ho; jinak vytvoř nový.
• Užitečné pro skripty, které potřebují pracovat se sešitem bez ohledu na to, zda existuje.

📄 Přístup k listům (Sheet)

local sheet = wb:Sheet("JménoListu");

• Vrací objekt listu, ze kterého lze číst nebo do kterého lze zapisovat.

Správa listů

-- Přidání nového listu
wb:AddSheet("NovýList");

-- Přejmenování listu
wb:RenameSheet("StaréJméno", "NovéJméno");

-- Smazání listu
wb:DeleteSheet("NepotřebnýList");

-- Získání seznamu všech listů
local sheetNames = wb:GetSheetNames();
for i, name in ipairs(sheetNames) do
    print(i, name);
end

🔎 Kontrola existence

local isWb = WorkbookExists("jménoSešitu.xlsx");
local isSheet = wb:ContainSheet("JménoListu");

• Vrací boolean hodnotu, jestli daný sešit existuje.
• Vrací boolean hodnotu, jestli sešit daný list obsahuje.

📋 Cell objekty

Cell objekt reprezentuje jednu buňku v tabulce a umožňuje elegantní práci s jejím obsahem a formátováním.

Vytvoření Cell objektu

local cell = sheet:Cell(5, 3);  -- řádek 5, sloupec 3

Chaining metod

Cell objekty podporují chaining - zřetězení více operací:

sheet:Cell(1, 1)
    :SetValue("Nadpis")
    :SetBold(true)
    :SetFontSize(14)
    :SetBackgroundColor("#4472C4")
    :SetFontColor("#FFFFFF")
    :SetAlignment("Center", "Center");

🔍 Čtení hodnot

Základní čtení

-- String hodnota
local value = sheet:GetCell(3, 2);  -- zpětná kompatibilita
local value = sheet:Cell(3, 2):GetS(); 

-- Typovaná hodnota (number, string, boolean, atd.)
local value = sheet:Cell(3, 2):Get();

-- Přes Cell objekt
local cell = sheet:Cell(3, 2);
local value = cell:Get();  -- typovaná
local text = cell:GetS();        -- string

• Pozor: indexace řádků a sloupců začíná od 1 (jako v Excelu), nikoliv od 0.

Čtení formátování

local cell = sheet:Cell(5, 3);

-- Font
local isBold = cell:GetBold();
local isItalic = cell:GetItalic();
local isUnderline = cell:GetUnderline();
local isStrikethrough = cell:GetStrikethrough();
local fontSize = cell:GetFontSize();
local fontName = cell:GetFontName();

-- Barvy (vrací hex string, např. "#FF0000")
local bgColor = cell:GetBackgroundColor();
local fontColor = cell:GetFontColor();

-- Zarovnání
local hAlign = cell:GetHorizontalAlignment();  -- "Left", "Center", "Right", "Justify"
local vAlign = cell:GetVerticalAlignment();    -- "Top", "Center", "Bottom", "Justify"
local isWrapped = cell:GetWrapText();

-- Ohraničení
local topBorder = cell:GetBorderTop();      -- "None", "Thin", "Medium", "Thick", atd.
local bottomBorder = cell:GetBorderBottom();
local leftBorder = cell:GetBorderLeft();
local rightBorder = cell:GetBorderRight();

-- Formát čísel
local format = cell:GetNumberFormat();  -- např. "#,##0.00"

-- Formula
local formula = cell:GetFormula();  -- např. "=SUM(A1:A10)" nebo nil
local hasFormula = cell:HasFormula();

-- Sloučené buňky
local isMerged = cell:IsMerged();
local mergedRange = cell:GetMergedRange();  -- např. "A1:C1" nebo nil

-- Adresa buňky
local address = cell:GetAddress();  -- např. "C5"

Detailní informace o buňce

local cellInfo = sheet:CellEx(5, 3);

-- cellInfo obsahuje všechny možné vlastnosti:
-- value, format, formula, dataType, isBold, isItalic, 
-- fontColor, bgColor, hAlign, vAlign, borders, 
-- richText, comment, atd.

print(cellInfo.value);
print(cellInfo.fontName);
if cellInfo.isBold then
    print("Buňka je tučná");
end

✍️ Zápis hodnot

Základní zápis

-- String 
sheet:SetCell(3, 2, "Text"); -- zpětná kompatibilita
sheet:Cell(3,2):SetS("Text");

-- Typovaná hodnota
sheet:Cell(3, 2):Set(123);      -- number
sheet:Cell(3, 2):Set(45.67);    -- float
sheet:Cell(3, 2):Set(true);     -- boolean
sheet:Cell(3, 2):Set("Text");   -- string

-- Přes Cell objekt
local cell = sheet:Cell(3, 2);
cell:SetValue(123);
cell:Set("Text");  -- string varianta

Formátování textu

local cell = sheet:Cell(1, 1);

-- Font
cell:SetBold(true);
cell:SetItalic(true);
cell:SetUnderline(true);
cell:SetStrikethrough(true);
cell:SetFontSize(14);
cell:SetFontName("Arial");

Barvy

local cell = sheet:Cell(1, 1);

-- Hex formát
cell:SetBackgroundColor("#FFFF00");
cell:SetFontColor("#FF0000");

-- RGB formát
cell:SetBackgroundColor(RGB(255, 255, 0));
cell:SetFontColor(RGB(255, 0, 0));

-- Theme barvy
cell:SetBackgroundColorTheme("Accent1");
cell:SetBackgroundColorTheme("Accent2", 0.5);  -- s tintem

-- Indexed barvy
cell:SetBackgroundColorIndexed(10);

Dostupné theme barvy:

• "Dark1", "Light1", "Dark2", "Light2"
• "Accent1", "Accent2", "Accent3", "Accent4", "Accent5", "Accent6"
• "Hyperlink", "FollowedHyperlink"
• "Text1", "Text2", "Background1", "Background2"

Zarovnání

local cell = sheet:Cell(1, 1);

-- Horizontální a vertikální zarovnání
cell:SetAlignment("Center", "Center");

-- Možnosti:
-- Horizontální: "Left", "Center", "Right", "Justify", "General"
-- Vertikální: "Top", "Center", "Bottom", "Justify"

-- Zalomení textu
cell:SetWrapText(true);  -- text se zalomí na více řádků

Ohraničení

local cell = sheet:Cell(1, 1);

-- Všechny strany najednou
cell:SetBorder("Thin");

-- Jen vnější ohraničení
cell:SetBorderOutside("Medium");

-- Jednotlivé strany
cell:SetBorderTop("Thick");
cell:SetBorderBottom("Thin");
cell:SetBorderLeft("Dashed");
cell:SetBorderRight("Dotted");

-- Styly: "None", "Thin", "Medium", "Thick", "Double", "Dotted", "Dashed"

Formát čísel

local cell = sheet:Cell(1, 1);

cell:SetNumberFormat("#,##0.00");      -- tisíce s čárkou, 2 des. místa
cell:SetNumberFormat("0.00%");         -- procenta
cell:SetNumberFormat("dd.mm.yyyy");    -- datum
cell:SetNumberFormat("hh:mm:ss");      -- čas

Formula

local cell = sheet:Cell(1, 1);

cell:SetFormula("=SUM(A1:A10)");
cell:SetFormula("=IF(B1>100, \"Vysoká\", \"Nízká\")");

-- Kontrola
if cell:HasFormula() then
    print("Formula:", cell:GetFormula());
end

Vymazání obsahu

local cell = sheet:Cell(1, 1);

cell:Clear();           -- smaže vše (hodnota + formátování)
cell:ClearContents();   -- smaže jen hodnotu, formátování zůstane
cell:ClearFormats();    -- smaže jen formátování, hodnota zůstane

📐 Práce s rozsahy (Ranges)

Poznámka: ERange je zkrácený alias pro Excel.Range — obě varianty jsou zaměnitelné.

ERange (alias Excel.Range) lze vytvořit více způsoby:

ERange(2, 1, 10, 5)       -- row1, col1, row2, col2
ERange("A1:E10")           -- string zápis
ERange("A1", "E10")        -- dvě adresy
ERange(cell1, cell2)       -- dva Cell objekty

-- Nastavení barvy pozadí pro rozsah
sheet:SetRangeBackgroundColor(ERange(2, 1, 10, 5), "#E0E0E0");

-- RGB varianta
sheet:SetRangeBackgroundColor(ERange(2, 1, 10, 5), RGB(224, 224, 224));

-- Tučné písmo pro rozsah
sheet:SetRangeBold(ERange(1, 1, 1, 5), true);

-- Ohraničení rozsahu
sheet:SetRangeBorder(ERange(1, 1, 10, 5), "Thin");

-- Sloučení buněk
sheet:MergeRange(ERange(1, 1, 1, 3));  -- sloučí řádek 1, sloupce 1-3

📏 Šířka sloupců a výška řádků

-- Nastavení šířky sloupce
sheet:SetColumnWidth(1, 25);

-- Automatické přizpůsobení šířky
sheet:AutoFitColumn(1);

-- Získání šířky
local width = sheet:GetColumnWidth(1);

-- Nastavení výšky řádku
sheet:SetRowHeight(1, 30);

-- Získání výšky
local height = sheet:GetRowHeight(1);

➕➖ Vkládání a mazání řádků/sloupců

-- Vložení řádku nad řádek 5
sheet:InsertRowAbove(5);

-- Smazání řádku 10
sheet:DeleteRow(10);

-- Vložení sloupce před sloupec 3
sheet:InsertColumnBefore(3);

-- Smazání sloupce 5
sheet:DeleteColumn(5);

🔍 Vyhledávání

Všechny vyhledávací funkce nyní vrací Cell objekty nebo tabulky Cell objektů.

Hledání v celém listu

-- Najde první výskyt
local cell = sheet:Find("Total");
if cell then
    print("Nalezeno na:", cell:GetAddress());
    cell:SetBold(true);
end

-- Najde všechny výskyty
local cells = sheet:FindAll("Error");
for _, cell in ipairs(cells) do
    cell:SetFontColor("#FF0000");
    print("Chyba na:", cell:GetAddress());
end

Hledání v rozsahu

-- Číselný rozsah
local cell = sheet:FindInRange("Sum", ERange(1, 1, 10, 5));

-- String rozsah
local cell = sheet:FindInRange("Total", ERange("A1:E10"));
local cell = sheet:FindInRange("Total", ERange("A1", "E10"));

-- 2 buňky tvořící protilehlé rohy
local cell = sheet:FindInRange("Sum", ERange(cell1, cell2));

-- Všechny výskyty v rozsahu
local cells = sheet:FindAllInRange("Error", ERange("A1:Z100"));

Hledání v řádku/sloupci

-- Najde v sloupci 1
local cell = sheet:FindInColumn("Total", 1);
local cell = sheet:FindInColumn("Control", 1, 5);  -- začít od řádku 5

-- Najde v řádku 1
local cell = sheet:FindInRow("Name", 1);
local cell = sheet:FindInRow("Price", 1, 3);  -- začít od sloupce 3

-- Všechny výskyty
local cells = sheet:FindAllInColumn("X", 1);
local cells = sheet:FindAllInRow("Header", 1);

📊 Rozsah listu

local rows, cols = sheet:GetSheetRange();
print("List má", rows, "řádků a", cols, "sloupců");

-- Procházení všech buněk
for row = 1, rows do
    for col = 1, cols do
        local value = sheet:Cell(row, col):Get();
        print(row, col, value);
    end;
end;

💾 Uložení změn a uzavření

wb:Save();
wb:SaveAs("adresa/novýNázev.xlsx");
wb:Close();

• wb:Save() uloží veškeré změny v rámci daného Workbook objektu. (Veškeré změny se projeví, až po uložení)
• Přepisuje původní .xlsx soubor.
• wb:SaveAs() uloží veškeré změny v do nového souboru.
• Nové workbooky je nutné uložit pomocí SaveAs.
• wb:Close() zavře otevřený sešit a jeho listy a uvolní paměť.

🧰 Pomocné funkce Excel modulu

-- Převod adresy na row, col
local row, col = Excel.AddressToRowCol("C5");  -- 5, 3

-- Převod row, col na adresu
local address = Excel.RowColToAddress(5, 3);  -- "C5"

-- Parsování rozsahu
local row1, row2, col1, col2 = Excel.ParseStringRange("A1:C10");

-- Index sloupce na písmeno
local letter = Excel.ColumnIndexToLetter(3);  -- "C"

-- Písmeno na index sloupce
local index = Excel.LetterToColumnIndex("C");  -- 3

-- Kontroly
local isCell = Excel.IsCellAddress("C5");     -- true
local isRange = Excel.IsRange("A1:C10");      -- true

-- Rozbalení rozsahu na jednotlivé adresy
local cells = Excel.ExpandRange("A1:B2");  -- {"A1", "A2", "B1", "B2"}

-- Normalizace rozsahu (levý horní roh, pravý dolní roh rozsahu)
local r1, r2, c1, c2 = Excel.NormalizeRange(10, 1, 5, 3);  -- 1, 10, 3, 5

-- Převod formátu na typ (heuristika)
local type = Excel.FormatToType("#,##0.00");  -- "number"

-- Vytvoření string rozsahu z row/col
local range = Excel.RangeToString(1, 10, 1, 5);  -- "A1:E10"

Příklad 1: Zpracování dat s vyhledáváním

local wb = Workbook("Units.xlsx");
local sheet = wb:Sheet("EngCon");

-- Najdeme buňku s textem "Control"
local controlCell = sheet:FindInColumn("Control", 1);
if controlCell then
    -- Zapíšeme hodnotu do řádku pod ní
    local dataCell = sheet:Cell(controlCell.row + 1, 5);
    dataCell:SetValue("Workshop");
    dataCell:SetBackgroundColor("#90EE90");

    print("Jednotka zapsána:", dataCell:GetValue());
else
    wb:Close();
    error("Nebyl nalezen Control.");
end

-- Najdeme všechny buňky s "Error" a označíme je
local errorCells = sheet:FindAll("Error");
for _, cell in ipairs(errorCells) do
    cell:SetFontColor("#FF0000")
        :SetBold(true)
        :SetBackgroundColor("#FFE0E0");
    print("Chyba na pozici:", cell:GetAddress());
end

wb:Save();
wb:Close();

Příklad 2: Formátování hlavičky tabulky

local wb = Workbook("Report.xlsx");
local sheet = wb:Sheet("Data");

-- Najdeme řádek s hlavičkami
local headerCells = sheet:FindAllInRow("Name", 1);

-- Naformátujeme celý řádek hlaviček
for _, cell in ipairs(headerCells) do
    -- Naformátujeme celý řádek hlaviček
    local row = cell.row;

    for col = 1, 10 do
        sheet:Cell(row, col)
            :SetBold(true)
            :SetBackgroundColor("#4472C4")
            :SetFontColor("#FFFFFF")
            :SetAlignment("Center", "Center")
            :SetBorder("Thin");
    end;

    break;  -- Stačí první nalezená
end;

-- AutoFit všech sloupců
for col = 1, 10 do
    sheet:AutoFitColumn(col);
end;

wb:Save();
wb:Close();

Příklad 3: Práce se Vzorci

local cell = sheet:Cell(1, 1);

cell:SetFormula("=SUM(A1:A10)");
cell:SetFormula("=IF(B1>100, \"Vysoká\", \"Nízká\")");

-- Kontrola
if cell:HasFormula() then
    print("Formula:", cell:GetFormula());
end

⚠️ Důležité upozornění o vzorcích:

CLua využívá ClosedXML, a ten nepřepočítává vzorce automaticky. Vzorce jsou zapsány do souboru, ale jejich výsledky budou vypočteny, až bude vyžádána value (skrz cell:Get()) nebo až při otevření souboru v Excelu, OfficeLibre či jiném programu..

sheet:Cell(1, 1):SetValue(10);
sheet:Cell(1, 2):SetValue(20);
sheet:Cell(1, 3):SetFormula("=A1+B1");

local result = sheet:Cell(1, 3):Get(); 

🧪 Tabulka všech funkcí

Workbook funkce

Sheet funkce - Základní operace

Sheet funkce - Vyhledávání

Všechny vrací Cell objekt nebo tabulku Cell objektů.

Sheet funkce - Sloupce a řádky

Sheet funkce - Formátování řádků

Sheet funkce - Formátování sloupců

Sheet funkce - Rozsahy

Sheet funkce - Zmrazení panelů

Cell funkce - Hodnoty

Cell funkce - Font formátování

Cell funkce - Barvy

Cell funkce - Zarovnání

Cell funkce - Ohraničení

Cell funkce - Formát čísel

Cell funkce - Čtení formátování

Excel pomocné funkce

RGB barvy

Pro barvy můžete použít pomocné funkce:

local barva = RGB(255, 200, 100)  -- {red=255, green=200, blue=100}
local cerna = BLACK()
local bila = WHITE()
local seda = GRAY(192)