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 chương trình, cũng như tuỳ chỉnh giao diện người dùng với các trình đơn, hộp thoại và thanh bên.

Khái niệm cơ bản

Apps Script có thể tương tác với Google Tài liệu theo hai cách phổ biến: 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 của tập lệnh có quyền thích hợp đối với tài liệu và một tập lệnh cũng có thể ràng buộc vào một tài liệu 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, nhấp vào Tiện ích > Apps Script.

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

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 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 chứa văn bản giống với tên tài liệu, hãy định kiểu đoạn văn bản đó thành một tiêu đề và nối bảng dựa trên các giá trị trong mảng hai chiều. Chiến lược phát hành đĩa đơn 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 đang thay thế lệnh gọi đến DocumentApp.create() với 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() và Document.getActiveTab().

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

Từ góc độ của Apps Script, một tài liệu trong Google Tài liệu được cấu trúc giống như tài liệu HTML—tức là tài liệu bao gồm một hoặc nhiều Đối tượng Tab, mỗi đối tượng chứa (như Paragraph hoặc Table) thường chứa các thuộc tính khác phần tử. 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 một lệnh gọi đến getTab() và asDocumentTab() tiếp theo 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ừ phần tử HeaderSection, FooterSection và bất kỳ Footnotes.

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 vào các phần tử khác. Cây bên dưới cho biết các phần tử 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ử in đậm; các phần tử không in đậm chỉ có thể được bị thao túng 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 có đầy đủ thông tin khách hàng và bạn muốn tạo một bảng tính Google Tài liệu cho từng khách hàng. (Loại thao tác này thường được gọi là gửi thư merge.)

Có nhiều cách để thay thế văn bản, nhưng đơn giản nhất là Phương thức replaceText() như trong ví dụ bên dưới. replaceText hỗ trợ nhiều nhất về tính năng biểu thức chính quy của JavaScript. Hàm đầu tiên bên dưới thêm một vài dòng văn bản giữ chỗ vào một tệp Google Tài liệu; trong thế giới thực, bạn có nhiều khả năng sẽ tự nhập phần giữ chỗ vào tài liệu. Chiến lược phát hành đĩa đơn 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.

Lưu ý rằng cả hai hàm này đều sử dụng lớp getActiveDocument() và getActiveTab() các phương pháp chỉ áp dụng cho các tập lệnh được tạo bên trong một tài liệu trên 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(), 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 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 bản sao hiện tại của tài liệu đang mở và chỉ khi tập lệnh là ràng buộc vào tài liệu.

Xem cách thêm trình đơn tùy chỉnh và hộp thoại vào Google Tài liệu của mình. Để 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 phần của tiện ích bổ sung, hãy làm theo hướng dẫn 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ẻ mã này với mọi người, Apps Script giúp bạn xuất bản tập lệnh của bạn dưới dạng để người dùng khác có thể cài đặt tiện ích bổ sung đó 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 bắt đầu nhanh việc 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 bị ràng buộc với một tệp 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 đối với onOpen sự kiện của tài liệu 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(). Ví dụ của điều kiện kích hoạt nà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 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ỳ Ứng dụng nào Dịch vụ tập lệnh yêu cầu uỷ quyền.