تتيح لك Google Sheets API إضافة الصفوف والأعمدة في الأوراق وإزالتها ومعالجتها. توضح الأمثلة في هذه الصفحة كيف يمكن تحقيق بعض عمليات الصفوف والأعمدة الشائعة باستخدام Sheets API.
يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون محايدة اللغة. لمعرفة كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج واجهة Google API، يمكنك الاطّلاع على مقالة تحديث جداول البيانات.
في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID
إلى مكان تقديم هذين المعرّفَين. يمكنك العثور على رقم تعريف
جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف ورقة البيانات باستخدام الطريقة spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. مثال على النطاق
Sheet1!A1:D5.
ضبط عرض العمود أو ارتفاع الصف
يوضّح نموذج الرمز البرمجي
spreadsheets.batchUpdate التالي كيفية استخدام
UpdateDimensionPropertiesRequest
لتعديل سمة عرض العمود A إلى 160 بكسل. يقوم الطلب الثاني بتحديث خاصية ارتفاع
الصف للصفوف الثلاثة الأولى ليكون 40 بكسل. ويحدِّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة أو صفوف ورقة البيانات.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateDimensionProperties": {
"range": {
"sheetId": SHEET_ID,
"dimension": "COLUMNS",
"startIndex": 0,
"endIndex": 1
},
"properties": {
"pixelSize": 160
},
"fields": "pixelSize"
}
},
{
"updateDimensionProperties": {
"range": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 0,
"endIndex": 3
},
"properties": {
"pixelSize": 40
},
"fields": "pixelSize"
}
}
]
}
إلحاق صفوف أو أعمدة فارغة
يوضّح نموذج الرمز البرمجي
spreadsheets.batchUpdate التالي كيفية استخدام
AppendDimensionRequest
لإلحاق الصفوف والأعمدة. يُلحِق الطلب الأول ثلاثة صفوف فارغة بنهاية الورقة، بينما يلحق الطلب الثاني عمودًا واحدًا فارغًا. ويحدِّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة أو صفوف ورقة البيانات.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"appendDimension": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"length": 3
}
},
{
"appendDimension": {
"sheetId": SHEET_ID,
"dimension": "COLUMNS",
"length": 1
}
}
]
}
تغيير حجم العمود تلقائيًا
يوضح نموذج الرمز البرمجي
spreadsheets.batchUpdate التالي كيفية استخدام
AutoResizeDimensionsRequest
لتغيير حجم الأعمدة A:C، بناءً على حجم محتوى العمود. يشير الحقل dimension إلى أنّ العملية تنطبق على أعمدة الورقة.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"autoResizeDimensions": {
"dimensions": {
"sheetId": SHEET_ID,
"dimension": "COLUMNS",
"startIndex": 0,
"endIndex": 3
}
}
}
]
}
تغيير حجم الصف تلقائيًا
يوضّح نموذج الرمز البرمجي
spreadsheets.batchUpdate التالي كيفية استخدام
AutoResizeDimensionsRequest
لمحو ارتفاعات الصفوف في أوّل ثلاثة صفوف. ثم تكبر ارتفاعات الصفوف ديناميكيًا
بناءً على محتوى الخلايا في كل صف. يشير الحقل dimension إلى أنّ العملية تنطبق على صفوف ورقة البيانات.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"autoResizeDimensions": {
"dimensions": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 0,
"endIndex": 3
}
}
}
]
}
حذف الصفوف أو الأعمدة
يوضّح نموذج الرمز البرمجي
spreadsheets.batchUpdate التالي كيفية استخدام
DeleteDimensionRequest
لحذف الصفوف الثلاثة الأولى من ورقة بيانات. الطلب الثاني يحذف الأعمدة B:D.
ويحدِّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة
ورقة البيانات أو صفوفها.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 0,
"endIndex": 3
}
}
},
{
"deleteDimension": {
"range": {
"sheetId": SHEET_ID,
"dimension": "COLUMNS",
"startIndex": 1,
"endIndex": 4
}
}
},
],
}
إدراج صف أو عمود فارغ
يوضّح نموذج الرمز البرمجي
spreadsheets.batchUpdate التالي كيفية استخدام
InsertDimensionRequest
لإدراج أعمدة أو صفوف في فهرس معيّن (مثل إضافة الصفوف الفارغة في أعلى ورقة البيانات). يقوم الطلب الأول بإدراج عمودين فارغين في العمود C.
بينما يُدرج الطلب الثاني ثلاثة صفوف فارغة تبدأ من الصف 1.
ويحدِّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة
ورقة البيانات أو صفوفها.
في حال اختيار القيمة "true"، يخبر الحقل inheritFromBefore واجهة برمجة التطبيقات لـ Sheets API بمنح الأعمدة أو الصفوف الجديدة الخصائص نفسها الواردة في الصف أو العمود السابق. أمّا إذا كانت القيمة "false"، فسيتم اكتسابها من السمات بعد الأعمدة أو الصفوف الجديدة.
لا يمكن أن يكون inheritFromBefore صحيحًا إذا تم إدراج صف في الصف 1 أو عمود في
العمود A.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"insertDimension": {
"range": {
"sheetId": SHEET_ID,
"dimension": "COLUMNS",
"startIndex": 2,
"endIndex": 4
},
"inheritFromBefore": true
}
},
{
"insertDimension": {
"range": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 0,
"endIndex": 3
},
"inheritFromBefore": false
}
},
],
}
نقل صف أو عمود
يوضّح نموذج الرمز البرمجي
spreadsheets.batchUpdate التالي كيفية استخدام
MoveDimensionRequest
لنقل العمود A إلى الموضع D. ينقل الطلب الثاني الصفوف من
5 إلى 10 إلى موضع الصف 20.
ويحدِّد الحقل dimension ما إذا كانت العملية تنطبق على أعمدة
ورقة البيانات أو صفوفها. ويحدِّد الحقل destinationIndex مكان نقل بيانات المصدر باستخدام فهرس بداية يستند إلى صفر.
في ما يلي بروتوكول الطلب.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"moveDimension": {
"source": {
"sheetId": SHEET_ID,
"dimension": "COLUMNS",
"startIndex": 0,
"endIndex": 1
},
"destinationIndex": 3
}
},
{
"moveDimension": {
"source": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 4,
"endIndex": 10
},
"destinationIndex": 19
}
},
],
}