Kartta gezinme

Kart tabanlı çoğu eklenti, eklenti arayüzünün farklı "sayfalarını" temsil eden birden fazla kart kullanılarak oluşturulur. Etkili bir kullanıcı deneyimi sağlamak için eklentinizdeki kartlar arasında basit ve doğal gezinme kullanmalısınız.

Başlangıçta Gmail eklentilerinde, farklı kullanıcı arayüzü kartları arasındaki geçişler, tek bir kart yığınına ve bu yığından çıkarılarak gerçekleştirilir. Bu kartlarda, en üstteki kart Gmail tarafından gösterilir.

Google Workspace Eklentileri, ana sayfaları ve bağlamsal olmayan kartları kullanıma sunar. Google Workspace Eklentilerinin bağlamsal ve bağlamsal olmayan kartlarına uyum sağlamak için her biri için dahili bir kart yığını bulunur. Ana makinede bir eklenti açıldığında, ilgili homepageTrigger, yığındaki ilk ana sayfa kartını (aşağıdaki şemada koyu mavi "ana sayfa" kartı) oluşturmak için etkinleşir. homepageTrigger tanımlanmazsa varsayılan kart oluşturulur, gösterilir ve bağlamsal olmayan yığına aktarılır. Bu ilk kart bir kök karttır.

Eklentiniz, bağlamsal olmayan ilave kartlar oluşturabilir ve kullanıcı eklentinizde gezinirken bunları yığına (şemadaki mavi "aktarılmış kartlar") itebilir. Eklentinin kullanıcı arayüzünde, yığındaki en üstteki kart görüntülenir. Bu nedenle, yığına yeni kartlar gönderildiğinde ekran değişir ve kartların yığından ayrılması, görünümü önceki kartlara döndürür.

Eklentinizin tanımlı bir içerik tetikleyicisi varsa kullanıcı bu bağlamı girdiğinde tetikleyici etkinleşir. Tetikleyici işlevi içerik kartını oluşturur ancak kullanıcı arayüzü görüntüsü yeni kartın DisplayStyle öğesine göre güncellenir:

• DisplayStyle REPLACE (varsayılan) ise içerik kartı (şemadaki koyu turuncu "içerik" kartı) o anda gösterilen kartın yerini alır. Böylece, bağlamsal olmayan kart yığınının üzerinde yeni bir içeriğe dayalı kart yığını başlatılır. Bu içerik kartı, bağlamsal yığının kök kartıdır.
• DisplayStyle PEEK ise kullanıcı arayüzü bunun yerine, eklenti kenar çubuğunun alt kısmında görünen ve mevcut kartın üzerine yerleştirilmiş, gözetilen bir başlık oluşturur. Göz atma başlığı yeni kartın başlığını gösterir ve yeni kartı görüntüleyip görüntülemeyeceklerine karar vermelerini sağlayan kullanıcı düğmesi kontrolleri sağlar. Kullanıcı Görüntüle düğmesini tıklarsa kart, geçerli kartı (yukarıda açıklandığı gibi REPLACE ile) değiştirir.

Ek içeriğe dayalı kartlar oluşturup bunları yığına (şemadaki sarı "aktarılmış kartlar") aktarabilirsiniz. Kart yığınını güncellemek, eklenti kullanıcı arayüzünü en üstteki kartı gösterecek şekilde değiştirir. Kullanıcı bir bağlam bırakırsa yığındaki içerik kartları kaldırılır ve görüntü, bağlamsal olmayan en üstteki kart veya ana sayfaya güncellenir.

Kullanıcı, eklentinizin içeriğe dayalı bir tetikleyici tanımlamadığı bir bağlam girerse yeni kart oluşturulmaz ve geçerli kart gösterilmeye devam eder.

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

Buna karşılık, düğmesi her zaman kullanıcı tarafından içeriğe dayalı kartlarınızdan bağlamsal olmayan kartlarınıza geçiş yapabilir.

Gezinme yöntemleri

Kartlar arasında geçişler oluşturmak için, yığınlara kart ekleyip çıkarabilirsiniz. Navigation sınıfı, yığınlardan kart itip patlatmak için işlevler sağlar. Etkili kart gezinmesi oluşturmak için widget'larınızı gezinme işlemlerini kullanacak şekilde yapılandırırsınız. Birden fazla kartı aynı anda aktarabilir veya büyütebilirsiniz ancak eklenti başladığında ilk olarak yığına itilen ilk ana sayfa kartını kaldıramazsınız.

Kullanıcının bir widget'la etkileşimine yanıt olarak yeni bir karta gitmek için aşağıdaki adımları izleyin:

1. Bir Action nesnesi oluşturun ve bunu tanımladığınız bir geri çağırma işleviyle ilişkilendirin.
2. Söz konusu widget'ta Action öğesini ayarlamak için widget'ın uygun widget işleyici işlevini çağırın.
3. Gezinmeyi gerçekleştiren geri çağırma işlevini uygulayın. Bu işleve bağımsız değişken olarak bir eylem etkinliği nesnesi verilir ve şunları yapması gerekir:
   1. Kart değişikliğini tanımlamak için bir Navigation nesnesi oluşturun. Tek bir Navigation nesnesi, birden çok gezinme adımı içerebilir. Bu adımlar, nesneye eklendikleri sırayla yürütülür.
   2. ActionResponseBuilder sınıfını ve Navigation nesnesini kullanarak bir ActionResponse nesnesi oluşturun.
   3. Derlemeyi geri verme ActionResponse.

Not: Kartlar arasında gezinirken kartların hangi yığına (bağlamsal veya bağlamsal olmayan) ekleneceğini veya kaldırılacağını belirtmezsiniz. Bu, kullanıcı bağlamları girip çıkarken kullanıcı tarafından kontrol edilir. Eklentinizi oluştururken olumlu bir kullanıcı deneyimi sağlamak için kartta gezinme deneyiminizi (bağlam değişiklikleri dahil) ayrıntılı bir şekilde test ettiğinizden emin olun.

Gezinme denetimlerini oluştururken aşağıdaki Navigation nesne işlevlerini kullanırsınız:

İşlev	Açıklama
Navigation.pushCard(Card)	Mevcut yığına bir kart aktarır. Bunun için öncelikle kartı tamamen oluşturmanız gerekir.
Navigation.popCard()	Yığının üst kısmındaki bir kartı kaldırır. Eklenti başlığı satırındaki geri okunun tıklanmasıyla aynı etkiye sahiptir. Bu işlem kök kartları kaldırmaz.
Navigation.popToRoot()	Kök kart hariç tüm kartları yığından kaldırır. Bu işlem temelde kart yığınını sıfırlar.
Navigation.popToNamedCard(String)	Gruptaki kartları, belirtilen ada veya grubun kök kartına ulaşana kadar çıkartır. CardBuilder.setName(String) işlevini kullanarak kartlara ad atayabilirsiniz.
Navigation.updateCard(Card)	Mevcut kartın yerine geçer ve kullanıcı arayüzünde yeni kart görüntülenir.

Gezinmeyle ilgili en iyi uygulama

Bir kullanıcı etkileşiminin veya etkinliğin aynı bağlamda kartların yeniden oluşturulmasıyla sonuçlanması gerekiyorsa mevcut kartları değiştirmek için Navigation.pushCard(), Navigation.popCard() ve Navigation.updateCard() yöntemlerini kullanın. Bir kullanıcı etkileşiminin veya etkinliğin kartların farklı bir bağlamda yeniden oluşturulmasına yol açması gerekiyorsa eklentinizin bu bağlamlarda yeniden yürütülmesini zorunlu kılmak için ActionResponseBuilder.setStateChanged() özelliğini kullanın.

Gezinme örnekleri şunlardır:

• Bir etkileşim veya etkinlik mevcut kartın durumunu değiştirirse (örneğin, bir görev listesine görev eklemek) updateCard() özelliğini kullanın.
• Bir etkileşim veya etkinlik daha fazla ayrıntı sağlıyorsa ya da kullanıcıdan daha fazla işlem yapmasını istiyorsa (örneğin, daha fazla ayrıntı görmek için bir öğenin başlığını tıklamak veya yeni bir Takvim etkinliği oluşturmak için bir düğmeye basmak) için pushCard() simgesini kullanarak yeni sayfayı gösterirken kullanıcının geri düğmesini kullanarak yeni sayfadan çıkmasına izin verin.
• Bir etkileşim veya etkinlik önceki bir kartta güncellenirse (örneğin, bir öğenin başlığını ayrıntı görünümünden güncellemek gibi), önceki kartı ve geçerli kartı güncellemek için popCard(), popCard(), pushCard(previous) ve pushCard(current) gibi bir şey kullanın.

Kartlar yenileniyor

Google Workspace Eklentileri, kullanıcıların manifest dosyanızda kayıtlı Apps Komut Dosyası tetikleyici işlevini yeniden çalıştırarak kartlarını yenilemelerine olanak tanır. Kullanıcılar bu yenilemeyi bir eklenti menü öğesi aracılığıyla tetikler:

Bu işlem, eklentinizin manifest dosyasında (bağlamsal ve bağlamsal olmayan kart yığınlarının "kökleri") belirtildiği gibi, homepageTrigger veya contextualTrigger tetikleyici işlevleri tarafından oluşturulan kartlara otomatik olarak eklenir.

Birden fazla kartı iade etme

Ana sayfa veya bağlamsal tetikleyici işlevleri, uygulama kullanıcı arayüzünün görüntülediği tek bir Card nesnesini veya Card nesneleri dizisi oluşturup döndürmek için kullanılır.

Yalnızca bir kart varsa bu, kök kart ve ana makine uygulamasının kullanıcı arayüzünde gösterildiği gibi bağlamsal olmayan veya bağlamsal yığına eklenir.

Döndürülen dizi, birden fazla oluşturulmuş Card nesnesi içerirse ana makine uygulaması, bunun yerine her kartın başlığının listesini içeren yeni bir kart görüntüler. Kullanıcı bu başlıklardan herhangi birini tıkladığında, kullanıcı arayüzünde ilgili kart görüntülenir.

Kullanıcı listeden bir kart seçtiğinde bu kart geçerli yığına aktarılır ve ana makine uygulaması bunu görüntüler. düğmesi, kullanıcıyı kart başlık listesine geri döndürür.

Eklentiniz, oluşturduğunuz kartlar arasında geçiş gerektirmiyorsa bu "düz" kart düzenlemesi işe yarayabilir. Ancak çoğu durumda, kart geçişlerini doğrudan tanımlamak ve ana sayfanız ile içeriğe dayalı tetikleyici işlevlerinizin tek bir kart nesnesi döndürmesini sağlamak daha iyi bir uygulamadır.

Örnek

Aşağıda, aralarında geçiş yapan gezinme düğmeleri bulunan birkaç kartın nasıl oluşturulacağını gösteren bir örnek verilmiştir. Bu kartlar, createNavigationCard() tarafından döndürülen kartı belirli bir bağlamın içine veya dışına iterek içeriğe dayalı olan veya olmayan yığına eklenebilir.

  /**
   *  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();
  }