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

تتيح لك واجهة 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 notation. مثال على نطاق: Sheet1!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,
}

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

يُرجى العِلم أنّ "صواب" في المنتصف وهي قيمة منطقية، بينما "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,
  }
}

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