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 phương thức lập trình, cũng như tuỳ chỉnh giao diện người dùng với 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 rộng rãi: bất kỳ tập lệnh nào cũng có thể tạo hoặc sửa đổi 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 và tập lệnh cũng có thể liên kết với một tài liệu, nhờ đó tập lệnh 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 tập lệnh ràng buộc vùng chứa từ trong Google Tài liệu, hãy nhấp vào Tiện ích > Apps Script.

Trong cả hai trường hợp, bạn có thể dễ dàng tương tác với một tệp Google Tài liệu thông qua 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 body = doc.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 đó chèn một đoạn có chứa văn bản giống với tên tài liệu, tạo kiểu cho đoạ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ể 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 đến DocumentApp.create() bằng DocumentApp.openById() hoặc openByUrl(). Đối với các tập lệnh được tạo trong một tài liệu (giới hạn trong vùng chứa), hãy sử dụng DocumentApp.getActiveDocument().

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

Từ góc độ của Apps Script, tệp Google Tài liệu có cấu trúc khá giống một tài liệu HTML, nghĩa là Google Tài liệu bao gồm 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 tệp Google Tài liệu đều bắt đầu bằng một lệnh gọi đến getBody(), vì Body là phần tử chính chứa mọi phần tử khác, ngoại trừ HeaderSection, FooterSection và Footnotes bất kỳ.

Tuy nhiên, sẽ có những quy tắc về việc loại phần tử nào có thể chứa các loại 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ử nhất định. Cây dưới đây cho thấy những phần tử có thể có trong một loại phần tử nhất định.

Bạn có thể chèn các phần tử hiển thị ở dạng in đậm; các phần tử không in đậm chỉ có thể được chỉnh sửa 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ệp Google 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ư.)

Có nhiều cách để thay thế văn bản, nhưng đơn giản nhất là phương thức replaceText() 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 dưới đây thêm một vài dòng văn bản phần giữ chỗ vào Google Tài liệu; trong thực tế, nhiều khả năng bạn có thể tự nhập phần giữ chỗ vào tài liệu. Hàm thứ hai thay thế 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 phương thức getActiveDocument(), phương thức này chỉ áp dụng cho các tập lệnh được tạo trong Google Tài liệu; trong tập lệnh độc lập, hãy sử dụng DocumentApp.create(), openById() hoặc openByUrl() thay thế.

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

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

Thay thế phần giữ chỗ

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .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 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 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 tài liệu đang mở và chỉ khi tập lệnh đó 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 sử dụng Dịch vụ HTML. Nếu bạn dự định phát hành giao diện tuỳ chỉnh trong một tiện ích bổ sung, hãy làm theo hướng dẫn về kiểu để đảm bảo tính nhất quán với kiểu 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 Google Tài liệu. Nếu bạn đã 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 publish tập lệnh của mình dưới dạng 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.

Để biết cách tạo tiện ích bổ sung cho Google Tài liệu, hãy xem phầ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

Những tập lệnh liên kết với một Google Tài liệu có thể sử dụng một điều kiện kích hoạt đơn giản để phản hồi onOpen sự kiện của tài liệu. Việc 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 có tên là onOpen(). Để xem ví dụ về điều kiện kích hoạt này, hãy xem 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 cho việc 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ụ Apps Script nào yêu cầu uỷ quyền.