Справка по API

# XLSX.XLSXFile — Type

XLSXFile представляет собой ссылку на файл Excel.

Он создается с использованием XLSX.readxlsx или XLSX.openxlsx.

Из XLSXFile можно перейти к ссылке XLSX.Worksheet, как показано в примере ниже.

Пример

xf = XLSX.readxlsx("myfile.xlsx")
sh = xf["mysheet"] # получает ссылку на лист (worksheet)

# XLSX.readxlsx — Function

readxlsx(source::Union{AbstractString, IO}) :: XLSXFile

Основная функция для чтения Excel-файла. Эта функция считывает весь Excel-файл в память и возвращает закрытый XLSX-файл.

Рассмотрите возможность использования XLSX.openxlsx для отложенной загрузки содержимого Excel-файла.

# XLSX.openxlsx — Function

openxlsx(f::F, source::Union{AbstractString, IO}; mode::AbstractString="r", enable_cache::Bool=true) where {F<:Function}

Открывает XLSX-файл для чтения и (или) записи. Возвращает открытый XLSX-файл, который будет автоматически закрыт после применения f к файлу.

Синтаксис Do

Эту функцию следует использовать с синтаксисом do, как показано ниже:

XLSX.openxlsx("myfile.xlsx") do xf
    # считывает данные из `xf`
end

Режимы работы с файлами

Аргумент mode управляет способом открытия файла. Разрешены следующие режимы:

r: режим чтения. Существующие данные в source будут доступны для чтения. Это поведение по умолчанию.
w: режим записи. Открывает пустой файл, который будет записан в source.
rw: режим редактирования. Открывает source для редактирования. По окончании работы функции файл будет сохранен на диск.

Известно, что режим rw приводит к некоторой потере данных. См. проблему #159. Простые данные должны работать нормально. Пользователям рекомендуется с осторожностью использовать эту функцию при работе с формулами и диаграммами.

Аргументы

source является вводом-выводом или полным путем к файлу.
mode является режимом работы с файлами, как было описано в предыдущем разделе.
enable_cache:

Если enable_cache=true, все считанные ячейки листа будут кэшироваться. Если ячейка листа считывается дважды, вместо чтения с диска во второй раз будет использоваться кэшированное значение.

Если enable_cache=false, ячейки листа будут всегда считываться с диска. Рекомендуется использовать, если требуется считать таблицу, которая не помещается в памяти.

Значение по умолчанию — enable_cache=true.

Примеры

Чтение из файла

В следующем примере показано чтение ячеек листа по одной строке за раз, где myfile.xlsx является таблицей, которая не помещается в памяти.

julia> XLSX.openxlsx("myfile.xlsx", enable_cache=false) do xf
          for r in XLSX.eachrow(xf["mysheet"])
              # считывает что-то из строки `r`
          end
       end

Запись нового файла

XLSX.openxlsx("new.xlsx", mode="w") do xf
    sheet = xf[1]
    sheet[1, :] = [1, Date(2018, 1, 1), "test"]
end

Редактирование существующего файла

XLSX.openxlsx("edit.xlsx", mode="rw") do xf
    sheet = xf[1]
    sheet[2, :] = [2, Date(2019, 1, 1), "add new line"]
end

См. также описание функции XLSX.readxlsx.

openxlsx(source::Union{AbstractString, IO}; mode="r", enable_cache=true) :: XLSXFile

Поддерживает открытие XLSX-файла без использования do-синтаксиса. В этом случае пользователь отвечает за закрытие XLSXFile с помощью close или его записи в файл с помощью XLSX.writexlsx.

См. также описание функции XLSX.writexlsx.

# XLSX.writexlsx — Function

writexlsx(output_source, xlsx_file; [overwrite=false])

Записывает Excel-файл, заданный с помощью xlsx_file::XLSXFile, в ввод-вывод или путь к файлу output_source.

Если overwrite=true, output_source (когда это путь к файлу) будет перезаписан, если он существует.

# XLSX.sheetnames — Function

sheetnames(xl::XLSXFile)
sheetnames(wb::Workbook)

Возвращает вектор с именами листов для данной книги.

# XLSX.sheetcount — Function

sheetcount(xlsfile) :: Int

Подсчитывает количество листов в книге.

# XLSX.Worksheet — Type

Worksheet представляет собой ссылку на лист (worksheet) файла Excel.

Из Worksheet можно запрашивать ячейки, значения ячеек и диапазоны.

Пример

xf = XLSX.readxlsx("myfile.xlsx")
sh = xf["mysheet"] # получает ссылку на лист (worksheet)
println( sh[2, 2] ) # обращается к элементу B2 (2-я строка, 2-й столбец)
println( sh["B2"] ) # также можно использовать имя ячейки
println( sh["A2:B4"] ) # или диапазон ячеек
println( sh[:] ) # все данные внутри измерения листа

# XLSX.readdata — Function

readdata(source, sheet, ref)
readdata(source, sheetref)

Возвращает скаляр или матрицу со значениями из таблицы.

См. также описание функции XLSX.getdata.

Примеры

Эти вызовы функций эквивалентны.

julia> XLSX.readdata("myfile.xlsx", "mysheet", "A2:B4")
3×2 Array{Any,2}:
 1  "first"
 2  "second"
 3  "third"

julia> XLSX.readdata("myfile.xlsx", 1, "A2:B4")
3×2 Array{Any,2}:
 1  "first"
 2  "second"
 3  "third"

julia> XLSX.readdata("myfile.xlsx", "mysheet!A2:B4")
3×2 Array{Any,2}:
 1  "first"
 2  "second"
 3  "third"

# XLSX.getdata — Function

getdata(sheet, ref)
getdata(sheet, row, column)

Возвращает скаляр или матрицу со значениями из таблицы. ref может быть ссылкой на ячейку или диапазоном.

Индексирование в Worksheet приведет к диспетчеризации в метод getdata.

Пример

julia> f = XLSX.readxlsx("myfile.xlsx")

julia> sheet = f["mysheet"]

julia> matrix = sheet["A1:B4"]

julia> single_value = sheet[2, 2] # B2

См. также описание функции XLSX.readdata.

getdata(ws::Worksheet, cell::Cell) :: CellValue

Возвращает представление Julia заданного значения ячейки. Тип данных результата выбирается в зависимости от значения ячейки, а также ее стиля.

Например, дата хранится в электронной таблице в виде целых чисел, а стиль — это информация, которая учитывается при выборе Date в качестве типа результата.

Для чисел, если стиль подразумевает, что число визуализируется с десятичными знаками, метод вернет значение с плавающей запятой, даже если в XML таблицы число хранится как целое.

Если ячейка (cell) имеет пустое значение или пустую строку (String), данная функция вернет missing.

# XLSX.getcell — Function

getcell(xlsxfile, cell_reference_name) :: AbstractCell
getcell(worksheet, cell_reference_name) :: AbstractCell
getcell(sheetrow, column_name) :: AbstractCell
getcell(sheetrow, column_number) :: AbstractCell

Возвращает внутреннее представление ячейки листа.

Возвращает XLSX.EmptyCell, если в ячейке нет данных.

getcell(sheet, ref)

Возвращает ячейку AbstractCell, представляющую ячейку в электронной таблице.

Пример:

julia> xf = XLSX.readxlsx("myfile.xlsx")

julia> sheet = xf["mysheet"]

julia> cell = XLSX.getcell(sheet, "A1")

# XLSX.getcellrange — Function

getcellrange(sheet, rng)

Возвращает матрицу с ячейками в виде Array{AbstractCell, 2}. rng должен быть допустимым диапазоном ячеек, как в "A1:B2".

# XLSX.row_number — Function

row_number(c::CellRef) :: Int

Возвращает номер строки заданной ссылки на ячейку.

# XLSX.column_number — Function

column_number(c::CellRef) :: Int

Возвращает номер столбца заданной ссылки на ячейку.

# XLSX.eachrow — Function

eachrow(sheet)

Создает итератор строк для листа.

Пример: запрос всех ячеек из столбцов с 1 по 4.

left = 1  # 1-й столбец
right = 4 # 4-й столбец
for sheetrow in XLSX.eachrow(sheet)
    for column in left:right
        cell = XLSX.getcell(sheetrow, column)

        # выполняет какие-либо действия с ячейкой
    end
end

# XLSX.readtable — Function

readtable(
    source,
    sheet,
    [columns];
    [first_row],
    [column_labels],
    [header],
    [infer_eltypes],
    [stop_in_empty_row],
    [stop_in_row_function],
    [keep_empty_rows]
) -> DataTable

Возвращает табличные данные из электронной таблицы в виде структуры XLSX.DataTable. Используйте эту функцию для создания DataFrame из пакета DataFrames.jl.

Используйте аргумент columns, чтобы указать, какие столбцы необходимо получить. Например, "B:D" выберет столбцы B, C и D. Если значение columns не задано, алгоритм найдет первую последовательность идущих подряд непустых ячеек.

Используйте first_row, чтобы указать первую строку таблицы. first_row=5 будет искать таблицу, начинающуюся со строки листа 5. Если значение first_row не задано, алгоритм будет искать первую непустую строку в таблице.

header — это логическое значение (Bool), указывающее, является ли первая строка заголовком. Если header=true и column_labels не указаны, надписи столбцов таблицы будут считываться из первой строки таблицы. Если header=false и column_labels не указаны, алгоритм создаст надписи столбцов. Значение по умолчанию — header=true.

Используйте column_labels, чтобы указать имена для заголовка таблицы.

Используйте infer_eltypes=true, чтобы получить data в виде Vector{Any} типизированных векторов. Значение по умолчанию — infer_eltypes=false.

stop_in_empty_row является логическим значением, указывающим, обозначает ли пустая строка конец таблицы. Если stop_in_empty_row=false, TableRowIterator будет продолжать извлекать строки до тех пор, пока на листе не останется ни одной строки. Поведение по умолчанию — stop_in_empty_row=true.

stop_in_row_function является функцией, которая принимает TableRow и возвращает Bool, указывая, достигнут ли конец таблицы.

Пример для stop_in_row_function:

function stop_function(r)
    v = r[:col_label]
    return !ismissing(v) && v == "unwanted value"
end

keep_empty_rows определяет, сохранять (true) или отбрасывать (false) из результирующей таблицы строки, в которых все значения столбцов равны missing. keep_empty_rows никогда не влияет на границы таблицы. На количество строк, считываемых с листа, влияют только first_row, stop_in_empty_row и stop_in_row_function (если они указаны). keep_empty_rows проверяется только после того, как определены первая и последняя строки таблицы, чтобы определить, оставлять или отбрасывать пустые строки между первой и последней строками.

Пример

julia> using DataFrames, XLSX

julia> df = DataFrame(XLSX.readtable("myfile.xlsx", "mysheet"))

См. также описание: XLSX.gettable.

# XLSX.gettable — Function

gettable(
    sheet,
    [columns];
    [first_row],
    [column_labels],
    [header],
    [infer_eltypes],
    [stop_in_empty_row],
    [stop_in_row_function],
    [keep_empty_rows]
) -> DataTable

header — это логическое значение (Bool), указывающее, является ли первая строка заголовком. Если header=true и column_labels не указаны, надписи столбцов таблицы будут считываться из первой строки таблицы. Если header=false и column_labels не указаны, алгоритм создаст заголовки столбцов. Значение по умолчанию — header=true.

Используйте column_labels в качестве вектора символов, чтобы указать имена для заголовка таблицы.

Пример для stop_in_row_function

function stop_function(r)
    v = r[:col_label]
    return !ismissing(v) && v == "unwanted value"
end

Пример

julia> using DataFrames, XLSX

julia> df = XLSX.openxlsx("myfile.xlsx") do xf
        DataFrame(XLSX.gettable(xf["mysheet"]))
    end

См. также описание: XLSX.readtable.

# XLSX.eachtablerow — Function

eachtablerow(sheet, [columns]; [first_row], [column_labels], [header], [stop_in_empty_row], [stop_in_row_function], [keep_empty_rows])

Создает итератор строк таблицы. Каждый элемент итератора имеет тип TableRow.

header — это логическое значение, указывающее, является ли первая строка таблицы заголовком таблицы.

Если header == false и column_labels не указаны, имена столбцов будут сгенерированы в соответствии с именами столбцов, содержащимися в Excel-файле.

Аргумент columns представляет собой диапазон столбцов, как в "B:E". Если columns не указан, диапазон столбцов будет определяться по непустым смежным ячейкам в первой строке таблицы.

Пользователь может заменить имена столбцов, присвоив необязательную входную переменную column_labels с помощью Vector{Symbol}.

stop_in_empty_row является логическим значением, указывающим, обозначает ли пустая строка конец таблицы. Если stop_in_empty_row=false, итератор будет продолжать извлекать строки до тех пор, пока на листе не останется ни одной строки. Поведение по умолчанию — stop_in_empty_row=true. Итератор может возвращать пустые строки, когда stop_in_empty_row=false.

Пример для stop_in_row_function:

function stop_function(r)
    v = r[:col_label]
    return !ismissing(v) && v == "unwanted value"
end

keep_empty_rows определяет, будет ли итератор строк сохранять (true) или пропускать (false) строки, в которых все значения столбцов равны missing. keep_empty_rows никогда не влияет на границы итератора. На количество строк, считываемых с листа, влияют только first_row, stop_in_empty_row и stop_in_row_function (если они указаны). keep_empty_rows проверяется только после того, как определены первая и последняя строки таблицы, чтобы определить, оставлять или отбрасывать пустые строки между первой и последней строками.

Пример кода:

for r in XLSX.eachtablerow(sheet)
    # r - это `TableRow`. Значения считываются с помощью заголовков или номеров столбцов.
    rn = XLSX.row_number(r) # номер строки `TableRow`.
    v1 = r[1] # будет считывать значение в столбце 1 таблицы.
    v2 = r[:COL_LABEL2] # будет считывать значение в столбце с заголовком `:COL_LABEL2`.
end

См. также описание функции XLSX.gettable.

# XLSX.writetable — Function

writetable(filename, table; [overwrite], [sheetname])

Записывает Tables.jl table в указанный файл.

writetable(filename::AbstractString, tables::Vector{Pair{String, T}}; overwrite::Bool=false)
writetable(filename::AbstractString, tables::Pair{String, Any}...; overwrite::Bool=false)

writetable(filename, data, columnnames; [overwrite], [sheetname])

data является вектором столбцов.
columnames является вектором заголовков столбцов.
overwrite является логическим значением (Bool), управляющим необходимостью перезаписи файла (filename), если он уже существует.
sheetname является именем листа.

Пример

import XLSX
columns = [ [1, 2, 3, 4], ["Hey", "You", "Out", "There"], [10.2, 20.3, 30.4, 40.5] ]
colnames = [ "integers", "strings", "floats" ]
XLSX.writetable("table.xlsx", columns, colnames)

См. также описание: XLSX.writetable!.

writetable(filename::AbstractString; overwrite::Bool=false, kw...)
writetable(filename::AbstractString, tables::Vector{Tuple{String, Vector{Any}, Vector{String}}}; overwrite::Bool=false)

Записывает несколько таблиц.

kw является списком именованных аргументов переменной. Каждый элемент должен иметь следующий формат: sheetname=( data, column_names ), data является вектором столбцов, а column_names — вектором заголовков столбцов.

Пример:

julia> import DataFrames, XLSX

julia> df1 = DataFrames.DataFrame(COL1=[10,20,30], COL2=["Fist", "Sec", "Third"])

julia> df2 = DataFrames.DataFrame(AA=["aa", "bb"], AB=[10.1, 10.2])

julia> XLSX.writetable("report.xlsx", "REPORT_A" => df1, "REPORT_B" => df2)

# XLSX.writetable! — Function

writetable!(sheet::Worksheet, table; anchor_cell::CellRef=CellRef("A1")))

Записывает Tables.jl table на указанный лист.

writetable!(sheet::Worksheet, data, columnnames; anchor_cell::CellRef=CellRef("A1"))

Записывает на лист (sheet) табличные данные data с заголовками, заданными columnnames, начиная с anchor_cell.

data должен быть вектором столбцов. columnnames должен быть вектором заголовков столбцов.

См. также описание: XLSX.writetable.

# XLSX.rename! — Function

rename!(ws::Worksheet, name::AbstractString)

Переименовывает Worksheet.

# XLSX.addsheet! — Function

addsheet!(workbook, [name]) :: Worksheet

Создает новый лист с именованным name. Если имя (name) не указано, создается уникальное имя.