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

العمل باستخدام شرائح القوائم المنسدلة

تتيح لك واجهة برمجة تطبيقات "مستندات Google" إنشاء شرائح القائمة المنسدلة وإدراجها وتعديلها وقراءتها وإدارتها آليًا ضمن مستندات Google.

ما هي شرائح القوائم المنسدلة؟

توفّر شرائح القوائم المنسدلة في "مستندات Google" للمستخدمين قائمة اختيار تفاعلية وقابلة للتخصيص مضمّنة في نص المستند. يمكن للمستخدمين النقر على شريحة قائمة منسدلة للاختيار من قائمة خيارات محدّدة مسبقًا، ولكل منها نص عرض وأسلوب ألوان خاص. تُستخدَم شرائح القوائم المنسدلة بشكل متكرر لتتبُّع المشاريع وتحديثات الحالة وسير عمل المراجعة ومراحل الموافقة.

من خلال Docs API، يمكنك إجراء ما يلي:

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

الهندسة المعمارية: التعريفات والأمثلة

في Docs API، تحتوي شرائح القوائم المنسدلة على تعريفات ومثيلات. يحدّد التعريف خيارات لمثيل قائمة منسدلة. مثيل القائمة المنسدلة هو قائمة منسدلة يمكن للمستخدمين التفاعل معها، ويحفظ معلومات حول الاختيارات.

تفصل واجهة Docs API إعدادات نموذج القائمة المنسدلة عن مثيلات شريحة القائمة المنسدلة المضمّنة:

DropdownDefinition: نموذج على مستوى علامة التبويب يحدّد عنوان القائمة المنسدلة ومجموعة الخيارات القابلة للتحديد (DropdownOption). لا يقع هذا النموذج عند موضع إزاحة محدد في المستند، بل يتم تخزينه في خريطة تعريف علامة التبويب: document.tabs[].documentTab.dropdownDefinitions.
القائمة المنسدلة: هي مثيل فردي لرقاقة مضمّن في سطر واحد ضمن عنصر فقرة (ParagraphElement.dropdown). يشير كل مثيل لقائمة منسدلة إلى dropdownDefinitionId ويخزّن selectedOptionId النشط الخاص به.

يؤدي تعديل DropdownDefinition (مثل إضافة خيار أو إعادة تسمية العنوان) إلى تعديل جميع الشرائح المرجعية في علامة التبويب بدون الحاجة إلى تعديل كل عنصر على حدة.

يتتبّع كل مثيل Dropdown قيمة selectedOptionId الخاصة به. يؤثر تغيير القيمة المحدّدة لشريحة فردية في هذا المثال المحدّد فقط.

قواعد التحقّق من صحة تنسيق المعرّف

يجب أن تلتزم المعرّفات المقدَّمة من المستخدِم بمواصفات التنسيق والبادئة والطول الصارمة التالية:

المُعرّف	البادئة الإلزامية	التعبير العادي للتحقّق من الصحة	حدّ الطول	مثال
رقم تعريف القائمة المنسدلة (`dropdownDefinitionId`)	`kix.`	`^kix\.[a-zA-Z0-9_-]{2,14}$`	من 6 إلى 18 حرفًا	`kix.review_status`
رقم تعريف خيار القائمة المنسدلة (`optionId`)	`dropdownItem.`	`^dropdownItem\.[a-zA-Z0-9_-]{2,14}$`	من 15 إلى 27 حرفًا	`dropdownItem.pending`

ملاحظة: في حال حذف dropdownDefinitionId أو optionId عند إنشاء تعريف، ينشئ الخادم تلقائيًا معرّفًا فريدًا دائمًا (على سبيل المثال، kix.8a7b6c5d وdropdownItem.ydcttxh1yt15). ينشئ الخادم دائمًا معرّفات مثيل شريحة القائمة المنسدلة (dropdownId) عند تنفيذ InsertDropdownRequest ويتم عرضها في InsertDropdownResponse.

إنشاء أرقام تعريف مقدَّمة من المستخدم

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

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}"

جافا

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

إنشاء شرائح القوائم المنسدلة وإدراجها

إنشاء دفعة واحدة (يُوصى به)

يجمع النمط الأكثر كفاءة بين CreateDropdownDefinitionRequest وInsertDropdownRequest في طلب documents.batchUpdate واحد.

تنشئ عينة تعليمات برمجية التالية تعريفًا لقائمة منسدلة باسم "حالة المراجعة" تتضمّن ثلاثة خيارات مرمّزة بالألوان باستخدام أرقام تعريف يقدّمها المستخدم، وتُدرج نسخة في نهاية المستند:

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()

جافا

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();

قواعد التحقّق من صحة القوائم المنسدلة وحدودها

عند إنشاء تعريفات القوائم المنسدلة أو تعديلها، تنطبق القيود التالية:

عدد الخيارات: يجب أن يتضمّن تعريف القائمة المنسدلة ما بين 2 و50 خيارًا.
طول العنوان: يجب ألا يكون تعريف title فارغًا، ويجب ألا يتجاوز 200 حرفًا.
طول قيمة العرض: يجب ألا يكون displayValue لكل خيار فارغًا، ويجب ألا يتجاوز 200 حرفًا.
تنسيق الخيارات: لا تتوافق سوى القيمتان foregroundColor وbackgroundColor مع DropdownOption.textStyle. يؤدي ضبط سمات الأنماط الأخرى إلى ظهور الخطأ 400 Bad Request.
الاختيار التلقائي: في InsertDropdownRequest، إذا تم حذف selectedOptionId، يتم ضبط الخيار التلقائي على الخيار الأول المحدّد في DropdownDefinition.

تعديل اختيار شريحة قائمة منسدلة فردية

لتغيير الخيار المحدّد لنسخة حالية من شريحة القائمة المنسدلة بدون تغيير نموذجها أو شرائح أخرى، استخدِم UpdateDropdownPropertiesRequest:

استبدِل dropdownId: (مطلوب) بمعرّف مثيل شريحة القائمة المنسدلة المحدّد الذي تريد تعديله.
‫tabId: رقم تعريف علامة التبويب التي تحتوي على القائمة المنسدلة (يتم ضبطها تلقائيًا على علامة التبويب الأولى في حال حذفها).
‫fields: اضبط القيمة على "selectedOptionId".

يعدّل نموذج الرمز البرمجي التالي التحديد النشط لشريحة القائمة المنسدلة إلى "dropdownItem.approved":

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()

جافا

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();

تعديل تعريفات القائمة المنسدلة وخياراتها

لتعديل النموذج نفسه (العنوان أو قائمة الخيارات أو تصنيفات العرض أو الألوان)، استخدِم UpdateDropdownDefinitionPropertiesRequest. يؤدي تعديل تعريف إلى تعديل جميع شرائح القائمة المنسدلة التي تشير إليه تلقائيًا في علامة التبويب.

استبدال القائمة الكاملة للخيارات

عند تضمين dropdownDefinitionProperties.options في قناع fields، ينفّذ الطلب استبدالاً كاملاً للقائمة. يجب تقديم القائمة الكاملة للخيارات بالترتيب المحدّد. يقارن الخادم القائمة الواردة بالتعريف الحالي:

خيار جديد: يؤدي تضمين خيار بدون optionId (أو مع optionId جديد يقدّمه المستخدم) إلى إضافته إلى التعريف.
الخيار المعدَّل: يؤدي تقديم optionId حالي مع تعديلات على displayValue أو textStyle إلى تعديل هذا الخيار.
الخيارات المعاد ترتيبها: يتم حفظ قائمة الخيارات بالتسلسل الدقيق المقدَّم في الطلب.
الخيار المحذوف: يؤدي حذف optionId حالي إلى إزالة هذا الخيار من التعريف.

التكامل المرجعي واستبدال الخيار

إذا تم تحديد خيار سيتم حذفه في أي شريحة قائمة منسدلة ضمن المستند، عليك توفير عملية ربط في selectedOptionIdReplacements (map<string, string>). المفاتيح هي معرّفات الخيارات التي سيتم حذفها، والقيم هي معرّفات الخيارات البديلة.

ملاحظة مهمة: إذا تم حذف خيار نشط بدون تقديم إدخال في selectedOptionIdReplacements، سيرفض الخادم الطلب مع ظهور الخطأ 400 Bad Request. لا تتطلّب الخيارات غير المحدّدة في أي شريحة في المستند إدخال بديل.

يوضّح نموذج الرمز البرمجي التالي كيفية تعديل تعريف قائمة منسدلة باستخدام بدائل الخيارات:

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()

جافا

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();

حذف تعريف قائمة منسدلة

لإزالة نموذج قائمة منسدلة غير مستخدَم، استخدِم DeleteDropdownDefinitionRequest.

تنبيه: إذا كانت أي شرائح من القائمة المنسدلة في المستند لا تزال تشير إلى dropdownDefinitionId، سيتعذّر تنفيذ الطلب وسيظهر الخطأ 400 Bad Request. يجب حذف جميع مثيلات شريحة القائمة المنسدلة التي تشير إلى التعريف أو إعادة استهدافها قبل حذف التعريف.

يوضّح نموذج الرمز البرمجي التالي كيفية حذف تعريف قائمة منسدلة:

Python

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

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

جافا

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();

معالجة الأخطاء وتحديد المشاكل وحلّها

شروط الخطأ الشائعة والحلول:

رمز الحالة	السبب	الدقة
`400 INVALID_ARGUMENT`	بادئة المعرّف أو تنسيق التعبير العادي غير صالح.	تأكَّد من أنّ `dropdownDefinitionId` يبدأ بـ `kix.` (من 6 إلى 18 حرفًا) وأنّ `optionId` يبدأ بـ `dropdownItem.` (من 15 إلى 27 حرفًا).
`400 INVALID_ARGUMENT`	عدد الخيارات خارج الحدود.	يجب أن يحتوي تعريف القائمة المنسدلة على ما بين خيارَين و50 خيارًا.
`400 INVALID_ARGUMENT`	العنوان أو قيمة العرض فارغ أو يتجاوز 200 حرف.	يُرجى تقديم سلسلة غير فارغة تتراوح بين حرف واحد و200 حرف.
`400 INVALID_ARGUMENT`	سمة نمط النص غير متوافقة في الخيار.	يُسمح فقط بالقيمتَين `foregroundColor` و`backgroundColor` في خيارات القائمة المنسدلة. إزالة الخط أو الحجم أو السمات الأخرى
`400 INVALID_ARGUMENT`	عدم توفّر عملية ربط بديلة للخيار المحذوف	عند حذف خيار محدّد بواسطة أي شريحة، يجب تقديم بديل صالح في `selectedOptionIdReplacements`.
`400 INVALID_ARGUMENT`	محاولة حذف تعريف مستخدَم	احذف أو استهدِف جميع مثيلات شريحة القائمة المنسدلة التي تشير إلى التعريف قبل حذفه.
`400 INVALID_ARGUMENT`	المعرّف المقدَّم من المستخدِم مكرّر.	تأكَّد من أنّ أرقام التعريف المقدَّمة من المستخدِم فريدة ضمن علامة تبويب المستند.

العمل باستخدام شرائح القوائم المنسدلة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

ما هي شرائح القوائم المنسدلة؟

الهندسة المعمارية: التعريفات والأمثلة

قواعد التحقّق من صحة تنسيق المعرّف

إنشاء أرقام تعريف مقدَّمة من المستخدم

Python

جافا

إنشاء شرائح القوائم المنسدلة وإدراجها

إنشاء دفعة واحدة (يُوصى به)

Python

جافا

قواعد التحقّق من صحة القوائم المنسدلة وحدودها

تعديل اختيار شريحة قائمة منسدلة فردية

Python

جافا

تعديل تعريفات القائمة المنسدلة وخياراتها

استبدال القائمة الكاملة للخيارات

التكامل المرجعي واستبدال الخيار

Python

جافا

حذف تعريف قائمة منسدلة

Python

جافا

معالجة الأخطاء وتحديد المشاكل وحلّها

المواضيع ذات الصلة

العمل باستخدام شرائح القوائم المنسدلة