Bu sayfa, Cloud Translation API ile çevrilmiştir.

Widget'lar

Widget, aşağıdakilerden birini veya daha fazlasını sağlayan bir kullanıcı arayüzü öğesidir:

Kartlar ve bölümler gibi diğer widget'lar için yapı,
Metin ve resimler gibi kullanıcıya yönelik bilgiler veya
Düğmeler, metin giriş alanları veya onay kutuları gibi işlem olanakları.

Kart bölümlerine eklenen widget grupları, eklenti kullanıcı arayüzünün genel görünümünü tanımlar. Widget'lar hem web'de hem de mobil cihazlarda aynı görünüme ve işleve sahiptir. Referans dokümanlarında widget setleri oluşturmayla ilgili çeşitli yöntemler açıklanmaktadır.

Eklenti widget'ları genellikle üç gruba ayrılır: yapısal widget'lar, bilgilendirici widget'lar ve kullanıcı etkileşimi widget'ları.

Yapısal widget'lar

Yapısal widget'lar, kullanıcı arayüzünde kullanılan diğer widget'lar için kapsayıcı ve düzen sağlar.

Düğme grubu: Bir veya daha fazla metin ya da resim düğmesinin yatay bir satırda gruplandırıldığı koleksiyon.
Kart: Bir veya daha fazla kart bölümü içeren tek bir bağlam kartı. Kart gezinmesini yapılandırarak kullanıcıların kartlar arasında nasıl hareket edebileceğini tanımlarsınız.
Kart başlığı: Belirli bir kartın başlığı. Kart başlıklarında başlık, altyazı ve resim bulunabilir. Eklenti bunları kullanıyorsa kart işlemleri ve evrensel işlemler kart üstbilgisinde görünür.
Kart bölümü: Diğer kart bölümlerinden yatay bir çizgiyle ayrılmış ve isteğe bağlı olarak bölüm başlığı içeren, bir araya getirilmiş widget grubu. Her kartta en az bir kart bölümü olmalıdır. Kart bölümüne kart veya kart üstbilgileri ekleyemezsiniz.

Yapısal widget'lar

Bu temel yapı widget'larına ek olarak, Google Workspace eklentisinde mevcut kartla örtüşen yapılar oluşturmak için Kart hizmetini kullanabilirsiniz: Sabit altbilgiler ve önizleme kartları:

Sabit altbilgi

Kartınızın alt kısmına sabit bir düğme satırı ekleyebilirsiniz. Bu satır, kart içeriğinin geri kalanıyla birlikte hareket etmez veya kaydırma yapılmaz.

Sabit altbilgi widget'ı örneği

Aşağıdaki kod alıntısından, sabit bir altbilginin nasıl tanımlanacağı ve bir karta nasıl ekleneceği anlaşılabilir:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("Primary")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("Secondary")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "secondaryCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

Göz at kartı

Bir önizleme kartı örneği

Yeni bir bağlamsal içerik, Gmail iletisi açma gibi bir kullanıcı işlemi tarafından tetiklendiğinde yeni bağlamsal içeriği hemen (varsayılan davranış) veya kenar çubuğunun alt kısmında bir göz atma kartı bildirimi gösterebilirsiniz. Bir bağlamsal tetikleyici etkinken kullanıcı ana sayfanıza dönmek için Geri düğmesini tıklarsa kullanıcıların bağlamsal içeriği tekrar bulmasına yardımcı olmak için bir önizleme kartı gösterilir.

Yeni bağlamsal içerik mevcut olduğunda bir önizleme kartı görüntülemek için yeni bağlamsal içeriği hemen görüntülemek yerine CardBuilder sınıfınıza .setDisplayStyle(CardService.DisplayStyle.PEEK) ekleyin. Bir önizleme kartı yalnızca bağlamsal tetikleyicinizle birlikte tek bir kart nesnesi döndürülürse gösterilir. Aksi takdirde, döndürülen kartlar mevcut kartın yerini hemen alır.

Bir önizleme kartının başlığını özelleştirmek için bağlama dayalı kartınızı oluştururken standart bir CardHeader nesnesi ile .setPeekCardHeader() yöntemini ekleyin. Varsayılan olarak, önizleme kartı başlığı yalnızca eklentinizin adını içerir.

Özelleştirilmiş önizleme kartı örneği

Cats Google Workspace eklentisi hızlı başlangıç kılavuzunu temel alan aşağıdaki kod, kullanıcıları bir göz atma kartı ile yeni bağlamsal içerikler hakkında bilgilendirir ve göz atma kartının başlığını, seçili Gmail ileti dizisinin konusunu gösterecek şekilde özelleştirir.

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);

Bilgilendirme amaçlı widget'lar

Bilgilendirici widget'lar kullanıcıya bilgi sunar.

Resim: Sağladığınız, barındırılan ve herkese açık bir URL ile gösterilen resim.
DecoratedText: Üst ve alt metin etiketleri, resim veya simge gibi diğer öğelerle eşleştirebileceğiniz bir metin içeriği dizesi. DecoratedText widget'ları Button veya Switch widget'ı da içerebilir. Eklenen anahtarlar açma/kapatma düğmeleri veya onay kutuları olabilir. DecoratedText widget'ının içerik metninde HTML biçimlendirmesi kullanılabilir. Üst ve alt etiketlerde ise düz metin kullanılmalıdır.
Metin paragrafı: HTML biçimli öğeler içerebilen bir metin paragrafı.

Bilgilendirme amaçlı widget'lar

Kullanıcı etkileşimi widget'ları

Kullanıcı etkileşimi widget'ları, eklentinin kullanıcılar tarafından gerçekleştirilen işlemlere yanıt vermesine olanak tanır. Farklı kartlar görüntülemek, URL'leri açmak, bildirimler göstermek, e-posta taslağı oluşturmak veya diğer Apps Script işlevlerini çalıştırmak için bu widget'ları işlem yanıtlarıyla yapılandırabilirsiniz. Ayrıntılar için Etkileşimli Kartlar Oluşturma kılavuzuna bakın.

Kart işlemi: Eklenti başlık çubuğu menüsüne yerleştirilmiş bir menü öğesidir. Başlık çubuğu menüsünde, eklentinin tanımladığı her kartta görünen evrensel işlemler olarak tanımlanan öğeler de bulunabilir.
Tarih ve saat seçicileri: Kullanıcıların tarih, saat veya her ikisini birden seçmesine olanak tanıyan widget'lar. Daha fazla bilgi için aşağıdaki Tarih ve saat seçicileri bölümünü inceleyin.
Resim düğmesi: Metin yerine resim kullanan bir düğmedir. Önceden tanımlanmış simgelerden birini veya URL'si ile belirtilen herkese açık bir resmi kullanabilirsiniz.
Seçim girişi: Bir seçenek koleksiyonunu temsil eden giriş alanı. Onay kutuları, radyo düğmeleri veya açılır seçim kutuları olarak sunulan seçim girişi widget'ları.
Anahtar: Açma/kapatma widget'ı. Geçiş düğmelerini yalnızca DecoratedText widget'ıyla birlikte kullanabilirsiniz. Bunlar varsayılan olarak bir açma/kapatma düğmesi olarak gösterilir ancak bunun yerine onay kutusu olarak gösterilmesini sağlayabilirsiniz.
Metin düğmesi: Metin etiketi içeren bir düğmedir. Metin düğmeleri için arka plan rengi dolgusu belirtebilirsiniz (varsayılan olarak şeffaftır). Gerekirse düğmeyi devre dışı da bırakabilirsiniz.
Metin girişi: Metin giriş alanı. Widget'ta başlık metni, ipucu metni ve çok satırlı metin bulunabilir. Widget, metin değeri değiştiğinde işlemleri tetikleyebilir.
Gri grid: Bir öğe koleksiyonunu temsil eden çok sütunlu bir düzendir. Öğeleri resim, başlık, altyazı ve kenarlıklar ile kırpma stilleri gibi çeşitli özelleştirme seçenekleriyle gösterebilirsiniz.

`DecoratedText` onay kutuları

Düğme veya ikili açma/kapatma anahtarı yerine onay kutusu eklenmiş bir DecoratedText widget'ı tanımlayabilirsiniz. Anahtarlarda olduğu gibi, onay kutusunun değeri, setOnClickAction(action) yöntemi tarafından bu DecoratedText öğesine bağlı Action öğesine iletilen işlem etkinliği nesnesine dahil edilir.

Süslenmiş metin onay kutusu widget'ı örneği

Aşağıdaki kod alıntısında, bir karta ekleyebileceğiniz onay kutusu DecoratedText widget'ının nasıl tanımlanacağı gösterilmektedir:

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

Tarih ve saat seçicileri

Kullanıcıların saat, tarih veya her ikisini birden seçmesine olanak tanıyan widget'lar tanımlayabilirsiniz. Seçicinin değeri değiştiğinde çalışacak bir widget işleyici işlevi atamak için setOnChangeAction()'ü kullanabilirsiniz.

Özelleştirilmiş önizleme kartı örneği

Aşağıdaki kod alıntısında, yalnızca tarih seçici, yalnızca saat seçici ve tarih saat seçicinin nasıl tanımlanacağı gösterilmektedir. Bu seçicileri daha sonra bir karta ekleyebilirsiniz:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter a date")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter a time")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter a date and time")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));

Aşağıda, tarih ve saat seçici widget işleyici işlevi örneği verilmiştir. Bu işleyici, "myDateTimePickerWidgetID" kimlikli bir tarih/saat seçici widget'ında kullanıcı tarafından seçilen tarih ve saati temsil eden bir dizeyi biçimlendirip günlüğe kaydeder:

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See https://developers.google.com/workspace/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

Aşağıdaki tabloda, masaüstü ve mobil cihazlardaki seçici seçim kullanıcı arayüzlerine örnekler verilmiştir. Tarih seçici, seçildiğinde kullanıcının yeni bir tarihi hızlıca seçmesine olanak tanımak için aya dayalı bir takvim kullanıcı arayüzü açar.

Kullanıcı masaüstü cihazlarda saat seçiciyi seçtiğinde, 30 dakikalık artışlarla ayrılmış ve kullanıcının aralarından seçim yapabileceği saatlerin listesinin bulunduğu bir açılır menü açılır. Kullanıcı belirli bir saat de yazabilir. Mobil cihazlarda bir saat seçiciyi seçtiğinizde yerleşik mobil "saat" saat seçici açılır.

Masaüstü	Mobil

Izgara

Öğeleri ızgara widget'ı ile çok sütunlu bir düzende görüntüleyin. Her öğede resim, başlık ve altyazı gösterilebilir. Metnin, ızgara öğesindeki resme göre konumunu ayarlamak için ek yapılandırma seçeneklerini kullanın.

Bir ızgara öğesini, ızgara üzerinde tanımlanan işleme parametre olarak döndürülen bir tanımlayıcıyla yapılandırabilirsiniz.

Izgara widget'ı örneği

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.RECTANGLE_4_3);

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

var grid = CardService.newGrid()
  .setTitle("Recently viewed")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));

Metin biçimlendirmesi

Bazı metin tabanlı widget'lar basit metin HTML biçimlendirmesini destekleyebilir. Bu widget'ların metin içeriğini ayarlarken karşılık gelen HTML etiketlerini eklemeniz yeterlidir.

Desteklenen etiketler ve amaçları aşağıdaki tabloda gösterilmektedir:

Biçim	Örnek	Oluşturulan sonuç
Kalın	`"This is <b>bold</b>."`	Bu metin kalın yazılmıştır.
İtalik	`"This is <i>italics</i>."`	Bu italik.
Altı çizili	`"This is <u>underline</u>."`	Bu altı çizili.
Üstü çizili	`"This is <s>strikethrough</s>."`	Bu ~~üstü çizili~~ metindir.
Yazı tipi rengi	`"This is <font color=\"#FF0000\">red font</font>."`	Bu kırmızı yazı tipidir.
Köprü	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	Bu bir köprü.
Saat	`"This is a time format: <time>2023-02-16 15:00</time>."`	Bu bir saat biçimidir: 2023-02-16 15:00.
Yeni satır	`"This is the first line. <br> This is a new line.`"	Bu ilk satırdır. Bu yeni bir satırdır.

Widget'lar

Widget türleri

Yapısal widget'lar

Sabit altbilgi

Göz at kartı

Bilgilendirme amaçlı widget'lar

Kullanıcı etkileşimi widget'ları

DecoratedText onay kutuları

Tarih ve saat seçicileri

Izgara

Metin biçimlendirmesi

`DecoratedText` onay kutuları