Trang chủ

Trang chủ là một tính năng Tiện ích bổ sung mới của Google Workspace, cung cấp khả năng 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 ở bên ngoài một ngữ cảnh cụ thể, chẳng hạn như khi người dùng đang xem hộp thư đến trong 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ể là nơi 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. Trang chủ cũng hữu ích trong việc 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 của mình 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ỗi ứ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 dùng trong các máy chủ mà bạn chưa chỉ định trang chủ tuỳ chỉnh.

Trang chủ tiện ích bổ sung của bạn hiển thị 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 trong máy chủ (sau khi được uỷ quyền).
  • Khi người dùng chuyển từ ngữ cảnh theo ngữ cảnh sang ngữ cảnh không theo ngữ 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 để bật 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 lệnh gọi Navigation.popToRoot().

Bạn không bắt buộc phải thiết kế trang chủ nhưng rất nên thiết kế trang chủ. Nếu bạn không xác định bất kỳ tên nào, một thẻ chung chứa tên tiện ích bổ sung sẽ được sử 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 (không theo ngữ cảnh) cho tất cả cá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 hàm Apps Script mà khung Tiện ích bổ sung của Google Workspace gọi để hiển thị các thẻ tiện ích bổ sung trên trang chủ. Chức năng này là chức năng 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 nhiều thẻ được trả về, ứng dụng lưu trữ sẽ hiển thị các 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ủ trong phạm vi này hay không. Trường này là 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 thẻ trang chủ bị tắt đối với tất cả máy chủ (trừ phi bị ghi đè cho máy chủ đó; hãy xem bên dưới).

Ngoài cấu hình phổ biến, còn có các cơ chế ghi đè cho mỗi máy chủ có cấu trúc định dạng như 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 }
        },
        ...
      }
    }

Lưu ý rằng đoạn mã này tương đương với phần trích dẫn 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 mục nào trong số homepageTrigger 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 cũng 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 liên kết hay không. Ví dụ sau cho thấy 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ẽ truyền một đối tượng sự kiện chứa dữ liệu từ ngữ cảnh lệnh gọi.

Các đối tượng sự kiện trên trang chủ không bao gồm tiện ích hoặc thông tin 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:

Xem mục Đối tượng sự kiện để biết thêm thông tin chi tiết.

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

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

Thẻ không theo bối cảnh được xây dựng 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ẻ đó. Xem 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ẻ.