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

Google Apps Script cho phép bạn tạo và sửa đổi Tài liệu theo phương thứ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 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 tập lệnh có quyền thích hợp đối với tài liệu đó. Ngoài ra, một tập lệnh cũng có thể được liên kết với một tài liệu, nhờ đó tập lệnh có 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 từ bên trong Tài liệu, hãy nhấp vào Tiện ích mở rộng > Apps Script.

Trong cả hai trường hợp, bạn có thể tương tác với một tài liệu Tài liệu bằng cách sử dụng 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ước đó 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 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ột mảng hai chiều. Tập lệnh cũng có thể 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 các tập lệnh được tạo bên trong một tài liệu (liên kết với vùng chứa), hãy sử 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 Tài liệu có cấu trúc tương tự 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 Tab đối tượng, mỗi đối tượng chứa các phần tử (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 một tài liệu Tài liệu đều bắt đầu bằng một 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ó các quy tắc về loại phần tử nào có thể chứa các loại phần tử khác. Hơn nữa, Dịch vụ tài liệu trong Apps Script chỉ có thể chèn một số loại phần tử nhất định vào các phần tử khác. Cây sau đây cho biết những phần tử nào có thể được chứa bởi một loại phần tử nhất định.

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

Thay thế văn bản

Apps Script thường được dùng để thay thế văn bản trong 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 Tài liệu đượ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à hợp nhất thư.)

Bạn có thể thay thế văn bản bằng phương thức replaceText, phương thức này hỗ trợ hầu hết các tính năng biểu thức chính quy của JavaScript. Trong ví dụ sau, hàm đầu tiên thêm văn bản giữ chỗ vào tài liệu và hàm thứ hai thay thế văn bản đó bằng các thuộc tính từ đối tượng client.

Cả hai hàm này đều sử dụng các phương thức getActiveDocument và getActiveTab, chỉ áp dụng cho các tập lệnh được tạo bên trong một tài liệu 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, thay thế.

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 tuỳ chỉnh và giao diện người dùng

Bạn có thể tuỳ chỉnh Tài liệu bằng cách thêm trình đơn tuỳ chỉnh, hộp thoại và thanh bên. Xin 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 của tài liệu mà tập lệnh đó được liên kết.

Để tìm hiểu thêm về cách tạo giao diện tuỳ chỉnh bằng HTML và CSS, 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 của mình dưới dạng một tiện ích bổ sung, hãy làm theo hướng dẫn về kiểu để đảm bảo giao diện nhất quán với trình chỉnh sửa Tài liệu.

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

Tiện ích bổ sung chạy bên trong Tài liệu và có thể được cài đặt từ cửa hàng tiện ích bổ sung của Tài liệu. Nếu bạn đã phát triển một tập lệnh cho 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 để 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.

Để tạo một tiện ích bổ sung cho Tài liệu, hãy xem hướng dẫn bắt đầu 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 điều kiện 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 một người dùng có quyền chỉnh sửa tài liệu mở tài liệu đó trong Tài liệu.

Để thiết lập điều kiện kích hoạt, hãy viết một hàm có tên là onOpen. Để xem ví dụ về điều kiện kích hoạt này, hãy xem bài viết Trình đơn tuỳ chỉnh trong Google Workspace. Mặc dù điều kiện kích hoạt này hữu ích cho việc thêm trình đơn, nhưng 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.