Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Açılır liste çiplerini kullanma

Google Docs API, Google Dokümanlar belgelerinde açılır liste çipleri oluşturmanıza, eklemenize, güncellemenize, okumanıza ve yönetmenize olanak tanır.

Açılır liste çipleri nedir?

Google Dokümanlar'daki açılır liste çipleri, kullanıcılara doküman metninde satır içi olarak etkileşimli ve özelleştirilebilir bir seçim menüsü sunar. Kullanıcılar, her biri kendi görüntüleme metnine ve renk stiline sahip önceden tanımlanmış seçenekler listesinden seçim yapmak için bir açılır liste çipini tıklayabilir. Açılır liste çipleri; proje takibi, durum güncellemeleri, inceleme iş akışları ve onay aşamaları için sıklıkla kullanılır.

Docs API ile şunları yapabilirsiniz:

Özelleştirilmiş başlıklar, seçenek adları ve renklerle yeniden kullanılabilir açılır liste şablonları tanımlayın.
Geçerli bir karakter konumuna açılır liste çipleri ekleyin.
Açılır liste çipi örneğinin seçili seçeneğini güncelleyin.
Paylaşılan açılır liste tanımlarını yerinde değiştirerek referans veren tüm çipleri aynı anda güncelleyin.
Mevcut çiplere referans bütünlüğünü koruyarak seçenekleri güvenli bir şekilde değiştirin veya kullanımdan kaldırın.
Kullanılmayan açılır liste şablonlarını silin.

Mimari: tanımlar ve örnekler

Dokümanlar API'sinde açılır liste çipleri tanımlara ve örneklere sahiptir. Tanım, açılır liste örneği için seçenekleri belirler. Açılır liste örneği, kullanıcıların etkileşimde bulunabileceği ve seçimlerle ilgili bilgileri kaydeden bir açılır listedir.

Docs API, açılır liste şablonu yapılandırmasını satır içi açılır liste çipi örneklerinden ayırır:

DropdownDefinition: Açılır liste başlığını ve seçilebilir seçenekler koleksiyonunu (DropdownOption) tanımlayan, sekme düzeyinde bir şablondur. Belgede belirli bir karakter uzaklığında bulunmaz. Bunun yerine, sekmenin tanım haritasında (document.tabs[].documentTab.dropdownDefinitions) saklanır.
Açılır liste: Bir paragraf öğesine (ParagraphElement.dropdown) satır içi olarak yerleştirilmiş bağımsız bir çip örneği. Her açılır liste örneği bir dropdownDefinitionId öğesine referans verir ve kendi etkin selectedOptionId öğesini depolar.

Bir DropdownDefinition öğesini değiştirme (ör. seçenek ekleme veya başlığı yeniden adlandırma), her bir öğenin güncellenmesini gerektirmeden sekmedeki tüm referans çipleri günceller.

Her Dropdown örneği kendi selectedOptionId değerini izler. Tek bir çipin seçili değerinin değiştirilmesi yalnızca söz konusu örneği etkiler.

Kimlik biçimi ve doğrulama kuralları

Kullanıcı tarafından sağlanan kimlikler, katı biçim, önek ve uzunluk özelliklerine uymalıdır:

Tanımlayıcı	Zorunlu önek	Doğrulama normal ifadesi	Uzunluk sınırı	Örnek
Açılır liste tanımı kimliği (`dropdownDefinitionId`)	`kix.`	`^kix\.[a-zA-Z0-9_-]{2,14}$`	6-18 karakter	`kix.review_status`
Açılır liste seçeneği kimliği (`optionId`)	`dropdownItem.`	`^dropdownItem\.[a-zA-Z0-9_-]{2,14}$`	15-27 karakter	`dropdownItem.pending`

Not: Tanım oluştururken dropdownDefinitionId veya optionId karakterlerini atlarsanız sunucu otomatik olarak benzersiz bir kalıcı kimlik oluşturur (ör. kix.8a7b6c5d ve dropdownItem.ydcttxh1yt15). InsertDropdownRequest yürütüldüğünde açılır liste çipi örnek kimlikleri (dropdownId) her zaman sunucu tarafından oluşturulur ve InsertDropdownResponse içinde döndürülür.

Kullanıcı tarafından sağlanan kimlikler oluşturma

Zorunlu önek ve normal ifade koşullarına uyan kimlikler oluşturmak için aşağıdaki yardımcı işlevleri kullanın. Bu yardımcılar, Google Dokümanlar kullanıcı arayüzü tarafından oluşturulan biçime uygun, küçük harfli, 36 tabanlı alfanümerik sonekler oluşturur:

Python

import random
import string

def generate_dropdown_definition_id(suffix_len: int = 8) -> str:
    """Generates a valid user-provided DropdownDefinition ID (6-18 chars, starting with 'kix.')."""
    chars = string.ascii_lowercase + string.digits
    suffix = "".join(random.choices(chars, k=max(2, min(suffix_len, 14))))
    return f"kix.{suffix}"

def generate_dropdown_option_id(suffix_len: int = 8) -> str:
    """Generates a valid user-provided DropdownOption ID (15-27 chars, starting with 'dropdownItem.')."""
    chars = string.ascii_lowercase + string.digits
    suffix = "".join(random.choices(chars, k=max(2, min(suffix_len, 14))))
    return f"dropdownItem.{suffix}"

Java

import java.security.SecureRandom;

public final class DropdownIdGenerator {
  private static final String BASE36_CHARS =
      "abcdefghijklmnopqrstuvwxyz0123456789";
  private static final SecureRandom RANDOM = new SecureRandom();

  private DropdownIdGenerator() {}

  /** Generates a valid user-provided DropdownDefinition ID (6-18 chars, starting with "kix."). */
  public static String generateDefinitionId(int suffixLength) {
    int length = Math.max(2, Math.min(suffixLength, 14));
    StringBuilder sb = new StringBuilder("kix.");
    for (int i = 0; i < length; i++) {
      sb.append(BASE36_CHARS.charAt(RANDOM.nextInt(BASE36_CHARS.length())));
    }
    return sb.toString();
  }

  /** Generates a valid user-provided DropdownOption ID (15-27 chars, starting with "dropdownItem."). */
  public static String generateOptionId(int suffixLength) {
    int length = Math.max(2, Math.min(suffixLength, 14));
    StringBuilder sb = new StringBuilder("dropdownItem.");
    for (int i = 0; i < length; i++) {
      sb.append(BASE36_CHARS.charAt(RANDOM.nextInt(BASE36_CHARS.length())));
    }
    return sb.toString();
  }
}

Açılır liste çipleri oluşturma ve ekleme

Tek toplu oluşturma (önerilir)

En verimli kalıp, documents.batchUpdate çağrısında CreateDropdownDefinitionRequest ve InsertDropdownRequest öğelerini birleştirir.

Aşağıdaki kod örneği, kullanıcı tarafından sağlanan kimlikleri kullanarak üç renk kodlu seçenek içeren bir "İnceleme Durumu" açılır liste tanımı oluşturur ve belgenin sonuna bir örnek ekler:

Python

requests = [
    {
        "createDropdownDefinition": {
            "dropdownDefinition": {
                "dropdownDefinitionId": "kix.review_status",
                "dropdownDefinitionProperties": {
                    "title": "Review Status",
                    "options": [
                        {
                            "optionId": "dropdownItem.pending",
                            "displayValue": "Pending Review",
                            "textStyle": {
                                "backgroundColor": {
                                    "color": {"rgbColor": {"red": 0.99, "green": 0.90, "blue": 0.65}}
                                },
                                "foregroundColor": {
                                    "color": {"rgbColor": {"red": 0.45, "green": 0.30, "blue": 0.0}}
                                },
                            },
                        },
                        {
                            "optionId": "dropdownItem.approved",
                            "displayValue": "Approved",
                            "textStyle": {
                                "backgroundColor": {
                                    "color": {"rgbColor": {"red": 0.85, "green": 0.95, "blue": 0.85}}
                                },
                                "foregroundColor": {
                                    "color": {"rgbColor": {"red": 0.08, "green": 0.40, "blue": 0.15}}
                                },
                            },
                        },
                        {
                            "optionId": "dropdownItem.rejected",
                            "displayValue": "Needs Changes",
                            "textStyle": {
                                "backgroundColor": {
                                    "color": {"rgbColor": {"red": 0.98, "green": 0.84, "blue": 0.84}}
                                },
                                "foregroundColor": {
                                    "color": {"rgbColor": {"red": 0.65, "green": 0.10, "blue": 0.10}}
                                },
                            },
                        },
                    ],
                },
            }
        }
    },
    {
        "insertDropdown": {
            "endOfSegmentLocation": {},
            "dropdownDefinitionId": "kix.review_status",
            "selectedOptionId": "dropdownItem.pending",
        }
    },
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID,
    body={"requests": requests}
).execute()

Java

List<Request> requests = new ArrayList<>();

List<DropdownOption> options = Arrays.asList(
    new DropdownOption()
        .setOptionId("dropdownItem.pending")
        .setDisplayValue("Pending Review")
        .setTextStyle(new TextStyle()
            .setBackgroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.99f).setGreen(0.90f).setBlue(0.65f))))
            .setForegroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.45f).setGreen(0.30f).setBlue(0.0f))))),
    new DropdownOption()
        .setOptionId("dropdownItem.approved")
        .setDisplayValue("Approved")
        .setTextStyle(new TextStyle()
            .setBackgroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.85f).setGreen(0.95f).setBlue(0.85f))))
            .setForegroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.08f).setGreen(0.40f).setBlue(0.15f))))),
    new DropdownOption()
        .setOptionId("dropdownItem.rejected")
        .setDisplayValue("Needs Changes")
        .setTextStyle(new TextStyle()
            .setBackgroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.98f).setGreen(0.84f).setBlue(0.84f))))
            .setForegroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.65f).setGreen(0.10f).setBlue(0.10f))))));

DropdownDefinition definition = new DropdownDefinition()
    .setDropdownDefinitionId("kix.review_status")
    .setDropdownDefinitionProperties(new DropdownDefinitionProperties()
        .setTitle("Review Status")
        .setOptions(options));

requests.add(new Request().setCreateDropdownDefinition(
    new CreateDropdownDefinitionRequest().setDropdownDefinition(definition)));

requests.add(new Request().setInsertDropdown(
    new InsertDropdownRequest()
        .setEndOfSegmentLocation(new EndOfSegmentLocation())
        .setDropdownDefinitionId("kix.review_status")
        .setSelectedOptionId("dropdownItem.pending")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
    .batchUpdate(DOCUMENT_ID, body)
    .execute();

Açılır liste doğrulama kuralları ve sınırları

Açılır liste tanımları oluştururken veya değiştirirken aşağıdaki kısıtlamalar geçerlidir:

Seçenek sayısı: Açılır liste tanımında 2 ile 50 arasında seçenek olmalıdır.
Başlık uzunluğu: Tanım title boş olamaz ve 200 karakteri aşmamalıdır.
Görüntü Değeri Uzunluğu: Her seçeneğin displayValue değeri boş olamaz ve 200 karakteri aşmamalıdır.
Seçenek Stili: DropdownOption.textStyle içinde yalnızca foregroundColor ve backgroundColor desteklenir. Diğer stil özelliklerinin ayarlanması 400 Bad Request hatası döndürür.
Varsayılan Seçim: InsertDropdownRequest içinde selectedOptionId atlanırsa çip, DropdownDefinition içinde tanımlanan ilk seçeneği varsayılan olarak kullanır.

Tek bir açılır liste çipi seçimini güncelleme

Mevcut bir açılır liste çipi örneğinin şablonunu veya diğer çiplerini değiştirmeden seçili seçeneği değiştirmek için UpdateDropdownPropertiesRequest simgesini kullanın:

dropdownId: (Zorunlu) Güncellenecek açılır liste çipi örneğinin kimliği.
tabId: Açılır listeyi içeren sekmenin kimliği (atlanırsa varsayılan olarak ilk sekme kullanılır).
fields: "selectedOptionId" olarak ayarlayın.

Aşağıdaki kod örneğinde, açılır liste çipinin etkin seçimi "dropdownItem.approved" olarak güncellenir:

Python

requests = [
    {
        "updateDropdownProperties": {
            "dropdownId": "kix.chip_abc1",
            "tabId": "t.0",
            "dropdownProperties": {
                "selectedOptionId": "dropdownItem.approved",
            },
            "fields": "selectedOptionId",
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID,
    body={"requests": requests}
).execute()

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setUpdateDropdownProperties(
    new UpdateDropdownPropertiesRequest()
        .setDropdownId("kix.chip_abc1")
        .setTabId("t.0")
        .setDropdownProperties(new DropdownProperties()
            .setSelectedOptionId("dropdownItem.approved"))
        .setFields("selectedOptionId")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
    .batchUpdate(DOCUMENT_ID, body)
    .execute();

Açılır liste tanımlarını ve seçeneklerini güncelleme

Şablonun kendisini (başlık, seçenek listesi, görüntüleme etiketleri veya renkler) değiştirmek için UpdateDropdownDefinitionPropertiesRequest simgesini kullanın. Bir tanımı güncellediğinizde, sekmedeki bu tanıma referans veren tüm açılır liste çipleri otomatik olarak güncellenir.

Seçenekler için tam liste değiştirme

dropdownDefinitionProperties.options, fields maskesine dahil edildiğinde istek tam liste değiştirme işlemi gerçekleştirir. Seçilen sıraya göre seçeneklerin tam listesini sağlamanız gerekir. Sunucu, gelen listeyi mevcut tanıma göre karşılaştırır:

Yeni seçenek: optionId içermeyen (veya yeni kullanıcı tarafından sağlanan bir optionId içeren) bir seçeneğin eklenmesi, bu seçeneği tanıma dahil eder.
Güncellenen seçenek: Değiştirilmiş displayValue veya textStyle güncellemeleri içeren mevcut bir optionId sağlamak, bu seçeneği yerinde günceller.
Yeniden sıralanan seçenekler: Seçenekler listesi, istekte belirtilen sırayla kaydedilir.
Silinen seçenek: Mevcut bir optionId öğesinin atlanması, bu seçeneğin tanımdan silinmesine neden olur.

Referans bütünlüğü ve seçenek değiştirme

Silinen bir seçenek, dokümandaki herhangi bir açılır liste çipinde seçiliyse selectedOptionIdReplacements (map<string, string>) içinde bir eşleme sağlamanız gerekir. Anahtarlar, silinen seçeneklerin kimlikleridir ve değerler, değiştirme seçeneklerinin kimlikleridir.

Önemli: Etkin bir seçenek, selectedOptionIdReplacements alanına giriş yapılmadan silinirse sunucu, isteği 400 Bad Request hatasıyla reddeder. Dokümandaki hiçbir çipte seçilmeyen seçenekler için yedek giriş gerekmez.

Aşağıdaki kod örneğinde, bir açılır liste tanımının seçenek değiştirmeleriyle nasıl güncelleneceği gösterilmektedir:

Python

requests = [
    {
        "updateDropdownDefinitionProperties": {
            "dropdownDefinitionId": "kix.review_status",
            "tabId": "t.0",
            "dropdownDefinitionProperties": {
                "title": "Editorial Review Status",
                "options": [
                    {
                        "optionId": "dropdownItem.approved",
                        "displayValue": "Approved",
                        "textStyle": {
                            "backgroundColor": {
                                "color": {"rgbColor": {"red": 0.85, "green": 0.95, "blue": 0.85}}
                            },
                            "foregroundColor": {
                                "color": {"rgbColor": {"red": 0.08, "green": 0.40, "blue": 0.15}}
                            },
                        },
                    },
                    {
                        "optionId": "dropdownItem.rejected",
                        "displayValue": "Changes Requested",
                        "textStyle": {
                            "backgroundColor": {
                                "color": {"rgbColor": {"red": 0.98, "green": 0.84, "blue": 0.84}}
                            },
                            "foregroundColor": {
                                "color": {"rgbColor": {"red": 0.65, "green": 0.10, "blue": 0.10}}
                            },
                        },
                    },
                ],
            },
            "selectedOptionIdReplacements": {
                "dropdownItem.pending": "dropdownItem.rejected"
            },
            "fields": "title,options",
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID,
    body={"requests": requests}
).execute()

Java

List<DropdownOption> updatedOptions = Arrays.asList(
    new DropdownOption()
        .setOptionId("dropdownItem.approved")
        .setDisplayValue("Approved")
        .setTextStyle(new TextStyle()
            .setBackgroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.85f).setGreen(0.95f).setBlue(0.85f))))
            .setForegroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.08f).setGreen(0.40f).setBlue(0.15f))))),
    new DropdownOption()
        .setOptionId("dropdownItem.rejected")
        .setDisplayValue("Changes Requested")
        .setTextStyle(new TextStyle()
            .setBackgroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.98f).setGreen(0.84f).setBlue(0.84f))))
            .setForegroundColor(new OptionalColor().setColor(
                new Color().setRgbColor(new RgbColor().setRed(0.65f).setGreen(0.10f).setBlue(0.10f))))));

Map<String, String> replacements = new HashMap<>();
replacements.put("dropdownItem.pending", "dropdownItem.rejected");

List<Request> requests = new ArrayList<>();
requests.add(new Request().setUpdateDropdownDefinitionProperties(
    new UpdateDropdownDefinitionPropertiesRequest()
        .setDropdownDefinitionId("kix.review_status")
        .setTabId("t.0")
        .setDropdownDefinitionProperties(new DropdownDefinitionProperties()
            .setTitle("Editorial Review Status")
            .setOptions(updatedOptions))
        .setSelectedOptionIdReplacements(replacements)
        .setFields("title,options")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
    .batchUpdate(DOCUMENT_ID, body)
    .execute();

Açılır liste tanımını silme

Kullanılmayan bir açılır liste şablonunu kaldırmak için DeleteDropdownDefinitionRequest simgesini kullanın.

Dikkat: Belgedeki herhangi bir açılır liste çipi hâlâ dropdownDefinitionId öğesini referans alıyorsa istek 400 Bad Request hatasıyla başarısız olur. Tanımı silmeden önce, tanıma referans veren tüm açılır liste çipi örneklerini silmeniz veya yeniden hedeflemeniz gerekir.

Aşağıdaki kod örneğinde, bir açılır liste tanımının nasıl silineceği gösterilmektedir:

Python

requests = [
    {
        "deleteDropdownDefinition": {
            "dropdownDefinitionId": "kix.review_status",
            "tabId": "t.0",
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID,
    body={"requests": requests}
).execute()

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setDeleteDropdownDefinition(
    new DeleteDropdownDefinitionRequest()
        .setDropdownDefinitionId("kix.review_status")
        .setTabId("t.0")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
    .batchUpdate(DOCUMENT_ID, body)
    .execute();

Hata işleme ve sorun giderme

Sık karşılaşılan hata koşulları ve çözümleri:

Durum Kodu	Neden	Çözünürlük
`400 INVALID_ARGUMENT`	Geçersiz kimlik öneki veya normal ifade biçimi.	`dropdownDefinitionId` değerinin `kix.` ile (6-18 karakter) ve `optionId` değerinin `dropdownItem.` ile (15-27 karakter) başladığından emin olun.
`400 INVALID_ARGUMENT`	Seçenek sayısı sınırların dışında.	Açılır liste tanımı 2 ila 50 seçenek içermelidir.
`400 INVALID_ARGUMENT`	Başlık veya görüntü değeri boş ya da 200 karakteri aşıyor.	1-200 karakter arasında boş olmayan bir dize sağlayın.
`400 INVALID_ARGUMENT`	Seçenekte desteklenmeyen metin stili özelliği.	Açılır menü seçeneklerinde yalnızca `foregroundColor` ve `backgroundColor` desteklenir. Yazı tipini, boyutu veya diğer özellikleri kaldırın.
`400 INVALID_ARGUMENT`	Silme işleminde eksik seçenek değiştirme eşlemesi.	Herhangi bir çip tarafından seçilen bir seçeneği silerken `selectedOptionIdReplacements` içinde geçerli bir alternatif sağlayın.
`400 INVALID_ARGUMENT`	Kullanımda olan bir tanımı silmeye çalıştı.	Tanımı silmeden önce, tanıma referans veren tüm açılır liste çipi örneklerini silin veya yeniden hedefleyin.
`400 INVALID_ARGUMENT`	Kullanıcı tarafından sağlanan kimlik yineleniyor.	Kullanıcı tarafından sağlanan kimliklerin doküman sekmesinde benzersiz olduğundan emin olun.

Açılır liste çiplerini kullanma Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Açılır liste çipleri nedir?

Mimari: tanımlar ve örnekler

Kimlik biçimi ve doğrulama kuralları

Kullanıcı tarafından sağlanan kimlikler oluşturma

Python

Java

Açılır liste çipleri oluşturma ve ekleme

Tek toplu oluşturma (önerilir)

Python

Java

Açılır liste doğrulama kuralları ve sınırları

Tek bir açılır liste çipi seçimini güncelleme

Python

Java

Açılır liste tanımlarını ve seçeneklerini güncelleme

Seçenekler için tam liste değiştirme

Referans bütünlüğü ve seçenek değiştirme

Python

Java

Açılır liste tanımını silme

Python

Java

Hata işleme ve sorun giderme

İlgili konular

Açılır liste çiplerini kullanma