Kartta gezinme

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

İlk olarak Gmail eklentilerinde, kullanıcı arayüzünün farklı kartları arasındaki geçişler, tek bir kart yığınına veya yığından kartlar genişletilerek yönetilir. Ayrıca, yığındaki en üstteki kart Gmail tarafından gösterilir.

Ana sayfa kartında gezinme

Google Workspace Eklentilerinde ana sayfalar ve bağlamsal olmayan kartlar bulunur. Google Workspace Eklentileri'nde, bağlama dayalı ve bağlama dayalı olmayan kartlara yer vermek için her biri için dahili bir kart yığını bulunur. Bir ana makinede bir eklenti açıldığında ilgili homepageTrigger, yığındaki ilk ana sayfa kartını (aşağıdaki şemada koyu mavi mavi "ana sayfa" kartı) oluşturmak için tetiklenir. homepageTrigger tanımlanmazsa varsayılan bir kart oluşturulur, gösterilir ve içeriğe dayalı olmayan yığına aktarılır. Bu ilk kart bir kök karttır.

Eklentiniz, kullanıcı eklentinizde gezinirken bağlama dayalı olmayan ek kartlar oluşturabilir ve bunları yığına (şemadaki mavi "aktarılan kartlar") aktarabilir. Eklenti kullanıcı arayüzü, yığındaki en üstteki kartı gösterir. Dolayısıyla, yeni kartlar yığına aktarıldığında ekran değişir, yığınların dışına açıldığında kartlar önceki kartlara döner.

Eklentinizde tanımlı bir bağlamsal tetikleyici 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ü ekranı, yeni kartın DisplayStyle değerine göre güncellenir:

  • DisplayStyle REPLACE ise (varsayılan) içerik kartı (şemadaki koyu turuncu "içeriğe dayalı" kart) şu anda gösterilen kartın yerini alır. Bu, içeriğe dayalı olmayan kart yığınının üzerinde etkili bir şekilde yeni bir bağlama dayalı kart yığını başlatır ve 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 geçerli kartın yer paylaşımlı olacak şekilde, ekranda kısaca beliren bir başlık oluşturur. Göz atma başlığı yeni kartın başlığını gösterir ve kullanıcıya, yeni kartı görüntüleyip görüntülememeye karar veren düğme denetimleri sunar. Kullanıcı Görüntüle düğmesini tıklarsa kart, geçerli kartı değiştirir (yukarıda REPLACE ile açıklandığı gibi).

Ek bağlamsal kartlar oluşturabilir ve bunları yığına (şemadaki sarı "aktarılan kartlar") aktarabilirsiniz. Kart yığınının güncellenmesi, eklenti kullanıcı arayüzünü en üstteki kartı gösterecek şekilde değiştirir. Kullanıcı bir bağlamdan ayrılırsa yığındaki içerik kartları kaldırılır ve güncellemeler, içeriğe dayalı olmayan en üstteki karta veya ana sayfaya gösterilir.

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, popToRoot(), bir içerik kartından yalnızca diğer tüm içerik kartlarını açar ve ana sayfa kartlarını etkilemez.

Buna karşın düğmesi, kullanıcıların içerik kartlarınızdan bağlama dayalı olmayan kartlarınıza gitmesi için her zaman kullanılabilir.

Kart yığınlarına kart ekleyerek veya gruptan kart kaldırarak kartlar arasında geçişler oluşturabilirsiniz. Navigation sınıfı, yığınlardan kart aktarma ve patlatma işlevleri sağlar. Kartlarda etkili gezinme oluşturmak için widget'larınızı gezinme işlemlerini kullanacak şekilde yapılandırırsınız. Aynı anda birden fazla kartı aktarabilir veya açabilirsiniz ancak eklenti başladığında ilk olarak gruba aktarılan ilk ana sayfa kartını kaldıramazsınız.

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

  1. Action nesnesi oluşturun ve bu nesneyi tanımladığınız bir geri çağırma işleviyle ilişkilendirin.
  2. İlgili widget'ta Action değerini ayarlamak için widget'ın uygun widget işleyici işlevini kullanın.
  3. Gezinmeyi yürüten 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, nesneye eklendikleri sırayla yürütülen birden fazla gezinme adımı içerebilir.
    2. ActionResponseBuilder sınıfını ve Navigation nesnesini kullanarak bir ActionResponse nesnesi oluşturun.
    3. Derlemeyi ActionResponse iade edin.

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

İş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ğlamda yeniden oluşturulmasıyla sonuçlanacaksa 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ğinin, kartların farklı bir bağlamda yeniden oluşturulmasına yol açması gerekiyorsa bu bağlamlarda eklentinizin yeniden yürütülmesini zorunlu kılmak için ActionResponseBuilder.setStateChanged() kullanın.

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

  • Bir etkileşim veya etkinlik mevcut kartın durumunu değiştiriyorsa (örneğin, bir görev listesine görev ekleme) updateCard() kullanın.
  • Bir etkileşim veya etkinlik daha fazla ayrıntı sunuyorsa 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ıklama veya yeni bir Takvim etkinliği oluşturmak için bir düğmeye basma) yeni sayfayı göstermek ve kullanıcının geri düğmesini kullanarak yeni sayfadan çıkmasına izin vermek için pushCard() tuşunu kullanın.
  • Önceki kartta bir etkileşim veya etkinlik güncellemesi durumu varsa (örneğin, ayrıntı görünümünden bir öğenin başlığını güncelleme) önceki kartı ve mevcut kartı güncellemek için popCard(), popCard(), pushCard(previous) ve pushCard(current) gibi bir ifade 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 kartınızı yenilemelerine olanak tanır. Kullanıcılar bu yenilemeyi bir eklenti menü öğesi aracılığıyla tetikler:

Google Workspace eklentisi kenar çubuğu

Bu işlem, eklentinizin manifest dosyasında (içeriğe dayalı ve içeriğe dayalı olmayan kart yığınlarının "kökleri") belirtilen şekilde, homepageTrigger veya contextualTrigger tetikleme işlevleri tarafından oluşturulan kartlara otomatik olarak eklenir.

Birden fazla kart iade etme

Örnek eklenti kartı

Ana sayfa veya bağlamsal tetikleyici işlevleri, tek bir Card nesnesi ya da uygulama kullanıcı arayüzünün görüntülediği bir dizi Card nesnesi oluşturmak ve döndürmek için kullanılır.

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

Döndürülen dizide birden fazla derleme Card nesnesi bulunuyorsa ana makine uygulaması bunun yerine, her kartın başlığının bir 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österilir.

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

Eklentiniz, oluşturduğunuz kartlar arasında geçişe ihtiyaç duymuyorsa bu "düz" kart düzenlemesi işe yarayabilir. Bununla birlikte çoğu durumda, kart geçişlerini doğrudan tanımlamak ve ana sayfanız ile bağlamsal 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çinde veya dışında aktararak bağlamsal ya da bağlamsal 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();
  }