تنسيق النص

توضّح لك هذه الصفحة كيفية تنسيق النص باستخدام Google Docs API.

لمحة عن التنسيق

هناك نوعان مختلفان من التنسيق يمكنك تطبيقهما على محتوى النص في مستندك:

  • يمكنك تغيير تنسيق الأحرف، مثل الخط أو اللون أو التسطير.
  • يمكنك تغيير تنسيق الفقرة، مثل المسافة البادئة أو تباعد الأسطر.

تغيير تنسيق الأحرف

يحدّد تنسيق الأحرف طريقة عرض أحرف النص في مستندك.

يؤدي أي تنسيق تطبّقه إلى إلغاء التنسيق التلقائي الموروث من TextStyle للفقرة الأساسية. في المقابل، تواصل أي أحرف لم يتم ضبط تنسيقها اكتساب التنسيق من أنماط الفقرة.

لتغيير تنسيق الأحرف في النص، استخدِم batchUpdate مع UpdateTextStyleRequest. عليك تقديم عنصر نطاق يتضمّن المعلومات التالية:

  • تمثّل هذه السمة segmentId الجزء الذي يحتوي على النص، سواء كان رأسًا أو تذييلاً أو حاشية سفلية، أو النص الأساسي إذا لم يتم تحديد أي جزء.
  • الرمزين startIndex وendIndex اللذين يحددان نطاق النص ضمن المقطع المراد تنسيقه.
  • تمثّل tabId علامة تحدّد علامة التبويب التي تحتوي على النص.

ينفّذ المثال التالي عدة عمليات لتنسيق النص المضمّن في العنوان:

  • يضبط خط الأحرف من 1 إلى 5 على خط مائل غامق.
  • يضبط لون الأحرف من 6 إلى 10 على blue خط Times New Roman بحجم 14 نقطة.
  • ربط الأحرف من 11 إلى 15 في الرابط التشعّبي بـ www.example.com

يمكن إجراء ذلك بطريقة مباشرة من خلال إنشاء قائمة بالطلبات ثم استخدام طلب batchUpdate واحد:

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setUpdateTextStyle(new UpdateTextStyleRequest()
        .setTextStyle(new TextStyle()
                .setBold(true)
                .setItalic(true))
        .setRange(new Range()
                .setStartIndex(1)
                .setEndIndex(5)
                .setTabId(TAB_ID))
        .setFields("bold")));

requests.add(new Request()
        .setUpdateTextStyle(new UpdateTextStyleRequest()
                .setRange(new Range()
                        .setStartIndex(6)
                        .setEndIndex(10)
                        .setTabId(TAB_ID))
                .setTextStyle(new TextStyle()
                        .setWeightedFontFamily(new WeightedFontFamily()
                                .setFontFamily("Times New Roman"))
                        .setFontSize(new Dimension()
                                .setMagnitude(14.0)
                                .setUnit("PT"))
                        .setForegroundColor(new OptionalColor()
                                .setColor(new Color().setRgbColor(new RgbColor()
                                        .setBlue(1.0F)
                                        .setGreen(0.0F)
                                        .setRed(0.0F)))))
                .setFields("foregroundColor,weightedFontFamily,fontSize")));

requests.add(new Request()
        .setUpdateTextStyle(new UpdateTextStyleRequest()
                .setRange(new Range()
                        .setStartIndex(11)
                        .setEndIndex(15)
                        .setTabId(TAB_ID))
                .setTextStyle(new TextStyle()
                        .setLink(new Link()
                                .setUrl("www.example.com")))
                .setFields("link")));


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

Python

requests = [
    {
        'updateTextStyle': {
            'range': {
                'startIndex': 1,
                'endIndex': 5,
                'tabId': TAB_ID
            },
            'textStyle': {
                'bold': True,
                'italic': True
            },
            'fields': 'bold,italic'
        }
    },
    {
        'updateTextStyle': {
            'range': {
                'startIndex': 6,
                'endIndex': 10,
                'tabId': TAB_ID
            },
            'textStyle': {
                'weightedFontFamily': {
                    'fontFamily': 'Times New Roman'
                },
                'fontSize': {
                    'magnitude': 14,
                    'unit': 'PT'
                },
                'foregroundColor': {
                    'color': {
                        'rgbColor': {
                            'blue': 1.0,
                            'green': 0.0,
                            'red': 0.0
                        }
                    }
                }
            },
            'fields': 'foregroundColor,weightedFontFamily,fontSize'
        }
    },
    {
        'updateTextStyle': {
            'range': {
                'startIndex': 11,
                'endIndex': 15,
                'tabId': TAB_ID
            },
            'textStyle': {
                'link': {
                    'url': 'www.example.com'
                }
            },
            'fields': 'link'
        }
    }
]

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

تغيير تنسيق الفقرة

تتيح لك Google Docs API تعديل تنسيق الفقرات، ما يحدّد طريقة عرض كتل النص في مستندك، بما في ذلك ميزات مثل المحاذاة والمسافة البادئة.

أي تنسيق تطبّقه يلغي التنسيق التلقائي الموروث من نمط الفقرة الأساسي. في المقابل، تستمر أي ميزات تنسيق لم يتم ضبطها في الوراثة من نمط الفقرة. لمزيد من المعلومات حول أنماط الفقرات والتوريث، يمكنك الاطّلاع على ParagraphStyle.

يحدّد المثال أدناه التنسيق التالي لفقرة:

  • عنوان كنمط مسمّى
  • تباعد مخصّص أعلاه
  • تباعد مخصّص أدناه
  • حدّ أيسر مخصّص

تستمر جميع ميزات التنسيق الأخرى للفقرة في الوراثة من النمط المسمّى الأساسي.

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setUpdateParagraphStyle(new UpdateParagraphStyleRequest()
        .setRange(new Range()
                .setStartIndex(1)
                .setEndIndex(10)
                .setTabId(TAB_ID))
        .setParagraphStyle(new ParagraphStyle()
                .setNamedStyleType("HEADING_1")
                .setSpaceAbove(new Dimension()
                        .setMagnitude(10.0)
                        .setUnit("PT"))
                .setSpaceBelow(new Dimension()
                        .setMagnitude(10.0)
                        .setUnit("PT")))
        .setFields("namedStyleType,spaceAbove,spaceBelow")
));

requests.add(new Request().setUpdateParagraphStyle(new UpdateParagraphStyleRequest()
        .setRange(new Range()
                .setStartIndex(10)
                .setEndIndex(20)
                .setTabId(TAB_ID))
        .setParagraphStyle(new ParagraphStyle()
                .setBorderLeft(new ParagraphBorder()
                        .setColor(new OptionalColor()
                                .setColor(new Color()
                                        .setRgbColor(new RgbColor()
                                                .setBlue(1.0F)
                                                .setGreen(0.0F)
                                                .setRed(0.0F)
                                        )
                                )
                        )
                        .setDashStyle("DASH")
                        .setPadding(new Dimension()
                                .setMagnitude(20.0)
                                .setUnit("PT"))
                        .setWidth(new Dimension()
                                .setMagnitude(15.0)
                                .setUnit("PT")
                        )
                )
        )
        .setFields("borderLeft")
));

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

Python

requests = [
    {
        'updateParagraphStyle': {
            'range': {
                'startIndex': 1,
                'endIndex':  10,
                'tabId': TAB_ID
            },
            'paragraphStyle': {
                'namedStyleType': 'HEADING_1',
                'spaceAbove': {
                    'magnitude': 10.0,
                    'unit': 'PT'
                },
                'spaceBelow': {
                    'magnitude': 10.0,
                    'unit': 'PT'
                }
            },
            'fields': 'namedStyleType,spaceAbove,spaceBelow'
        }
    },
    {
        'updateParagraphStyle': {
            'range': {
                'startIndex': 10,
                'endIndex':  20,
                'tabId': TAB_ID
            },
            'paragraphStyle': {
                'borderLeft': {
                    'color': {
                        'color': {
                            'rgbColor': {
                                'blue': 1.0,
                                'green': 0.0,
                                'red': 0.0
                            }
                        }
                    },
                    'dashStyle': 'DASH',
                    'padding': {
                        'magnitude': 20.0,
                        'unit': 'PT'
                    },
                    'width': {
                        'magnitude': 15.0,
                        'unit': 'PT'
                    },
                }
            },
            'fields': 'borderLeft'
        }
    }
]

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