Xây dựng giao diện Google Editor

Với tiện ích bổ sung của Google Workspace, bạn có thể cung cấp giao diện tuỳ chỉnh trong Trình chỉnh sửa, bao gồm cả Google Tài liệu, Trang tính và Trang trình bày. Điều này cho phép bạn cung cấp cho người dùng thông tin liên quan, tự động hoá các tác vụ và kết nối các hệ thống của bên thứ ba với Trình chỉnh sửa.

Truy cập vào giao diện người dùng của tiện ích bổ sung

Bạn có thể mở một tiện ích bổ sung của Google Workspace trong Trình chỉnh sửa nếu biểu tượng của tiện ích đó xuất hiện trong bảng điều khiển truy cập nhanh của Google Workspace ở bên phải giao diện người dùng của Tài liệu, Trang tính và Trang trình bày.

Tiện ích bổ sung của Google Workspace có thể hiển thị các giao diện sau:

  • Giao diện trang chủ: Nếu tệp kê khai của tiện ích bổ sung bao gồm trình kích hoạt EDITOR_NAME.homepageTrigger cho Trình chỉnh sửa mà người dùng mở tiện ích bổ sung, thì tiện ích bổ sung sẽ tạo và trả về một thẻ trang chủ dành riêng cho Trình chỉnh sửa đó. Nếu tệp kê khai của tiện ích bổ sung không bao gồm EDITOR_NAME.homepageTrigger cho Trình chỉnh sửa mà người dùng mở tệp kê khai đó, thì một thẻ trang chủ chung sẽ hiển thị.

  • Giao diện API REST: Nếu tiện ích bổ sung sử dụng API REST, bạn có thể đưa vào các trình kích hoạt yêu cầu quyền truy cập theo tệp vào một tài liệu bằng cách sử dụng phạm vi drive.file. Sau khi được cấp, một trình kích hoạt khác có tên là EDITOR_NAME.onFileScopeGrantedTrigger sẽ thực thi và hiển thị một giao diện dành riêng cho tệp đó.

  • Giao diện xem trước đường liên kết: Nếu tiện ích bổ sung của bạn tích hợp với một dịch vụ bên thứ ba, bạn có thể tạo các thẻ xem trước nội dung từ URL của dịch vụ.

Xây dựng giao diện cho tiện ích bổ sung của Trình chỉnh sửa

Tạo giao diện tiện ích bổ sung cho Trình chỉnh sửa bằng cách làm theo các bước sau:

  1. Thêm các trường addOns.common, addOns.docs, addOns.sheets và addOns.slides thích hợp vào tệp kê khai của dự án tập lệnh bổ sung.
  2. Thêm mọi phạm vi Trình chỉnh sửa bắt buộc vào tệp kê khai dự án tập lệnh.
  3. Nếu bạn đang cung cấp trang chủ dành riêng cho Người chỉnh sửa, hãy triển khai hàm EDITOR_NAME.homepageTrigger để tạo giao diện. Nếu không, hãy sử dụng giao diện common.homepageTrigger để tạo trang chủ chung cho các ứng dụng lưu trữ.
  4. Nếu bạn sử dụng API REST, hãy triển khai quy trình uỷ quyền phạm vi drive.file và hàm kích hoạt EDITOR_NAME.onFileScopeGrantedTrigger để hiển thị giao diện dành riêng cho tệp đang mở. Để biết thêm thông tin, hãy xem Giao diện API REST.
  5. Nếu bạn đang định cấu hình bản xem trước đường liên kết từ một dịch vụ của bên thứ ba, hãy triển khai quy trình uỷ quyền phạm vi https://www.googleapis.com/auth/workspace.linkpreview và hàm linkPreviewTriggers. Để biết thêm thông tin, hãy xem phần Giao diện xem trước đường liên kết.
  6. Triển khai các hàm gọi lại liên kết cần thiết để phản hồi các hoạt động tương tác của người dùng với giao diện người dùng, chẳng hạn như lượt nhấp vào nút.

Trang chủ của trình chỉnh sửa

Bạn phải cung cấp một hàm kích hoạt trang chủ trong dự án tập lệnh của tiện ích bổ sung. Hàm này sẽ tạo và trả về một Card hoặc một mảng các đối tượng Card tạo nên trang chủ của tiện ích bổ sung.

Hàm điều kiện kích hoạt trang chủ được truyền một đối tượng sự kiện dưới dạng tham số chứa thông tin như nền tảng của ứng dụng. Bạn có thể sử dụng dữ liệu đối tượng sự kiện để điều chỉnh việc xây dựng trang chủ.

Bạn có thể hiển thị một trang chủ chung hoặc một trang chủ dành riêng cho Trình chỉnh sửa mà người dùng mở tiện ích bổ sung của bạn.

Hiển thị trang chủ chung

Để hiển thị trang chủ chung của tiện ích bổ sung trong Trình chỉnh sửa, hãy thêm các trường Trình chỉnh sửa thích hợp, chẳng hạn như addOns.docs, addOns.sheets hoặc addOns.slides vào tệp kê khai của tiện ích bổ sung.

Ví dụ sau đây cho thấy phần addons của tệp kê khai tiện ích bổ sung Google Workspace. Tiện ích bổ sung này mở rộng Tài liệu, Trang tính và Trang trình bày, đồng thời hiển thị trang chủ chung trong mỗi ứng dụng lưu trữ.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

Hiển thị trang chủ dành riêng cho Người chỉnh sửa

Để hiển thị trang chủ dành riêng cho một Trình chỉnh sửa, hãy thêm EDITOR_NAME.homepageTrigger vào tệp kê khai tiện ích bổ sung.

Ví dụ sau đây cho thấy phần addons của tệp kê khai tiện ích bổ sung Google Workspace. Tiện ích bổ sung này được bật cho Tài liệu, Trang tính và Trang trình bày. Chế độ này hiển thị trang chủ chung trong Tài liệu và Trang trình bày, cũng như một trang chủ riêng trong Trang tính. Hàm gọi lại onSheetsHomepage tạo thẻ trang chủ dành riêng cho Trang tính.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

Giao diện API REST

Nếu tiện ích bổ sung của bạn sử dụng các API REST, chẳng hạn như API Google Trang tính, bạn có thể sử dụng hàm onFileScopeGrantedTrigger để hiển thị một giao diện mới dành riêng cho tệp đang mở trong ứng dụng lưu trữ Trình chỉnh sửa.

Bạn phải đưa quy trình uỷ quyền phạm vi drive.file vào để sử dụng hàm onFileScopeGrantedTrigger. Để tìm hiểu cách yêu cầu phạm vi drive.file, hãy xem phần Yêu cầu quyền truy cập vào tệp cho tài liệu hiện tại.

Khi người dùng cấp phạm vi drive.file, EDITOR_NAME.onFileScopeGrantedTrigger.runFunction sẽ kích hoạt. Khi kích hoạt, trình kích hoạt sẽ thực thi hàm kích hoạt theo ngữ cảnh do trường EDITOR_NAME.onFileScopeGrantedTrigger.runFunction chỉ định trong tệp kê khai tiện ích bổ sung.

Để tạo giao diện API REST cho một trong các Trình chỉnh sửa, hãy làm theo các bước dưới đây. Thay thế EDITOR_NAME bằng ứng dụng lưu trữ Trình chỉnh sửa mà bạn chọn sử dụng, ví dụ: sheets.onFileScopeGrantedTrigger.

  1. Thêm EDITOR_NAME.onFileScopeGrantedTrigger vào phần Trình chỉnh sửa thích hợp của tệp kê khai. Ví dụ: nếu bạn muốn tạo giao diện này trong Google Trang tính, hãy thêm điều kiện kích hoạt vào phần "sheets".
  2. Triển khai hàm có tên trong phần EDITOR_NAME.onFileScopeGrantedTrigger. Hàm này chấp nhận đối tượng sự kiện làm đối số và phải trả về một đối tượng Card hoặc một mảng đối tượng Card.
  3. Giống như mọi thẻ khác, bạn phải triển khai các hàm gọi lại dùng để cung cấp tính tương tác của tiện ích cho giao diện. Ví dụ: nếu bạn thêm một nút vào giao diện, thì nút đó phải có một Thao tác đính kèm và một hàm gọi lại đã triển khai sẽ chạy khi người dùng nhấp vào nút đó.

Ví dụ sau đây cho thấy phần addons của tệp kê khai tiện ích bổ sung Google Workspace. Tiện ích bổ sung này sử dụng các API REST, vì vậy, onFileScopeGrantedTrigger được đưa vào Google Trang tính. Khi người dùng cấp phạm vi drive.file, hàm gọi lại onFileScopeGrantedSheets sẽ tạo một giao diện dành riêng cho tệp.

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

Để bật bản xem trước đường liên kết cho một dịch vụ bên thứ ba, bạn phải định cấu hình bản xem trước đường liên kết trong tệp kê khai của tiện ích bổ sung và tạo một hàm trả về thẻ xem trước. Đối với các dịch vụ yêu cầu người dùng uỷ quyền, hàm của bạn cũng phải gọi luồng uỷ quyền.

Để biết các bước bật tính năng xem trước đường liên kết, hãy xem bài viết Xem trước đường liên kết bằng khối thông minh.

Đối tượng sự kiện

Một đối tượng sự kiện được tạo và truyền đến các hàm kích hoạt, chẳng hạn như EDITOR_NAME.homepageTrigger hoặc EDITOR_NAME.onFileScopeGrantedTrigger. Hàm kích hoạt sử dụng thông tin trong đối tượng sự kiện để xác định cách tạo thẻ bổ sung hoặc kiểm soát hành vi của thẻ bổ sung.

Cấu trúc đầy đủ của đối tượng sự kiện được mô tả trong phần Đối tượng sự kiện.

Khi một Trình chỉnh sửa là ứng dụng lưu trữ đang hoạt động của tiện ích bổ sung, các đối tượng sự kiện sẽ bao gồm các trường đối tượng sự kiện Tài liệu, Trang tính hoặc Trang trình bày chứa thông tin về ứng dụng khách.

Nếu tiện ích bổ sung không có quyền truy cập phạm vi drive.file cho người dùng hoặc tài liệu hiện tại, thì đối tượng sự kiện chỉ chứa trường docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission hoặc slides.addonHasFileScopePermission. Nếu tiện ích bổ sung có quyền, thì đối tượng sự kiện sẽ chứa tất cả các trường đối tượng sự kiện của Trình chỉnh sửa.

Ví dụ sau đây cho thấy một đối tượng sự kiện Trình chỉnh sửa được truyền đến hàm sheets.onFileScopeGrantedTrigger. Tại đây, tiện ích bổ sung có quyền uỷ quyền phạm vi drive.file cho tài liệu hiện tại:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }