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

Nhờ các tiện ích bổ sung của Google Workspace, bạn có thể cung cấp giao diện tuỳ chỉnh trong phần Trình chỉnh sửa, bao gồm 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 phù hợp, tự động hoá công việc và kết nối hệ thống của bên thứ ba với Người chỉnh sửa.

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

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

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 chứa yếu tố 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 trong đó, các bản dựng tiện ích bổ sung và trả về một thẻ trang chủ dành riêng cho Người 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ở trong đó, một thẻ trang chủ chung sẽ được hiển thị thay thế.

  • Giao diện API REST: Nếu tiện ích bổ sung sử dụng REST API, bạn có thể thêm các điều kiện kích hoạt yêu cầu quyền truy cập theo từng 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ấp quyền, một trình kích hoạt khác có tên EDITOR_NAME.onFileScopeGrantedTrigger thực thi và hiển thị 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 dịch vụ của bên thứ ba, bạn có thể tạo thẻ có thể xem trước từ các URL của dịch vụ bạn sử dụng.

Xây dựng giao diện cho Tiện ích bổ sung dành cho trình chỉnh sửa

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

  1. Thêm thông tin thích hợp addOns.common! addOns.docs! addOns.sheets! và addOns.slides vào dự án tập lệnh tiện ích bổ sung tệp kê khai.
  2. Thêm mọi phạm vi Editor bắt buộc vào tệp kê khai dự án tập lệnh của bạn.
  3. Nếu bạn cung cấp trang chủ dành riêng cho Trình chỉnh sửa, triển khai EDITOR_NAME.homepageTrigger để tạo giao diện. Nếu không, hãy sử dụng common.homepageTrigger để tạo một 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.fileEDITOR_NAME.onFileScopeGrantedTrigger để hiển thị một giao diện dành riêng cho tệp đang mở. Để biết thêm 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ụ bên thứ ba, hãy triển khai quy trình uỷ quyền phạm vi https://www.googleapis.com/auth/workspace.linkpreviewlinkPreviewTriggers . Để biết thêm thông tin, hãy xem Giao diện xem trước đường liên kết.
  6. Triển khai các hàm callback được liên kết để phản hồi các lệnh gọi lại của người dùng Lượt tương tác trên 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 hàm kích hoạt trang chủ trong dự án tập lệnh của tiện ích bổ sung tạo và trả về một Card duy nhất 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 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 cấu trúc của trang chủ.

Bạn có thể trình bày một trang chủ chung hoặc một trang chủ dành riêng cho Trình chỉnh sửa 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 bao gồm Các trường trong trình chỉnh sửa, chẳng hạn như addOns.docs, addOns.sheets! hoặc addOns.slides, trong tệp kê khai của tiện ích bổ sung.

Ví dụ sau đây cho thấy phần addons của một tiện ích bổ sung của Google Workspace tệp kê khai. 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ị các 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

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

Ví dụ sau đây minh hoạ phần addons của tệp kê khai tiện ích bổ sung của 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. Thẻ này cho thấy các lưu ý chung trang chủ trong Tài liệu và Trang trình bày cũng như một trang chủ duy nhất trong Trang tính. Lệnh gọi lại hàm 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 API REST, chẳng hạn như API Google Trang tính, bạn có thể dùng hàm onFileScopeGrantedTrigger để cho thấy giao diện mới dành riêng cho tệp được mở trong ứng dụng lưu trữ Editor.

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

Khi người dùng cấp phạm vi drive.file, EDITOR_NAME.onFileScopeGrantedTrigger.runFunction hoả hoạn. Khi trình kích hoạt kích hoạt, nó sẽ thực thi hàm kích hoạt theo ngữ cảnh được chỉ định bởi trường EDITOR_NAME.onFileScopeGrantedTrigger.runFunction 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ữ Editor mà bạn chọn ví dụ: sheets.onFileScopeGrantedTrigger.

  1. Bao gồm EDITOR_NAME.onFileScopeGrantedTrigger tại mục "Người chỉnh sửa" tương ứng trong 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 trình kích hoạt vào phần "sheets".
  2. Triển khai hàm có tên trong EDITOR_NAME.onFileScopeGrantedTrigger . Hàm này chấp nhận một đối tượng sự kiện làm đối số và phải trả về một đối số duy nhất Card hoặc một mảng các đối tượng Card.
  3. Giống như với bất kỳ thẻ nào, bạn phải triển khai các hàm callback dùng để cung cấp tiện ích tương tác cho giao diện. Ví dụ: nếu bạn đưa vào một nút trong giao diện, nó sẽ có một Action (Hành động) đính kèm và một hàm callback được triển khai để chạy khi nút này được nhấp vào.

Ví dụ sau đây minh hoạ phần addons của tệp kê khai tiện ích bổ sung của Google Workspace. Tiện ích bổ sung này sử dụng API REST, vì vậy, onFileScopeGrantedTrigger được đưa vào cho Google Trang tính. Khi người dùng cấp phạm vi drive.file, hàm callback onFileScopeGrantedSheets xây dựng 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 tính năng xem trước đường liên kết cho dịch vụ bên thứ ba, bạn phải định cấu hình đường liên kết bản xem trước trong tệp kê khai của tiện ích bổ sung và tạo một hàm trả về bản xem trước . Đối với các dịch vụ yêu cầu sự cho phép của người dùng, hàm của bạn cũng phải gọi quy trình 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 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ẻ tiện ích bổ sung hoặc kiểm soát hoạt động của tiện ích bổ sung.

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

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

Nếu tiện ích bổ sung không được uỷ quyền phạm vi drive.file đối với người dùng hiện tại hoặc tài liệu, đối tượng sự kiện chỉ chứa docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission hoặc Trường slides.addonHasFileScopePermission. Nếu tiện ích bổ sung có uỷ quyền, đố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. Ở đây, tiện ích bổ sung có Ủy 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"
          },
          ...
        }