Kartta gezinme

Kart tabanlı eklentilerin çoğu, Farklı "sayfaları" temsil eden kartlar ekleyebilirsiniz. Etkili bir kullanıcı deneyimi için eklentinizdeki kartlar arasında basit ve doğal bir gezinme deneyimi kullanmalısınız.

İlk olarak Gmail eklentilerinde, kullanıcı arayüzünün farklı kartları arasındaki geçişler tek bir kart yığınına veya desteden kart çıkarılarak atılarak yapılır. Gmail tarafından gösterilen grubun en üstündeki kart.

Ana sayfa kartında gezinme

Google Workspace Eklentileri tanıtımları homepages ve bağlama dayalı olmayan kartlar. Bağlamsal ve bağlama dayalı olmayan kartlara yer vermek için Google Workspace Eklentilerinde dahili bir kart yığını var her biri için. Eklenti açıldığında bir ana makinede, karşılık gelen homepageTrigger tetiklenerek gruptaki ana sayfa kartı (aşağıdaki şemada yer alan koyu mavi "ana sayfa" kartı). homepageTrigger tanımlı değilse varsayılan kart oluşturulur, bağlamsal olmayan yığına aktarılır. Bu ilk kart bir kök karttır.

Eklentiniz bağlam dışı ek kartlar oluşturabilir ve bunları (şemadaki mavi "aktarılan kartlar") gösterilir. ekleyebilirsiniz. Eklenti kullanıcı arayüzü, yığında en üstteki kartı gösterir. Bu nedenle, Yığına eklenen kartlar görünümü değiştirir ve kartları yığından çıkarmak önceki kartlara gösterme.

Eklentinizin tanımlı bir içeriğe dayalı tetikleyici, Kullanıcı bu bağlamı girdiğinde tetikleyici etkinleşir. Tetikleyici işlevi bağlam kartını oluşturur, ancak kullanıcı arayüzü görünümü DisplayStyle yeni kartın:

  • DisplayStyle REPLACE (varsayılan), içerik kartı (koyu turuncu) "bağlamsal" kartı), mevcut gösterilen kart. Böylece üstte yeni bir bağlamsal kart yığını etkili bir şekilde başlatılır bağlamsal olmayan kart yığınıdır ve bu bağlam kartı, kök içeriğe dayalı yığının kartıdır.
  • DisplayStyle PEEK ise kullanıcı arayüzü, bunun yerine eklenti kenar çubuğunun alt kısmına giderek geçerli kartın üzerine yerleştirin. Göz atma başlığı yeni kartın başlığını gösterir ve yeni kartı görüntüleyip görüntülememeye karar verir. Kullanıcı Görünüm'ü tıklarsa düğmesi, kart geçerli kartı (yukarıda açıklandığı gibi REPLACE).

Ek bağlam kartları oluşturabilir ve bunları yığa itin (şemadaki sarı "içe aktarılan kartlar"). Güncelleniyor Kart yığını, eklenti kullanıcı arayüzünü en üstteki kartı gösterecek şekilde değiştirir. Kullanıcı bir bağlam bıraktığında, gruptaki içerik kartları kaldırılır ve içeriğe dayalı olmayan en üstteki kartta veya ana sayfada güncellemeler yapar.

Kullanıcı, eklentinizin tanımlamadığı bir bağlam girerse bağlamsal tetikleyici, yeni kart oluşturulmaz ve geçerli kart görüntülenmeye devam eder.

Navigation işlemleri aşağıda açıklananlar yalnızca aynı bağlamdaki kartlarda işlem yapar; örneğin, popToRoot() bağlamsal bir kart içindeyken yalnızca diğer tüm içerik kartları gösterilir ve ana sayfa kartlarını etkilemez.

Buna karşılık düğmesi içerik kartlarınızdan bağlama dayalı olmayan kartlar.

Ayrıca, kartlarından oluşur. Navigation sınıfı, yığınlardan kart itme ve patlatma işlevleri sağlar. Bina oluşturmak için etkin kart gezinmesi için, Gezinmeyi kullanmak için widget'lar işlem. Basabilir veya popülasyona aynı anda birden fazla kart, ancak ilk ana sayfa kartını kaldıramazsınız. ilk olarak yığına aktarılan bir satır öğesidir.

Kullanıcının widget'la etkileşimine yanıt olarak yeni bir karta gitmek için: şu adımları uygulayın:

  1. Action nesnesi oluşturma Böylece, bunu bir geri çağırma işlevi her şeyi kapsıyor.
  2. Widget'ın uygun widget işleyici işlevi widget'ta Action değerini ayarlayın.
  3. Gezinmeyi yürüten geri çağırma işlevini uygulayın. Bu işlev Bir işlem etkinliği nesnesi verildiğinde bağımsız değişken olarak kullanıyorsanız ve aşağıdakileri yapmanız gerekir:
    1. Bir Navigation oluşturun nesnesini tanımlayın. Tek bir Navigation nesnesi sırasıyla gerçekleştirilen birden çok gezinme adımını içermelidir. bu öğeler nesneye eklenir.
    2. ActionResponse oluşturun nesnesini ActionResponseBuilder sınıfı ve Navigation nesnesini tanımlayın.
    3. İnşa edilen ActionResponse.
ziyaret edin.

Gezinme denetimleri oluştururken aşağıdakileri kullanırsınız: Navigation nesne işlevleri:

İşlev Açıklama
Navigation.pushCard(Card) Bir kartı geçerli gruba aktarır. Bunun için önce kartı tamamen oluşturmanız gerekir.
Navigation.popCard() Yığının en üstündeki bir kartı kaldırır. Eklenti başlığı satırındaki geri okunu tıklamaya eşdeğerdir. Bu işlem, kök kartları kaldırmaz.
Navigation.popToRoot() Kök kart hariç gruptaki tüm kartları kaldırır. Esasen, ilgili kart yığınını sıfırlar.
Navigation.popToNamedCard(String) Belirtilen ada veya yığının kök kartına sahip bir karta ulaşana kadar destedeki kartları gösterir. CardBuilder.setName(String) işlevini kullanarak kartlara ad atayabilirsiniz.
Navigation.updateCard(Card) Mevcut kartı yerinde değiştirerek kullanıcı arayüzünde görünümünü yeniler.

Bir kullanıcı etkileşimi veya etkinliği, kartların aynı bağlam, kullan Navigation.pushCard() Navigation.popCard(), ve Navigation.updateCard() yöntemlerine göz atacağız. Bir kullanıcı etkileşiminin veya etkinliğin kartları farklı bir bağlamda yeniden sunabilir, ActionResponseBuilder.setStateChanged() yüklemeniz gerekebilir.

Aşağıda gezinme örnekleri verilmiştir:

  • Bir etkileşim veya etkinlik mevcut kartın durumunu değiştirirse (örneğin, bir görev listesine görev ekleme) olarak bilinen updateCard().
  • Bir etkileşim veya etkinlik, daha fazla ayrıntı sağlıyorsa ya da kullanıcıdan ek işlem (örneğin, daha fazla ayrıntı görmek için bir öğenin başlığını tıklama veya yeni bir Takvim etkinliği oluşturmak için bir düğmeye basarak) pushCard() yeni sayfayı göstermek için kullanıcının geri düğmesi.
  • Etkileşim veya etkinlik güncellemeleri önceki bir kartta görünüyorsa (örneğin, ayrıntı görünümünden bir öğenin başlığını güncellerseniz) popCard() popCard(), pushCard(previous), ve pushCard(current) önceki kartı ve geçerli kartı güncelleyin.

Kartlar yenileniyor

Google Workspace Eklentileri, kullanıcılara şurada kayıtlı Apps Komut Dosyası tetikleyici işlevini yeniden çalıştırarak kartınızı yenileyin manifest dosyanız. Kullanıcılar bu yenilemeyi bir eklenti menü öğesi aracılığıyla tetikler:

Google Workspace eklentisi kenar çubuğu

Bu işlem, homepageTrigger veya Eklentinizin manifest dosyasında belirtildiği şekliyle contextualTrigger tetikleme işlevleri dosyası (bağlamsal ve bağlamsal olmayan kart yığınlarının "kökleri")

Birden fazla kart iade etme

Örnek eklenti kartı

Ana sayfa veya bağlamsal tetikleme işlevleri, oluşturma ve geri dönüş için kullanılır ya tek Card nesnesi veya bir dizisi Card nesne kullanıcı arayüzü görüntülenir.

Tek bir kart varsa bu kart, bağlamsal olmayan veya içeriğe dayalı olmayan gruba eklenir ana makine uygulamasının kullanıcı arayüzünde gösterilir.

Döndürülen dizide birden fazla derleme varsa Card ana makine uygulaması bunun yerine, yeni bir kart içeren yeni bir kart görüntüler. her kartın başlık listesini gösterir. Kullanıcı bu başlıklardan herhangi birini tıkladığında, ilgili kart görüntülenir.

Kullanıcı listeden bir kart seçtiğinde, bu kart ana makine uygulamasında gösterir. İlgili içeriği oluşturmak için kullanılan düğmesi, kullanıcıyı kart başlığı listesi.

Bu "düz" Eklentiniz için herhangi bir ödeme yapmanız gerekmiyorsa kart düzenlemesi her şeyi görüntüleyebilirsiniz. Ancak çoğu durumda kart geçişlerini doğrudan tanımlamak ve ana sayfanızın bağlamsal tetikleyici işlevleri tek bir kart nesnesi döndürür.

Örnek

Burada, gezinme içeren birkaç kartın nasıl oluşturulacağını gösteren bir örnek verilmiştir düğmelerdir. Bu kartlar kartı aktararak bağlamsal veya bağlamsal olmayan yığın belirli bir bağlam içinde veya dışında createNavigationCard() tarafından.

  /**
   *  Create the top-level card, with buttons leading to each of three
   *  'children' cards, as well as buttons to backtrack and return to the
   *  root card of the stack.
   *  @return {Card}
   */
  function createNavigationCard() {
    // Create a button set with actions to navigate to 3 different
    // 'children' cards.
    var buttonSet = CardService.newButtonSet();
    for(var i = 1; i <= 3; i++) {
      buttonSet.addButton(createToCardButton(i));
    }

    // Build the card with all the buttons (two rows)
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle('Navigation'))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()));
    return card.build();
  }

  /**
   *  Create a button that navigates to the specified child card.
   *  @return {TextButton}
   */
  function createToCardButton(id) {
    var action = CardService.newAction()
        .setFunctionName('gotoChildCard')
        .setParameters({'id': id.toString()});
    var button = CardService.newTextButton()
        .setText('Card ' + id)
        .setOnClickAction(action);
    return button;
  }

  /**
   *  Create a ButtonSet with two buttons: one that backtracks to the
   *  last card and another that returns to the original (root) card.
   *  @return {ButtonSet}
   */
  function buildPreviousAndRootButtonSet() {
    var previousButton = CardService.newTextButton()
        .setText('Back')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoPreviousCard'));
    var toRootButton = CardService.newTextButton()
        .setText('To Root')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoRootCard'));

    // Return a new ButtonSet containing these two buttons.
    return CardService.newButtonSet()
        .addButton(previousButton)
        .addButton(toRootButton);
  }

  /**
   *  Create a child card, with buttons leading to each of the other
   *  child cards, and then navigate to it.
   *  @param {Object} e object containing the id of the card to build.
   *  @return {ActionResponse}
   */
  function gotoChildCard(e) {
    var id = parseInt(e.parameters.id);  // Current card ID
    var id2 = (id==3) ? 1 : id + 1;      // 2nd card ID
    var id3 = (id==1) ? 3 : id - 1;      // 3rd card ID
    var title = 'CARD ' + id;

    // Create buttons that go to the other two child cards.
    var buttonSet = CardService.newButtonSet()
      .addButton(createToCardButton(id2))
      .addButton(createToCardButton(id3));

    // Build the child card.
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle(title))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()))
        .build();

    // Create a Navigation object to push the card onto the stack.
    // Return a built ActionResponse that uses the navigation object.
    var nav = CardService.newNavigation().pushCard(card);
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Pop a card from the stack.
   *  @return {ActionResponse}
   */
  function gotoPreviousCard() {
    var nav = CardService.newNavigation().popCard();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Return to the initial add-on card.
   *  @return {ActionResponse}
   */
  function gotoRootCard() {
    var nav = CardService.newNavigation().popToRoot();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }