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 bối cảnh. Thẻ không theo bối 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 bối cảnh cụ thể, chẳng hạn như khi người dùng đang xem hộp thư đến 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 bối cảnh, giống như các ứng dụng 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ể là nơi bắt đầu 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 phần Cấu hình trang chủ).

Bạn có thể có nhiều trang chủ, mỗi trang dành 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 duy nhất được dùng trong những 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 một trong các điều kiện sau được đáp ứng:

  • Khi tiện ích bổ sung được mở lần đầu tiên trong ứng dụng lưu trữ (sau khi được uỷ quyền).
  • Khi người dùng chuyển từ một ngữ cảnh theo bối cảnh sang một 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 để kéo mọi thẻ khác ra khỏi ngăn xếp nội bộ.
  • Khi một hoạt động tương tác trên giao diện người dùng trong thẻ không theo ngữ cảnh dẫn đến một 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 làm; 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 của bạn sẽ được dùng bất cứ khi nào 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 tiện ích bổ sung mặc định trên trang chủ (không theo bối cảnh) cho tất cả các ứng dụng lưu trữ trong tệp kê khai 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 Google Workspace gọi để kết xuất các thẻ tiện ích bổ sung trên trang chủ. Hàm nà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 trang chủ. Nếu có nhiều thẻ được trả về, ứng dụng lưu trữ sẽ hiển thị tiêu đề thẻ trong một danh sách mà người dùng có thể chọn (xem phần Trả về nhiều thẻ).

  • enabled: 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 sẽ được đặt là true. Nếu bạn đặt giá trị này thành false, các thẻ trên trang chủ sẽ bị vô hiệu hoá cho tất cả các máy chủ lưu trữ (trừ phi bị 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 đè trên mỗi máy chủ có cấu trúc giống hệt nhau trong cấu hình của từng ứ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 điều này tương đương với đoạn trích sau đây trong tệp kê khai:

    {
      ...
      "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": { /* ... */ },
        ...
      }
    }

Bạn không bắt buộc phải điền vào bất kỳ phần nào trong số homepageTrigger. Tuy nhiên, giao diện người dùng xuất hiện cho một tiện ích bổ sung trong bất kỳ sản phẩm lưu trữ nào sẽ 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 những hàm 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 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.

Các đối tượng sự kiện trên trang chủ không bao gồm thông tin về tiện ích hoặc thông tin theo bối cảnh; thông tin được truyền chỉ giới hạn ở các trường đối tượng sự kiện chung sau đây:

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

Các thẻ không theo bối cảnh khác

Giao diện người dùng của tiện ích bổ sung có thể chứa các thẻ bổ sung không theo bối cảnh và 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" để người dùng có thể điều chỉnh chế độ cài đặt của tiện ích bổ sung (trong hầu hết các trường hợp, những chế độ cài đặt như vậy sẽ độc lập với bối cảnh và do đó không theo bối cảnh).

Thẻ không theo bối cảnh được tạo 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 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ẻ.