Giới thiệu về gem Spreadsheet

I. Giới thiệu

Thư viện Spreadsheet được thiết kế để đọc và ghi các tài liệu Spreadsheet. Với bản 0.6.0 thì chỉ có Microsoft Excel là phù hợp mà được hộ trợ. Spreadsheet được viết bởi Daniel J. Berger và Hannes Wyss. Nó là một trong những thư viện nổi tiếng để xuất Excel trong Rails. Hiện tại Nó có tổng số lượt tải về lên đến 4,5 triệu lượt.

II. Những hướng dẫn cơ bản sử dụng thư viện

Giống như các gem khác để sử dụng được thì điều đầu tiên ta phải cài đặt.

    require "spreadsheet"

Sau khi cài đặt xong ta sẽ cùng tìm hiểu các tính năng của gem này.

1. Việc đọc dễ dàng hơn

Worksheet có thể mã hóa nhiều kiểu khác nhau. Bạn cần thiết phải cài đặt cách mà hóa nào mà bạn muốn cho ứng ụng của bạn. Mã hóa mặc định sẽ là UTF-8.

    Spreadsheet.client_encoding = 'UTF-8'

Để mở một workbook:

    book = Spreadsheet.open '/path/to/an/excel-file.xls'

Chúng ta có thể truy cập vào tất cả các worksheets trong một workbook bằng câu lệnh:

    book.worksheets

... hoặc có thể truy nhập vào worksheet cụ thể nào đó bằng index hoặc tên của nó.

    sheet1 = book.worksheet 0
    sheet2 = book.worksheet 'Sheet1'

Sau khi đã truy cập vào được worksheet thì ta có thể lấy dự liệu trong trong đó bằng cách gọi Worksheet.each. Mặc đinh là bắt đầu từ hàng số 0;

    sheet1.each do |row|
      # Làm bất cứ thứ gì bạn thích với các row ở phần này
    end

hoặc bạn có thể bắt đầu lấy dữ liệu từ hàng thứ 3 bằng cách.

    sheet2.each 2 do |row|
      # Làm bất cứ thứ gì bạn thích với các row ở phần này
    end

hoặc nếu muốn truy nhập để lấy dữ liệu ở 1 hàng cụ thể nào đó.

    row = sheet1.row(3)

Sau khi truy cập được vào 1 hàng thì ta có thể truy cập đến bất kì dữ liệu ở ô nào bạn muốn. Bạn coi row giống như là 1 cái mảng một chiều. Và truy cập đến các cột trong 1 hàng trống như truy cập đến các phần tử trong một mảng.

    row[0]

Giá trị trả về của có thể là một kiểu String, một kiểu Float, một kiểu Integer.. hoặc là nil nếu ô đấy là trống. Hơn nữa bạn có thể format ô cụ thể bằng cách.

    row.format 2

2. Việc ghi dễ dàng hơn

Như ở phần trên, để bắt đầu ta phải mã hóa UTF-8, sau đó tạo một Workbook mới:

    book = Spreadsheet::Workbook.new

Thêm một Worksheet và truy nhập vào bằng cách:

    sheet1 = book.create_worksheet

Hoặc đặt tên cho Worksheet:

    sheet2 = book.create_worksheet :name => 'My Second Worksheet'
    sheet1.name = 'My First Worksheet'

Bây giờ chúng ta có thể đưa dữ liệu vào Worksheet qua các câu lệnh dưới đây:

    sheet1.row(0).concat %w{Name Country Acknowlegement}
    sheet1[1,0] = 'Japan'
    row = sheet1.row(1)
    row.push 'Creator of Ruby'
    row.unshift 'Yukihiro Matsumoto'
    sheet1.row(2).replace [ 'Daniel J. Berger', 'U.S.A.',
                            'Author of original code for Spreadsheet::Excel' ]
    sheet1.row(3).push 'Charles Lowe', 'Author of the ruby-ole Library'
    sheet1.row(3).insert 1, 'Unknown'
    sheet1.update_row 4, 'Hannes Wyss', 'Switzerland', 'Author'

Thêm một vài format để đẹp hơn qua đoạn:

    sheet1.row(0).height = 18

    format = Spreadsheet::Format.new :color => :blue,
                                     :weight => :bold,
                                     :size => 18
    sheet1.row(0).default_format = format

    bold = Spreadsheet::Format.new :weight => :bold
    4.times do |x| sheet1.row(x + 1).set_format(0, bold) end

Cuối cùng tạo file Excel:

    book.write '/path/to/output/excel-file.xls'

3. Thay đổi file đã tồn tại

Spreadsheet có một vài giới hạn trong việc hỗ trợ để thay đổi một file đã tồn tại. Nó thực hiện bằng cách copy các phần của một file Excel mà Spreadsheet không thế thay đổi, tính toán lại offset và gui lại dữ liệu thay đổi. Đây là nhưng chuwscs năng mà Spreadssheet có thể làm

• Thêm, thay đổi và xóa cells.
• Bạn có thể ghi dữ liệu được tính bằng công thức xác định trước.

Hạn chế:

• Spreadsheet chỉ có thể ghi BIFF8 (Excel97 hoặc cao hơn).
• Spreadsheet không thể thay đổi định dạng hiện tại. Điều đó có ý nghĩa đặc biệt nếu bạn cài đặt giá trị của 1 Cell thành 1 ngày, Nó chỉ có thể được đọc như 1 ngày nếu định dạng của nó đã được cài trước để thay đổi.
• Mặc dù về lý thuyết, nó không khuyến khích để ghi tài liệu kết quả trở lại cùng File/IO mà nó đọc. Và đây là đọạn code để chạy:

    book = Spreadsheet.open '/path/to/an/excel-file.xls'
 sheet = book.worksheet 0
 sheet.each do |row|
   row[0] *= 2
 end
 book.write '/path/to/output/excel-file.xls'

Hoặc bạn có thể trực tiếp truy nhập vào cell mà bạn muốn và thêm câu của bạn vào nó:

  sheet.rows[2][1] = "X"

4. Kiểu ngày và Kiểu ngày giờ

Trong Excel không chia rõ định dạng các kiểu của ngày. Thay vì đó, nó mà hóa kiểu ngày thành số dấu phẩy động và nhận dạng một Cell kiểu ngày bằng định dạng string của nó.

    row.format(3).number_format

Bất cứ khi nào một định dạng Cell biểu diễn kiểu Date hoăc Time thì Spreadsheet sẽ giúp bạn giải mã các giá trị kiểu Date và DateTime. Nên bạn cần thiết truy nhập các Float cơ bản, thì bạn cần làm như sau:

   row.at(3)

Nếu có lý do nào đấy mà không tự động convert được thì bạn phải làm thủ công nhu sau:

    row.date(3)
    row.datetime(3)

Ngoài ra bạn có thể ghi kiểu Date vào trong Cell bằng cách:

   row[4] = Date.new 1975, 8, 21
   # -> assigns the builtin Date-Format: 'M/D/YY'
   book.add_format Format.new(:number_format => 'DD.MM.YYYY hh:mm:ss')
   row[5] = DateTime.new 2008, 10, 12, 11, 59
   # -> assigns the added DateTime-Format: 'DD.MM.YYYY hh:mm:ss'
   row.set_format 6, Format.new(:number_format => 'D-MMM-YYYY')
   row[6] = Time.new 2008, 10, 12
   # -> the Format of cell 6 is left unchanged.

5. Outline (Grouping) và Hiding

Spreadsheet hỗ trợ các chức năng outline (grouping) và hiding tù phiên bản 0.6.5. Để có thể ẩn được các hàng và các cột, thì bạn có thể sử dụng thuộc tính 'hidden'. Cũng như cho outline, thuộc tính 'outline_level' cũng có sẵn . Bạn có thể sử dụng cả 'hidden' và 'outline_level' cùng nhau. Bạn có thẻ tạo một file mới với các cột và các dòng outline và hiding như sau:

  require 'spreadsheet'

  # create a new book and sheet
  book = Spreadsheet::Workbook.new
  sheet = book.create_worksheet
  5.times {|j| 5.times {|i| sheet[j,i] = (i+1)*10**j}}

  # column
  sheet.column(2).hidden = true
  sheet.column(3).hidden = true
  sheet.column(2).outline_level = 1
  sheet.column(3).outline_level = 1

  # row
  sheet.row(2).hidden = true
  sheet.row(3).hidden = true
  sheet.row(2).outline_level = 1
  sheet.row(3).outline_level = 1

  # save file
  book.write 'out.xls'

Bạn cũng có thể đọc một file đã tồn tại và thay đổi thuộc tính hidden và outline:

  require 'spreadsheet'

  # read an existing file
  file = ARGV[0]
  book = Spreadsheet.open(file, 'rb')
  sheet= book.worksheet(0)

  # column
  sheet.column(2).hidden = true
  sheet.column(3).hidden = true
  sheet.column(2).outline_level = 1
  sheet.column(3).outline_level = 1

  # row
  sheet.row(2).hidden = true
  sheet.row(3).hidden = true
  sheet.row(2).outline_level = 1
  sheet.row(3).outline_level = 1

  # save file
  book.write "out.xls"

Để truy nhập để xuất file thì ta cần làm như sau:

file_contents = StringIO.new
book.write file_contents

III. Kết luận

Spreadsheet là một gem được sử dụng phổ biến bởi tính dễ dùng và dễ controll dữ liệu, format để tạo 1 file Excel trong Ruby On Rails. Bài viết đã được dịch và lược bớt những phần không quan trọng để tránh làm rối mắt người đọc.

Bài viết tham khảo từ

https://github.com/zdavatz/spreadsheet/blob/master/GUIDE.md