Thao tác trên trình chỉnh sửa

Sử dụng các đối tượng Thao tác để đưa hành vi tương tác vào Tiện ích bổ sung của Google Workspace.

Đối tượng hành động xác định điều sẽ xảy ra khi người dùng tương tác với một tiện ích (ví dụ: một nút) trong giao diện người dùng tiện ích bổ sung.

Thêm hành động vào tiện ích

Để đính kèm một thao tác vào tiện ích, hãy sử dụng hàm trình xử lý tiện ích. Hàm này cũng xác định điều kiện kích hoạt thao tác đó. Khi được kích hoạt, hành động sẽ thực thi một hàm gọi lại được chỉ định. Hàm callback được truyền một đối tượng sự kiện chứa thông tin về các lượt tương tác phía máy khách của người dùng. Bạn phải triển khai hàm callback và yêu cầu hàm này trả về một đối tượng phản hồi cụ thể.

Ví dụ: Hiển thị thẻ mới khi nhấp vào một nút

Nếu bạn muốn thêm một nút vào tiện ích bổ sung sẽ tạo và hiển thị thẻ mới khi được nhấp vào, hãy làm theo các bước dưới đây:

1. Tạo một tiện ích nút.
2. Để thiết lập một hành động tạo thẻ, hãy thêm hàm trình xử lý tiện ích của nút setOnClickAction(action).
3. Tạo một hàm callback Apps Script để thực thi và chỉ định hàm này làm (action) trong hàm của trình xử lý tiện ích. Trong trường hợp này, hàm callback sẽ tạo thẻ bạn muốn và trả về một đối tượng ActionResponse. Đối tượng phản hồi yêu cầu tiện ích bổ sung hiển thị thẻ mà hàm callback đã tạo.

Ví dụ sau đây cho thấy cách tạo một tiện ích nút. Thao tác này thay mặt cho tiện ích bổ sung yêu cầu phạm vi drive.file của tệp hiện tại.

/**
 * Adds a section to the Card Builder that displays a "REQUEST PERMISSION" button.
 * When it's clicked, the callback triggers file scope permission flow. This is used in
 * the add-on when the home-page displays basic data.
 */
function addRequestFileScopeButtonToBuilder(cardBuilder) {
    var buttonSection = CardService.newCardSection();
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClickedInEditor");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setBackgroundColor("#4285f4")
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
      .setOnClickAction(buttonAction);

    buttonSection.addWidget(button);
    cardBuilder.addSection(buttonSection);
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the 
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClickedInEditor(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();

Tương tác truy cập vào tệp cho API REST

Tiện ích bổ sung của Google Workspace mở rộng Trình chỉnh sửa và sử dụng API REST có thể bao gồm một thao tác bổ sung dành cho tiện ích để yêu cầu quyền truy cập vào tệp. Thao tác này đòi hỏi hàm callback hành động liên kết để trả về một đối tượng phản hồi chuyên biệt:

Hành động đã cố gắng thực hiện	Hàm callback sẽ trả về
Yêu cầu quyền truy cập vào tệp cho tài liệu hiện tại	EditorFileScopeActionResponse

Để sử dụng đối tượng phản hồi và thao tác trong tiện ích này, bạn phải đáp ứng tất cả những điều sau:

• Tiện ích bổ sung sử dụng API REST.
• Tiện ích bổ sung sẽ hiển thị hộp thoại phạm vi tệp yêu cầu bằng phương thức CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
• Tiện ích bổ sung này bao gồm phạm vi trình chỉnh sửa https://www.googleapis.com/auth/drive.file và trình kích hoạt onFileScopeGranted trong tệp kê khai.

Yêu cầu quyền truy cập vào tệp đối với tài liệu hiện tại

Để yêu cầu quyền truy cập vào tệp cho tài liệu hiện tại, hãy làm theo các bước sau:

1. Tạo một thẻ trang chủ để kiểm tra xem tiện ích bổ sung có phạm vi drive.file hay không.
2. Đối với các trường hợp mà tiện ích bổ sung chưa được cấp phạm vi drive.file, hãy tạo một cách để yêu cầu người dùng cấp phạm vi drive.file cho tài liệu hiện tại.

Ví dụ: Truy cập vào tài liệu hiện tại trong Google Tài liệu

Ví dụ sau đây xây dựng một giao diện cho Google Tài liệu để hiển thị kích thước của tài liệu hiện tại. Nếu tiện ích bổ sung không có quyền uỷ quyền drive.file, tiện ích bổ sung sẽ hiển thị một nút để bắt đầu uỷ quyền phạm vi tệp.

/**
 * Build a simple card that checks selected items' quota usage. Checking
 * quota usage requires user-permissions, so this add-on provides a button
 * to request `drive.file` scope for items the add-on doesn't yet have
 * permission to access.
 *
 * @param e The event object passed containing information about the
 *   current document.
 * @return {Card}
 */
function onDocsHomepage(e) {
  return createAddOnView(e);
}

function onFileScopeGranted(e) {
  return createAddOnView(e);
}

/**
 * For the current document, display either its quota information or
 * a button that allows the user to provide permission to access that
 * file to retrieve its quota details.
 *
 * @param e The event containing information about the current document
 * @return {Card}
 */
function createAddOnView(e) {
  var docsEventObject = e['docs'];
  var builder =  CardService.newCardBuilder();

  var cardSection = CardService.newCardSection();
  if (docsEventObject['addonHasFileScopePermission']) {
    cardSection.setHeader(docsEventObject['title']);
    // This add-on uses the recommended, limited-permission `drive.file`
    // scope to get granular per-file access permissions.
    // See: https://developers.google.com/drive/api/v2/about-auth
    // If the add-on has access permission, read and display its quota.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "This file takes up: " + getQuotaBytesUsed(docsEventObject['id'])));
  } else {
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "The add-on needs permission to access this file's quota."));

    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClicked");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setOnClickAction(buttonAction);

    cardSection.addWidget(button);
  }
  return builder.addSection(cardSection).build();
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClicked(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}