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

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

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

Thêm một thao tác vào tiện ích

Để đính kèm một thao tác vào một tiện ích, hãy sử dụng hàm trình xử lý tiện ích, mã này cũng xác định điều kiện kích hoạt hành động đó. Khi được kích hoạt, Thao tác này sẽ thực thi hàm callback đã chỉ định. Hàm callback được truyền một đối tượng sự kiện có 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 để tạo và hiển thị thẻ mới khi nhấp vào, hãy làm theo các bước sau:

  1. Tạo một tiện ích nút.
  2. Để thiết lập một hành động khi tạo thẻ, hãy thêm hàm nút trình xử lý tiện ích setOnClickAction(action).
  3. Tạo một hàm callback Apps Script để thực thi và chỉ định hàm đó làm (action) trong hàm xử lý tiện ích. Trong trường hợp này, hàm callback sẽ tạo thẻ mà bạn muốn và trả về đố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 minh hoạ cách tạo tiện ích nút. Hành động yêu cầu phạm vi drive.file cho tệp hiện tại thay mặt cho tiện ích bổ sung.

/**
 * 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();

Hoạt động tương tác truy cập vào tệp đối với API REST

Các 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 thao tác khác vào tiện ích để yêu cầu quyền truy cập vào tệp. Thao tác này yêu cầu 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:

Đã cố gắng thực hiện thao tác Hàm gọi lại cần trả về
Yêu cầu quyền truy cập vào tệp đối với current_document EditorFileScopeActionResponse

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

  • Tiện ích bổ sung này sử dụng API REST.
  • Tiện ích bổ sung này 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 https://www.googleapis.com/auth/drive.file phạm vi trình chỉnh sửa và Điều kiện 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 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 trường hợp tiện ích bổ sung chưa được cấp phạm vi drive.file, hãy tạo để 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ụ: Lấy quyền truy cập hiện tại vào tài liệu 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ó lệnh uỷ quyền drive.file, hệ thống 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();
}