Mở rộng Google Tài liệu

Google Apps Script cho phép bạn tạo và sửa đổi Google Tài liệu theo cách có lập trình, cũng như tuỳ chỉnh giao diện người dùng bằng các trình đơn, hộp thoại và thanh bên mới.

Thông tin cơ bản

Apps Script có thể tương tác với Google Tài liệu theo hai cách chính: mọi tập lệnh đều có thể tạo hoặc sửa đổi một tài liệu nếu người dùng của tập lệnh có các quyền thích hợp đối với tài liệu đó, đồng thời một tập lệnh cũng có thể được liên kết với một tài liệu, điều này mang lại cho tập lệnh các khả năng đặc biệt để thay đổi giao diện người dùng hoặc phản hồi khi tài liệu được mở. Để tạo một tập lệnh liên kết với vùng chứa trong Google Tài liệu, hãy nhấp vào Tiện ích bổ sung > Apps Script.

Trong cả hai trường hợp, bạn đều có thể dễ dàng tương tác với một tài liệu trên Google Tài liệu thông qua Document Service (Dịch vụ tài liệu) của Apps Script, như minh hoạ trong ví dụ sau.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

Tập lệnh ở trên sẽ tạo một tài liệu mới trong Google Drive của người dùng, sau đó truy xuất thẻ có mã nhận dạng t.0 (thẻ đầu tiên theo mặc định), chèn một đoạn văn bản có cùng nội dung với tên của tài liệu, tạo kiểu cho đoạn văn bản đó dưới dạng tiêu đề và thêm một bảng dựa trên các giá trị trong mảng hai chiều. Tập lệnh này cũng có thể dễ dàng thực hiện những thay đổi này đối với một tài liệu hiện có bằng cách thay thế lệnh gọi DocumentApp.create() bằng DocumentApp.openById() hoặc openByUrl(). Đối với tập lệnh được tạo trong một tài liệu (được liên kết với vùng chứa), hãy dùng DocumentApp.getActiveDocument() và Document.getActiveTab().

Cấu trúc của tài liệu

Theo quan điểm của Apps Script, một tài liệu Google Tài liệu được cấu trúc giống như một tài liệu HTML, tức là một tài liệu bao gồm một hoặc nhiều đối tượng Tab, mỗi đối tượng chứa các phần tử (chẳng hạn như Paragraph hoặc Table) thường chứa các phần tử khác. Hầu hết các tập lệnh sửa đổi tài liệu trên Google Tài liệu đều bắt đầu bằng lệnh gọi đến getTab() và asDocumentTab(), sau đó là getBody(), vì Body là một phần tử cốt lõi chứa tất cả các phần tử khác trong một thẻ, ngoại trừ HeaderSection, FooterSection và mọi Footnotes.

Tuy nhiên, có những quy tắc về loại phần tử có thể chứa các loại phần tử khác. Ngoài ra, Dịch vụ tài liệu trong Apps Script chỉ có thể chèn một số loại phần tử vào các phần tử khác. Cây dưới đây cho thấy những phần tử có thể được chứa trong một loại phần tử nhất định.

Bạn có thể chèn các phần tử được in đậm; bạn chỉ có thể thao tác các phần tử không được in đậm tại chỗ.

Thay thế văn bản

Apps Script thường được dùng để thay thế văn bản trong Google Tài liệu. Giả sử bạn có một bảng tính chứa đầy thông tin khách hàng và bạn muốn tạo một tài liệu Google được cá nhân hoá cho từng khách hàng. (Loại thao tác này thường được gọi là trộn thư.)

Có nhiều cách để thay thế văn bản, nhưng cách đơn giản nhất là phương thức replaceText() như trong ví dụ bên dưới. replaceText hỗ trợ hầu hết các tính năng biểu thức chính quy của JavaScript. Hàm đầu tiên bên dưới sẽ thêm một số dòng văn bản giữ chỗ vào Google Tài liệu; trong thực tế, bạn có nhiều khả năng sẽ tự nhập các phần giữ chỗ vào tài liệu. Hàm thứ hai thay thế các phần giữ chỗ bằng các thuộc tính được xác định trong đối tượng client.

Xin lưu ý rằng cả hai hàm này đều sử dụng các phương thức getActiveDocument() và getActiveTab(). Các phương thức này chỉ áp dụng cho những tập lệnh được tạo trong tài liệu Google Tài liệu; trong một tập lệnh độc lập, hãy sử dụng DocumentApp.create(), openById() hoặc openByUrl(), kết hợp với Document.getTab().

Thêm một số phần giữ chỗ

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

Thay thế phần giữ chỗ

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

Trình đơn và giao diện người dùng tuỳ chỉnh

Bạn có thể tuỳ chỉnh Google Tài liệu bằng cách thêm trình đơn, hộp thoại và thanh bên. Tuy nhiên, hãy lưu ý rằng một tập lệnh chỉ có thể tương tác với giao diện người dùng cho phiên bản hiện tại của một tài liệu đang mở và chỉ khi tập lệnh được liên kết với tài liệu đó.

Xem cách thêm trình đơn tuỳ chỉnh và hộp thoại vào Google Tài liệu. Để tìm hiểu thêm về cách tạo giao diện tuỳ chỉnh cho hộp thoại hoặc thanh bên, hãy xem hướng dẫn về Dịch vụ HTML. Nếu bạn dự định xuất bản giao diện tuỳ chỉnh dưới dạng một tiện ích bổ sung, hãy tuân theo hướng dẫn về kiểu chữ để đảm bảo tính nhất quán với kiểu chữ và bố cục của trình chỉnh sửa Google Tài liệu.

Tiện ích bổ sung cho Google Tài liệu

Tiện ích bổ sung chạy trong Google Tài liệu và có thể được cài đặt từ cửa hàng tiện ích bổ sung của Google Tài liệu. Nếu đã phát triển một tập lệnh cho Google Tài liệu và muốn chia sẻ tập lệnh đó với mọi người, thì Apps Script cho phép bạn xuất bản tập lệnh dưới dạng một tiện ích bổ sung để những người dùng khác có thể cài đặt tập lệnh đó từ cửa hàng tiện ích bổ sung.

Để xem cách tạo một tiện ích bổ sung cho Google Tài liệu, hãy xem hướng dẫn nhanh về cách tạo tiện ích bổ sung cho Tài liệu.

Điều kiện kích hoạt

Các tập lệnh được liên kết với một Tài liệu trên Google có thể sử dụng trình kích hoạt đơn giản để phản hồi sự kiện onOpen của tài liệu. Sự kiện này xảy ra bất cứ khi nào người dùng có quyền chỉnh sửa tài liệu mở tài liệu đó trong Google Tài liệu.

Để thiết lập điều kiện kích hoạt, bạn chỉ cần viết một hàm tên là onOpen(). Để xem ví dụ về điều kiện kích hoạt này, hãy xem phần Trình đơn tuỳ chỉnh trong Google Workspace. Mặc dù trình kích hoạt đơn giản rất hữu ích khi thêm trình đơn, nhưng trình kích hoạt này không thể sử dụng bất kỳ dịch vụ nào của Apps Script yêu cầu uỷ quyền.