التنقّل في البطاقة

يتم إنشاء معظم الإضافات المستندة إلى البطاقة باستخدام خيارات البطاقات التي تمثّل "صفحات" مختلفة من مع واجهة المستخدم الإضافية. للحصول على تجربة مستخدم فعالة، يجب أن تستخدم التنقل البسيط والطبيعي بين البطاقات في الإضافة.

كانت الانتقالات بين البطاقات المختلفة لواجهة المستخدم موجودة في الأصل في إضافات Gmail يتم التعامل معها من خلال دفع البطاقات وتمييزها من وإلى حزمة بطاقات واحدة، البطاقة العلوية من الحزمة التي يعرضها Gmail.

لمحة عن إضافات Google Workspace الصفحات الرئيسية بطاقات غير سياقية. ولاستيعاب البطاقات السياقية وغير السياقية، تحتوي إضافات Google Workspace على حزمة بطاقات داخلية لكل منها. عند فتح إضافة في المضيف، يتم تنشيط homepageTrigger المقابلة لإنشاء أول بطاقة الصفحة الرئيسية على الحزمة (بطاقة "الصفحة الرئيسية" باللون الأزرق الداكن في المخطّط البياني أدناه). إذا لم يتم تحديد homepageTrigger، سيتم إنشاء بطاقة تلقائية وعرضها وإرسالها إلى المكدس غير السياقي. البطاقة الأولى هي بطاقة جذر.

يمكن لإضافتك إنشاء بطاقات إضافية غير سياقية وإرسالها إلى مكدس ("البطاقات المدفوعة" الزرقاء في المخطط) أثناء تنقل المستخدم عبر الإضافة التي تريدها. تعرض واجهة المستخدم الإضافية البطاقة العلوية في الحزمة، لذلك يؤدي الضغط على تؤدي البطاقات إلى الحزمة إلى تغيير طريقة العرض، وينبثق البطاقات من الحزمة مجددًا العرض إلى البطاقات السابقة.

إذا كان للإضافتك قيمة مشغّل سياقي، عندما يدخل المستخدم هذا السياق، يتم تنشيط المشغِّل. دالة المشغّل بطاقة السياقية، ولكن يتم تحديث عرض واجهة المستخدم بناءً على DisplayStyle بالبطاقة الجديدة:

• إذا كانت DisplayStyle هي REPLACE (الافتراضية)، البطاقة السياقية (اللون البرتقالي الداكن "السياقي" في الرسم التخطيطي) تحل محل بطاقة البطاقة المعروضة. يؤدي ذلك بشكل فعّال إلى إطلاق حزمة بطاقات سياقية جديدة في الأعلى. حزمة البطاقات التي لا سياقية عن السياق، وتمثل هذه البطاقة السياقية الجذر ضمن المكدس السياقي.
• إذا كانت DisplayStyle PEEK، تنشئ واجهة المستخدم عنوانًا خاطفًا يظهر في أسفل الشريط الجانبي للإضافة، متراكبًا على البطاقة الحالية. عنوان النظرة السريعة عنوان البطاقة الجديدة ويوفر عناصر تحكم لزر المستخدم تتيح فيقرر عرض البطاقة الجديدة أم لا. إذا نقر المستخدم على عرض ستحل البطاقة محل البطاقة الحالية (كما هو موضح أعلاه REPLACE).

يمكنك إنشاء بطاقات سياقية إضافية ودفعها إلى الحزمة ("البطاقات المدفوعة" الصفراء في المخطط). قيد التحديث تغيّر حزمة البطاقات واجهة المستخدم الإضافية لعرض البطاقة في أقصى الجزء العلوي. إذا كان المستخدم سياقًا، تتم إزالة البطاقات السياقية على الحزمة ويتم عرض تعديلات على البطاقة الرئيسية أو البطاقة الرئيسية غير السياقية

إذا أدخل المستخدم سياقًا لم تحدّده إضافتك سياقه، لن يتم إنشاء بطاقة جديدة فستظل البطاقة الحالية معروضة.

إجراءات Navigation يتم العمل فقط على البطاقات من السياق نفسه كما هو موضّح أدناه. على سبيل المثال، popToRoot() من داخل بطاقة سياقية تنبثق فقط عن جميع البطاقات السياقية الأخرى، لن يؤثر على بطاقات الصفحة الرئيسية.

في المقابل، يعمل الزر arrow_back دائمًا للمستخدم للانتقال من البطاقات السياقية إلى بطاقات لا سياقية

طرق التنقّل

يمكنك الانتقال بين البطاقات من خلال إضافة بطاقات أو إزالتها من حزم البطاقات. Navigation توفر الفئة دوال لدفع البطاقات وتمييزها من الحزم. لإنشاء التنقل الفعال للبطاقة، يمكنك تهيئة التطبيقات المصغّرة لاستخدام ميزة التنقّل الإجراءات يمكنك الضغط أو الضغط بطاقات متعددة في الوقت نفسه، ولكن لا يمكنك إزالة بطاقة الصفحة الرئيسية الأولية التي يتم دفعها أولاً إلى الحزمة عند بدء الإضافة.

للانتقال إلى بطاقة جديدة استجابةً لتفاعل مستخدم مع أداة، اتبع هذه الخطوات:

1. إنشاء عنصر Action وربطه دالة معاودة الاتصال التي تحددها.
2. استدعاء واجهة برمجة تطبيقات مناسبة دالة معالج التطبيقات المصغّرة لضبط Action على هذا التطبيق المصغّر.
3. تنفيذ وظيفة معاودة الاتصال التي تُجري التنقل. هذه الدالة تحديد كائن حدث الإجراء كوسيطة ويجب إجراء ما يلي:
   1. إنشاء Navigation لتحديد تغيير البطاقة. يمكن لكائن Navigation واحد تحتوي على خطوات تنقل متعددة، والتي يتم إجراؤها بالترتيب تتم إضافتها إلى الكائن.
   2. إنشاء ActionResponse باستخدام ActionResponseBuilder الفئة وNavigation الخاص بك.
   3. إرجاع الطراز ActionResponse

عند إنشاء عناصر التحكم في التنقل، يمكنك استخدام ما يلي دوال Navigation:

أفضل ممارسات التنقل

إذا كان من المفترض أن يؤدي تفاعل المستخدم أو الحدث إلى إعادة عرض البطاقات بالطريقة نفسها السياق، استخدام Navigation.pushCard()، Navigation.popCard(), وNavigation.updateCard() طرق لاستبدال البطاقات الحالية. إذا كان يجب أن يكون تفاعل المستخدم أو الحدث تؤدي إلى إعادة عرض البطاقات في سياق مختلف، فتستخدم ActionResponseBuilder.setStateChanged() فرض إعادة تنفيذ الإضافة في تلك السياقات

في ما يلي أمثلة على التنقّل:

• في حال غيَّر التفاعل أو الحدث حالة البطاقة الحالية (على سبيل المثال، إضافة مهمة إلى قائمة مهام)، واستخدام updateCard()
• إذا كان التفاعل أو الحدث يوفر مزيدًا من التفاصيل أو يطلب من المستخدم إجراء إضافي (على سبيل المثال، النقر على عنوان عنصر للاطّلاع على مزيد من التفاصيل) الضغط على زر لإنشاء حدث تقويم جديد)، استخدم pushCard() لعرض الصفحة الجديدة مع السماح للمستخدم بالخروج من الصفحة الجديدة وزر الرجوع.
• إذا تم تعديل تفاعل أو حدث في بطاقة سابقة (على سبيل المثال، وتحديث عنوان العنصر من عرض التفاصيل)، استخدم شيئًا مثل popCard()، popCard(), pushCard(previous), وpushCard(current) لتعديل البطاقة السابقة والبطاقة الحالية.

جارٍ إعادة تحميل البطاقات

تتيح إضافات Google Workspace للمستخدمين إجراء ما يلي: إعادة تحميل بطاقتك عن طريق إعادة تشغيل وظيفة مشغِّل برمجة التطبيقات المسجّلة في البيان. يبدأ المستخدمون عملية إعادة التحميل هذه من خلال عنصر قائمة الإضافة:

تتم إضافة هذا الإجراء تلقائيًا إلى البطاقات التي يُنشئها homepageTrigger أو وظائف المشغِّل contextualTrigger، كما هو محدّد في بيان الإضافة ("جذور" حزم البطاقات السياقية وغير السياقية).

عرض بطاقات متعددة

تُستخدم دوال الصفحة الرئيسية أو دوال التشغيل السياقية لإنشاء إما Card أو مصفوفة من كائنات Card التي واجهة مستخدم التطبيق.

إذا كانت هناك بطاقة واحدة فقط، ستتم إضافتها إلى الحزمة غير السياقية أو السياقية. حيث تعرضها البطاقة الجذر وواجهة مستخدم تطبيق المضيف.

إذا كان الصفيف المعروض يتضمن أكثر من صفيف تم إنشاؤه Card يعرض التطبيق المضيف بطاقة جديدة تحتوي على قائمة بعنوان كل بطاقة. عندما ينقر المستخدم على أي من هذه العناوين، فإن واجهة لعرض البطاقة المقابلة.

عندما يختار المستخدم بطاقة من القائمة، يتم دفع هذه البطاقة إلى الحزمة الحالية ويعرضها تطبيق المضيف. تشير رسالة الأشكال البيانية يُعيد الزر "arrow_back" المستخدم إلى قائمة عناوين البطاقة.

هذه "الشقة" يمكن أن يعمل تنسيق البطاقات بشكل جيد إذا لم تكن إضافتك بحاجة إلى أي والانتقالات بين البطاقات التي تنشئها ومع ذلك، من الأفضل في معظم الحالات التدرب على تحديد انتقالات البطاقات بشكل مباشر، وجعل صفحتك الرئيسية تعرض دوال المشغل السياقي كائن بطاقة واحدًا.

مثال

في ما يلي مثال يوضّح كيفية إنشاء عدة بطاقات باستخدام ميزة التنقّل الأزرار التي تنتقل بينها. يمكن إضافة هذه البطاقات إلى سياقية أو غير سياقية من خلال دفع البطاقة إلى إرجاع التي ينشئها createNavigationCard() في سياق معيّن أو خارجه.

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