الكتابة الأساسية

تتيح لك واجهة Google Sheets API كتابة القيم والصيغ في الخلايا والنطاقات ومجموعات النطاقات والجداول بأكملها. توضّح الأمثلة الواردة في هذه الصفحة كيفية تنفيذ بعض عمليات الكتابة الشائعة باستخدام مورد spreadsheets.values في Sheets API.

يُرجى العِلم أنّه يمكن أيضًا كتابة قيم الخلايا باستخدام طريقة spreadsheet.batchUpdate، وهي طريقة مفيدة إذا أردت تعديل تنسيق الخلايا أو خصائص أخرى في الوقت نفسه، وهي خصائص لا يتأثر بها المرجع spreadsheets.values. على سبيل المثال، إذا أردت نسخ نطاق من الخلايا من ورقة إلى أخرى مع الكتابة فوق صيغة الخلية وتنسيقها، يمكنك استخدام طريقة UpdateCellsRequest مع spreadsheet.batchUpdate.

ومع ذلك، لتسهيل عملية كتابة القيم البسيطة، يمكنك استخدام الطريقتَين spreadsheets.values.update أو spreadsheets.values.batchUpdate.

يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون محايدة من حيث اللغة. للتعرّف على كيفية تنفيذ عمليات الكتابة بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على قراءة قيم الخلايا وكتابتها.

في هذه الأمثلة، يشير العنصر النائب SPREADSHEET_ID إلى المكان الذي ستوفّر فيه رقم تعريف جدول البيانات، ويمكنك العثور عليه من عنوان URL الخاص بجدول البيانات. يتم تحديد النطاقات التي سيتم الكتابة فيها باستخدام ترميز A1. مثال على نطاق: الورقة1!A1:D5

كتابة نطاق واحد

بدءًا من جدول بيانات جديد فارغ، يوضّح نموذج الرمز التالي spreadsheets.values.update كيفية كتابة القيم في نطاق. مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (على سبيل المثال، ما إذا كان سيتم تحويل سلسلة إلى تاريخ أم لا).

يتضمّن نص الطلب الكائن ValueRange الذي يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم قيم منظَّمة حسب الصفوف. يتم استبدال القيم الحالية في النطاق المستهدف.

يظهر بروتوكول الطلب أدناه.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

تتألف الاستجابة من عنصر UpdateValuesResponse، مثل هذا العنصر:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

يبدو جدول البيانات الناتج على النحو التالي:

الكتابة بشكل انتقائي في نطاق

عند كتابة قيم في نطاق، من الممكن تجنُّب تغيير بعض الخلايا الحالية من خلال ضبط عناصر المصفوفة المقابلة على null. يمكن أيضًا محو محتوى خلية من خلال كتابة سلسلة فارغة ("") فيها.

بدءًا من ورقة تتضمّن البيانات نفسها التي تم إنتاجها بواسطة المثال أعلاه، يوضّح نموذج الرمز التالي spreadsheets.values.update كيفية كتابة القيم في النطاق B1:D4، مع ترك بعض الخلايا بدون تغيير ومحو البعض الآخر بشكل انتقائي. مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (على سبيل المثال، ما إذا كان سيتم تحويل سلسلة إلى تاريخ أم لا).

يتضمّن نص الطلب الكائن ValueRange الذي يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم قيم منظَّمة حسب العمود.

يظهر بروتوكول الطلب أدناه.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

يسرد الحقل values هنا التغييرات التي تم إجراؤها على كل عمود في النطاق. تشير المصفوفة الأولى إلى أنّه يجب ترك الخلية B1 بدون تغيير (بسبب العنصر null في المصفوفة)، بينما يجب محو الخلية B4 (سلسلة فارغة). يتم تعديل قيمتَي الخليتين B2 وB3. تُجري المصفوفة الثالثة العمليات نفسها على العمود D، بينما تشير المصفوفة الفارغة الثانية إلى أنّه يجب ترك العمود C بدون تغيير.

تتألف الاستجابة من عنصر UpdateValuesResponse مثل العنصر التالي:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

يبدو جدول البيانات الناتج على النحو التالي:

يُرجى العِلم أنّ صف "المجموعات"، على الرغم من أنّه لم يتم تغييره مباشرةً من خلال هذا الطلب، يتغيّر لأنّ خلاياه تحتوي على صيغ تعتمد على الخلايا التي تم تغييرها.

الكتابة في نطاقات متعددة

بدءًا من ورقة فارغة، يوضّح نموذج الرمز التالي spreadsheets.values.batchUpdate كيفية كتابة القيم في النطاقات Sheet1!A1:A4 و Sheet1!B1:D2. يتم استبدال القيم الحالية في النطاق المستهدف. يتألف نص الطلب من عنصر ValueInputOption يوضّح كيفية تفسير بيانات الإدخال ومصفوفة من عناصر ValueRange تتوافق مع كل نطاق مكتوب. يحدّد الحقل majorDimension ما إذا كان سيتم تفسير المصفوفات المضمّنة على أنّها مصفوفات أعمدة أو صفوف.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

تتألّف الاستجابة من كائن يسرد إحصاءات الخلايا المعدَّلة ومصفوفة من كائنات UpdateValuesResponse، كائن واحد لكل نطاق معدَّل. على سبيل المثال:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

يبدو جدول البيانات الناتج على النحو التالي:

كتابة القيم بدون تحليل

بدءًا من ورقة فارغة، يوضّح نموذج الرمز التالي spreadsheets.values.update كيفية كتابة القيم في النطاق Sheet1!A1:E1، ولكنّه يستخدم معلَمة طلب البحث RAW ValueInputOption لمنع تحليل السلاسل المكتوبة على أنّها صِيغ أو قيم منطقية أو أرقام. تظهر هذه القيم كسلاسل نصية وتكون محاذاة النص مضبوطة في ورقة البيانات.

يتضمّن نص الطلب الكائن ValueRange الذي يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم قيم منظَّمة حسب الصفوف. يتم استبدال القيم الحالية في النطاق المستهدف.

يظهر بروتوكول الطلب أدناه.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

تتألف الاستجابة من عنصر UpdateValuesResponse مثل العنصر التالي:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

يبدو جدول البيانات الناتج على النحو التالي:

يُرجى العِلم أنّ القيمة "TRUE" تتوسّط الخلية وهي قيمة منطقية، بينما تتم محاذاة القيمة "123.45" إلى اليسار لأنّها رقم، وتتم محاذاة القيمة "10" إلى اليمين لأنّها سلسلة. لا يتم تحليل الصيغة، وتظهر أيضًا كسلسلة.

إلحاق القيم

ابدأ بورقة مثل الجدول أدناه:

يوضّح نموذج الرمز البرمجي spreadsheets.values.append التالي كيفية إضافة صفَّين جديدَين من القيم بدءًا من الصف 3. مَعلمة طلب البحث ValueInputOption مطلوبة وتحدّد ما إذا كان سيتم تحليل القيم المكتوبة (على سبيل المثال، ما إذا كان سيتم تحويل سلسلة إلى تاريخ أم لا).

يتضمّن نص الطلب الكائن ValueRange الذي يصف قيم النطاق المطلوب كتابتها. يشير الحقل majorDimension إلى أنّ المصفوفات هي قوائم قيم منظَّمة حسب الصفوف.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

تتألف الاستجابة من عنصر AppendValuesResponse مثل العنصر التالي:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

يبدو جدول البيانات الناتج على النحو التالي: