تتيح لك Google Sheets API إضافة الصفوف والأعمدة وإزالتها ومعالجتها في جداول البيانات. توضّح الأمثلة الواردة في هذه الصفحة كيفية تنفيذ بعض العمليات الشائعة على الصفوف والأعمدة باستخدام واجهة برمجة التطبيقات Sheets API.
يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون متعافِية من اللغة. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على مقالة تعديل جداول بيانات Google.
في هذين المثالَين، تشير العنصران النائبان SPREADSHEET_ID وSHEET_ID
إلى المكان الذي يجب فيه تقديم معرّفات التطبيقَين. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على
معرّف جدول البيانات باستخدام الأسلوب
spreadsheets.get. يتم تحديد النطاقات
باستخدام ترميز A1. أحد مثالي النطاق هو الورقة1!A1:D5.
تعديل عرض العمود أو ارتفاع الصف
يوضّح نموذج الرمز التالي
spreadsheets.batchUpdate
كيفية استخدام الرمز
UpdateDimensionPropertiesRequest
لتعديل سمة العرض للعمود "أ" إلى 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 ما إذا كانت العملية تنطبق على الأعمدة أو
الصفوف في ورقة البيانات.
إذا كان الحقل inheritFromBefore صحيحًا، يطلب من واجهة برمجة التطبيقات Sheets API منح
الأعمدة أو الصفوف الجديدة السمات نفسها التي يمتلكها الصف أو العمود السابقان، وإذا كان الحقل
خطأ، يتم اكتساب السمات من السمات التي تلي الأعمدة أو الصفوف الجديدة.
لا يمكن أن تكون inheritFromBefore صحيحة في حال إدراج صف في الصف 1 أو عمود في عمود "أ".
يظهر بروتوكول الطلب أدناه.
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
لنقل العمود "أ" إلى موضع العمود "د". ينقل طلب ثانٍ الصفوف
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
}
},
],
}