Cài đặt và sử dụng — Spreadsheet

Tổng quan

@digiforce-nc/plugin-spreadsheet cung cấp giao diện bảng tính kiểu Excel cho phép xem, chỉnh sửa và chia sẻ dữ liệu trực tiếp trong trình duyệt. Plugin bao gồm cả Spreadsheet Block (nhúng trong trang) và Spreadsheet Page (trang riêng biệt với URL chia sẻ).

Bước 1: Kích hoạt Plugin

Vào Settings → Plugin Manager, tìm plugin-spreadsheet và bật. Khởi động lại server.

Sau khi kích hoạt:

• Bảng spreadsheet được tạo trong Database
• Mục Spreadsheet xuất hiện trong danh sách block
• Route /spreadsheet/:spreadsheetId được đăng ký (skipAuthCheck)

Bước 2: Tạo Spreadsheet Block

1. Trên trang, nhấn Add block → Spreadsheet
2. Block bảng tính hiển thị với giao diện giống Excel
3. Bắt đầu nhập dữ liệu trực tiếp vào các ô

Cấu hình Block

Click vào biểu tượng cấu hình (⚙️) trên Spreadsheet Block để truy cập các tùy chọn:

Tùy chọn	Mô tả
Name	Tên spreadsheet (hiển thị trên header)
Description	Mô tả mục đích của spreadsheet
Share Mode	Chế độ chia sẻ (xem bên dưới)
Height	Chiều cao block (px)

Bước 3: Chỉnh sửa dữ liệu

Thao tác cơ bản

Thao tác	Cách thực hiện
Chỉnh sửa ô	Click đúp vào ô hoặc nhấn phím bất kỳ khi ô đang được chọn
Di chuyển	Phím mũi tên, Tab (sang phải), Enter (xuống dưới)
Chọn nhiều ô	Shift + Click hoặc kéo chuột
Copy	Ctrl/Cmd + C
Paste	Ctrl/Cmd + V (hỗ trợ paste từ Excel/Google Sheets)
Undo	Ctrl/Cmd + Z
Redo	Ctrl/Cmd + Shift + Z

Copy/Paste từ Excel

Plugin hỗ trợ paste dữ liệu trực tiếp từ Excel hoặc Google Sheets:

1. Chọn vùng dữ liệu trong Excel → Copy
2. Chọn ô bắt đầu trong Spreadsheet → Paste
3. Dữ liệu được điền vào các ô tương ứng

Lưu ý: Paste giữ nguyên cấu trúc hàng/cột. Nếu vùng paste vượt ngoài kích thước hiện tại, spreadsheet tự động mở rộng.

Chế độ chia sẻ

Plugin hỗ trợ chia sẻ spreadsheet qua URL trực tiếp:

Chế độ	Mô tả
Private	Chỉ người có quyền truy cập
Public (view)	Ai có link đều xem được (chỉ đọc)
Public (edit)	Ai có link đều chỉnh sửa được

URL chia sẻ: https://your-domain.com/spreadsheet/<spreadsheetId>

Route này đăng ký với skipAuthCheck: true — người truy cập không cần đăng nhập (cho chế độ public).

Hệ thống Plugin mở rộng

Spreadsheet hỗ trợ hệ thống plugin và function mở rộng, cho phép tích hợp dữ liệu từ Collection hoặc nguồn bên ngoài:

Đăng ký Custom Function

import { useRegisterSpreadsheetFunction } from '@digiforce-nc/plugin-spreadsheet/client';

useRegisterSpreadsheetFunction('DG_LOOKUP', {
  description: 'Tìm kiếm dữ liệu từ Collection',
  handler: async (collectionName, field, value) => {
    // Logic tìm kiếm
    return result;
  },
});

Đăng ký Spreadsheet Plugin

import { useRegisterSpreadsheetPlugin } from '@digiforce-nc/plugin-spreadsheet/client';

useRegisterSpreadsheetPlugin('my-plugin', {
  name: 'My Custom Plugin',
  init: (spreadsheet) => {
    // Khởi tạo plugin cho spreadsheet instance
  },
});

Plugin dgRecords

Plugin tích hợp sẵn dgRecords cho phép kết nối spreadsheet với Collection — dữ liệu từ Collection được hiển thị và đồng bộ trong spreadsheet.

API Server

Action spreadsheet:getData

Trả về nội dung spreadsheet dưới dạng HTML:

GET /api/spreadsheet:getData/<spreadsheetId>

Response: HTML content (Content-Type: text/html; charset=UTF-8) — dùng cho embed/iframe.

Database Schema

Bảng spreadsheet

Field	Kiểu	Mô tả
id	uid (primary key)	ID duy nhất
name	string	Tên spreadsheet
description	text	Mô tả
content	jsonb	Nội dung bảng tính (cells, format, v.v.)
shareMode	string	Chế độ chia sẻ
shareToken	string	Token chia sẻ
permission	array	Danh sách quyền
version	integer	Phiên bản (cho optimistic locking)
createdBy / updatedBy	—	Người tạo / cập nhật

ACL và quyền truy cập

Snippet	Quyền	Mô tả
ui.spreadsheet	User	Toàn quyền trên spreadsheet
spreadsheet:getData	loggedIn	Đọc nội dung spreadsheet

Lưu ý quan trọng

• Thay đổi được lưu trực tiếp vào Database — không có nút Save riêng
• Nội dung bảng tính lưu trong field content (jsonb) — kích thước tối đa phụ thuộc cấu hình Database
• Route /spreadsheet/:spreadsheetId bỏ qua kiểm tra auth — nên kiểm soát chế độ chia sẻ cẩn thận
• Spreadsheet phù hợp cho dữ liệu vừa và nhỏ — với hàng chục ngàn dòng, nên dùng Table Block hoặc export CSV
• Plugin hỗ trợ Spreadsheet Block (nhúng trong page layout) và Spreadsheet Page (trang riêng biệt)
• Phân quyền theo Collection spreadsheet: user cần quyền edit mới chỉnh sửa được