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

تتيح لك واجهة 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,
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزّن	تاريخ الشحن
2	العجلة	$20.50	4	2016/3/1
3	باب	$15	2	2016/3/15
4	المحرّك	$100	1	2016/3/20
5	مجاميع	$135.5	7	2016/3/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,
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزّن	تاريخ الشحن
2	العجلة	$1,00	4	2016/4/1
3	باب	2 دولار أميركي (أو ما يعادلهما بالعملة المحلية)	2	4/15/2016
4	المحرّك		1
5	مجاميع	$3,00	7	4/15/2016

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

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

بدءًا من ورقة فارغة، يوضّح نموذج الرمز التالي 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,
    }
  ],
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزّن	تاريخ الشحن
2	العجلة	$20.50	4	2016/3/1
3	باب
4	المحرّك
5

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

بدءًا من ورقة فارغة، يوضّح نموذج الرمز التالي 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,
}

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

	A	ب	C	D	E
1	البيانات	123.45	صواب	=MAX(D2:D4)	10
2

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

إلحاق القيم

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزّن	تاريخ الشحن
2	العجلة	$20.50	4	2016/3/1
3

يوضّح نموذج الرمز البرمجي 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,
  }
}

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

	A	ب	C	D
1	المنتج/الخدمة	التكلفة	مخزّن	تاريخ الشحن
2	العجلة	$20.50	4	2016/3/1
3	باب	$15	2	2016/3/15
4	المحرّك	$100	1	2016/3/20
5