با لیست ها کار کنید، با لیست ها کار کنید

رابط برنامه‌نویسی کاربردی گوگل داکس از ایجاد فهرست در اسناد جدید، تبدیل پاراگراف‌های ساده موجود به فهرست‌های نشانه‌گذاری‌شده و حذف نشانه‌گذاری‌ها از پاراگراف‌ها پشتیبانی می‌کند.

ایجاد لیست شماره گذاری شده در سند جدید

API اسناد از ایجاد یک لیست شماره‌گذاری شده در یک سند جدید با وارد کردن متن و سپس اعمال سبک لیست به متن در یک درخواست دسته‌ای واحد پشتیبانی می‌کند.

برای ایجاد یک لیست شماره گذاری شده در یک سند جدید:

1. برای ایجاد یک سند از متد documents.create استفاده کنید.

2. از متد documents.batchUpdate استفاده کنید و یک InsertTextRequest برای افزودن محتوا به سند ارائه دهید. از کاراکترهای خط جدید ( \n ) برای جدا کردن موارد لیست استفاده کنید.

3. در همان به‌روزرسانی دسته‌ای، یک CreateParagraphBulletsRequest ، یک Range برای مشخص کردن محدوده متن و یک BulletGlyphPreset برای تنظیم الگوی شماره‌گذاری اضافه کنید.

نمونه کد زیر نحوه ایجاد یک سند و سپس درج سه مورد به عنوان یک لیست شماره‌گذاری شده را نشان می‌دهد. BulletGlyphPreset از NUMBERED_DECIMAL_ALPHA_ROMAN برای قالب‌بندی لیست استفاده می‌کند. این بدان معناست که سه سطح تودرتوی اول لیست شماره‌گذاری شده با یک عدد اعشاری، یک حرف کوچک و یک عدد رومی کوچک نمایش داده می‌شوند.

جاوا

Document doc = new Document().setTitle("New List Document");
doc = docsService.documents().create(doc).execute();
String documentId = doc.getDocumentId();

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item 1\nItem 2\nItem 3\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(22)
                        .setTabId(TAB_ID))
                .setBulletPreset("NUMBERED_DECIMAL_ALPHA_ROMAN")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
docsService.documents().batchUpdate(documentId, body).execute();

System.out.println("Created document with ID: " + documentId);

پایتون

title = 'New List Document'
body = {'title': title}
doc = service.documents().create(body=body).execute()
document_id = doc.get('documentId')

requests = [
    {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item 1\nItem 2\nItem 3\n'
        }
    },
    {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex': 22,
                'tabId': TAB_ID
            },
            'bulletPreset': 'NUMBERED_DECIMAL_ALPHA_ROMAN'
        }
    }
]

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

print(f"Created document with ID: {document_id}")

به جای TAB_ID، شناسه‌ی برگه‌ای که محتوای لیست در آن قرار دارد را وارد کنید.

تبدیل پاراگراف به لیست

یک عملیات قالب‌بندی پاراگراف رایج، تبدیل پاراگراف‌های موجود به یک لیست بولت‌دار است.

برای ایجاد یک لیست، از متد documents.batchUpdate استفاده کنید و یک CreateParagraphBulletsRequest ارائه دهید. یک Range برای مشخص کردن متن تحت تأثیر و یک BulletGlyphPreset برای تنظیم الگو برای گلوله اضافه کنید.

تمام پاراگراف‌هایی که با محدوده‌ی داده شده همپوشانی دارند، علامت‌گذاری می‌شوند. اگر محدوده‌ی مشخص شده با یک جدول همپوشانی داشته باشد، علامت‌گذاری‌ها درون سلول‌های جدول اعمال می‌شوند. سطح تودرتوی هر پاراگراف با شمارش تب‌های ابتدای هر پاراگراف تعیین می‌شود.

شما نمی‌توانید سطح تودرتوی یک بولت موجود را تنظیم کنید. در عوض، باید بولت را حذف کنید، زبانه‌های اصلی را در جلوی پاراگراف تنظیم کنید و سپس دوباره بولت را ایجاد کنید. برای اطلاعات بیشتر، به حذف بولت‌ها از لیست مراجعه کنید.

همچنین می‌توانید CreateParagraphBulletsRequest برای تغییر سبک گلوله برای یک لیست موجود استفاده کنید.

نمونه کد زیر یک درخواست دسته‌ای را نشان می‌دهد که ابتدا متن را در ابتدای سند وارد می‌کند و سپس لیستی از پاراگراف‌ها که شامل ۵۰ کاراکتر اول است، ایجاد می‌کند. BulletGlyphPreset از BULLET_ARROW_DIAMOND_DISC استفاده می‌کند، به این معنی که سه سطح تودرتوی اول لیست گلوله‌ای با یک فلش، یک لوزی و یک دیسک نمایش داده می‌شوند.

جاوا

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item One\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))
                .setBulletPreset("BULLET_ARROW_DIAMOND_DISC")));

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

پایتون

requests = [
        {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item One\n',
        }}, {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
            'bulletPreset': 'BULLET_ARROW_DIAMOND_DISC',
        }
    }
]

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

به جای TAB_ID، شناسه‌ی برگه‌ای که محتوای لیست در آن قرار دارد را وارد کنید، یا آن را حذف کنید تا به طور پیش‌فرض روی اولین برگه در سند قرار گیرد.

شکل ۱. تبدیل یک پاراگراف به یک لیست.

حذف بولت‌ها از یک لیست

برای حذف بولت‌ها از لیست پاراگراف، از متد documents.batchUpdate استفاده کنید و یک DeleteParagraphBulletsRequest ارائه دهید. یک Range برای مشخص کردن متن تحت تأثیر قرار گرفته وارد کنید.

این روش تمام بولت‌هایی را که با محدوده داده شده همپوشانی دارند، صرف نظر از سطح تودرتو، حذف می‌کند. برای حفظ بصری سطح تودرتو، به ابتدای هر پاراگراف مربوطه تورفتگی اضافه می‌شود.

نمونه کد زیر یک درخواست دسته‌ای را نشان می‌دهد که بولت‌ها را از لیست پاراگراف حذف می‌کند.

جاوا

List<Request> requests = new ArrayList<>();
requests.add(new Request().setDeleteParagraphBullets(
        new DeleteParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))));

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

پایتون

requests = [
        {
        'deleteParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
        }
    }
]

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

به جای TAB_ID، شناسه‌ی برگه‌ای که محتوای لیست در آن قرار دارد را وارد کنید، یا آن را حذف کنید تا به طور پیش‌فرض روی اولین برگه در سند قرار گیرد.