Trang chủ

Trang chủ là một tính năng mới của tiện ích bổ sung Google Workspace, cho phép bạn xác định một hoặc nhiều thẻ không theo ngữ cảnh. Thẻ không theo ngữ cảnh được dùng để hiển thị giao diện người dùng khi người dùng không ở trong một ngữ cảnh cụ thể, chẳng hạn như khi người dùng đang xem hộp thư đến của họ trên Gmail nhưng chưa mở thư hoặc thư nháp.

Trang chủ cho phép bạn hiển thị nội dung không theo ngữ cảnh, giống như các ứng dụng của Google trong bảng điều khiển bên truy cập nhanh (Keep, Lịch và Tasks). Trang chủ cũng có thể cung cấp một điểm xuất phát ban đầu khi người dùng mở tiện ích bổ sung của bạn lần đầu tiên và rất hữu ích khi hướng dẫn người dùng mới cách tương tác với tiện ích bổ sung của bạn.

Bạn có thể xác định trang chủ cho tiện ích bổ sung bằng cách chỉ định trang chủ đó trong tệp kê khai dự án và triển khai một hoặc nhiều hàm homepageTrigger (xem Cấu hình trang chủ).

Bạn có thể có nhiều trang chủ, mỗi trang chủ cho một ứng dụng lưu trữ mà tiện ích bổ sung của bạn mở rộng. Bạn cũng có thể quyết định xác định một trang chủ mặc định chung được sử dụng trong các máy chủ lưu trữ mà bạn chưa chỉ định trang chủ tuỳ chỉnh.

Trang chủ của tiện ích bổ sung sẽ xuất hiện khi đáp ứng một trong các điều kiện sau:

  • Khi tiện ích bổ sung được mở lần đầu trong máy chủ lưu trữ (sau khi được uỷ quyền).
  • Khi người dùng chuyển từ ngữ cảnh theo bối cảnh sang ngữ cảnh không theo bối cảnh trong khi tiện ích bổ sung đang mở. Ví dụ: từ việc chỉnh sửa một sự kiện trên Lịch sang Lịch chính.
  • Khi người dùng nhấp vào nút quay lại đủ số lần để đẩy mọi thẻ khác ra khỏi ngăn xếp nội bộ.
  • Khi một lượt tương tác với giao diện người dùng trong thẻ không theo ngữ cảnh dẫn đến lệnh gọi Navigation.popToRoot().

Bạn không bắt buộc phải thiết kế trang chủ nhưng nên thiết kế; nếu bạn không xác định trang chủ nào, thì một thẻ chung chứa tên tiện ích bổ sung sẽ được sử dụng mỗi khi người dùng chuyển đến trang chủ.

Cấu hình trang chủ

Tiện ích bổ sung của Google Workspace sử dụng trường addOns.common.homepageTrigger để định cấu hình nội dung trang chủ mặc định (không theo ngữ cảnh) của tiện ích bổ sung cho tất cả ứng dụng lưu trữ trong tệp kê khai của tiện ích bổ sung:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

  • runFunction: Tên của hàm Apps Script mà khung tiện ích bổ sung của Google Workspace gọi để hiển thị thẻ tiện ích bổ sung trên trang chủ. Đây là hàm kích hoạt trang chủ. Hàm này phải tạo và trả về một mảng các đối tượng Card tạo nên giao diện người dùng của trang chủ. Nếu trả về nhiều thẻ, thì ứng dụng lưu trữ sẽ hiển thị tiêu đề thẻ trong danh sách mà người dùng có thể chọn (xem phần Trả về nhiều thẻ).

  • enabled: Liệu có nên bật thẻ trang chủ cho phạm vi này hay không. Trường này không bắt buộc và mặc định là true. Việc đặt giá trị này thành false sẽ khiến các thẻ trang chủ bị tắt đối với tất cả máy chủ lưu trữ (trừ khi được ghi đè cho máy chủ lưu trữ đó; xem bên dưới).

Ngoài cấu hình chung, còn có các chế độ ghi đè có cấu trúc giống hệt nhau cho mỗi máy chủ lưu trữ trong cấu hình của mỗi ứng dụng lưu trữ, tại addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger, v.v.:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

Xin lưu ý rằng nội dung này tương đương với đoạn trích tệp kê khai sau:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

Không có phần homepageTrigger nào là bắt buộc. Tuy nhiên, giao diện người dùng hiển thị cho một tiện ích bổ sung trong bất kỳ sản phẩm lưu trữ nào phụ thuộc vào sự hiện diện của trường tệp kê khai tương ứng và liệu có homepageTrigger được liên kết hay không. Ví dụ sau đây cho biết các hàm điều kiện kích hoạt tiện ích bổ sung nào được thực thi (nếu có) để tạo giao diện người dùng trang chủ cho các cấu hình tệp kê khai khác nhau:

Luồng trang chủ

Đối tượng sự kiện trên trang chủ

Khi được gọi, hàm điều kiện kích hoạt trang chủ (runFunction) được mô tả ở trên sẽ được truyền một đối tượng sự kiện chứa dữ liệu từ ngữ cảnh gọi.

Đối tượng sự kiện trên trang chủ không bao gồm tiện ích hoặc thông tin theo ngữ cảnh; thông tin được truyền chỉ giới hạn ở các trường đối tượng sự kiện phổ biến sau:

Hãy xem phần Đối tượng sự kiện để biết thêm chi tiết.

Các thẻ khác không theo ngữ cảnh

Giao diện người dùng của tiện ích bổ sung có thể chứa các thẻ không theo ngữ cảnh bổ sung không phải là trang chủ. Ví dụ: trang chủ của bạn có thể có một nút mở thẻ "Cài đặt", trong đó người dùng có thể điều chỉnh chế độ cài đặt tiện ích bổ sung (trong hầu hết các trường hợp, các chế độ cài đặt này sẽ độc lập với ngữ cảnh và do đó không theo ngữ cảnh).

Thẻ không theo ngữ cảnh được tạo giống như mọi thẻ khác; điểm khác biệt duy nhất là hành động hoặc sự kiện nào tạo ra và hiển thị thẻ. Hãy xem phần Phương thức điều hướng để biết thông tin chi tiết về cách tạo hiệu ứng chuyển đổi giữa các thẻ.