مرجع واجهة برمجة تطبيقات Google Visualization API

تسرد هذه الصفحة الكائنات التي تعرضها واجهة برمجة التطبيقات Google Visualization API والطرق القياسية التي تعرضها كل العروض المرئية.

ملاحظة: مساحة الاسم لواجهة Google Visualization API هي google.visualization.*.

فئة جدول البيانات

يمثل جدول قيم ثنائي الأبعاد قابل للتغيير. لإنشاء نسخة للقراءة فقط من DataTable (تتم فلترتها اختياريًا لعرض قيم أو صفوف أو أعمدة معيّنة)، أنشئ DataView.

يتم تخصيص نوع بيانات لكل عمود، بالإضافة إلى العديد من السمات الاختيارية، بما في ذلك المعرّف والتصنيف وسلسلة النمط.

بالإضافة إلى ذلك، يمكنك تحديد سمات مخصّصة (أزواج الاسم/القيمة) لأي خلية أو صف أو عمود أو الجدول بأكمله. تتيح بعض الرسومات البيانية استخدام سمات مخصّصة محدّدة، على سبيل المثال، يتيح التمثيل البصري للجدول استخدام خاصية خلية باسم "style" تتيح لك تحديد سلسلة نمط CSS مضمّنة لخلية الجدول المعروض. يجب أن يصف التمثيل البصري في مستنداته أي سمات مخصّصة متوافقة.

راجع أيضًا: QueryResponse.getDataTable

المنشئ

البنية

DataTable(opt_data, opt_version)

opt_data

[اختيارية] البيانات المستخدَمة لإعداد الجدول ويمكن أن يكون هذا إما ملف JSON الذي يتم عرضه من خلال استدعاء DataTable.toJSON() على جدول تمت تعبئته، أو كائن JavaScript يحتوي على بيانات تُستخدَم لإعداد الجدول. يمكنك الاطّلاع هنا على شرح لبنية كائن JavaScript الحرفي. في حال عدم توفير هذه المَعلمة، سيتم عرض جدول بيانات جديد وفارغ.

opt_version

[اختيارية] قيمة رقمية تحدّد نسخة بروتوكول النقل السلكي المستخدَم. ولا يتم استخدام ذلك إلا من خلال جهات تنفيذ مصدر البيانات لأدوات الرسوم البيانية. الإصدار الحالي هو 0.6.

التفاصيل

يُستخدَم الكائن DataTable للاحتفاظ بالبيانات التي يتم نقلها إلى العرض المرئي. الجدول DataTable هو جدول أساسي ثنائي الأبعاد. يجب أن تحتوي جميع البيانات في كل عمود على نوع البيانات نفسه. ويحتوي كل عمود على واصف يتضمّن نوع بياناته وتصنيفًا لذلك العمود (الذي يمكن عرضه من خلال التمثيل البصري) ورقم تعريف يمكن استخدامه للإشارة إلى عمود معيّن (كبديل لاستخدام فهارس الأعمدة). يتيح الكائن DataTable أيضًا خريطة للسمات العشوائية المخصّصة لقيمة معيّنة أو صف أو عمود أو DataTable بالكامل. يمكن للتمثيل البصري استخدام هذه العناصر لإتاحة ميزات إضافية، على سبيل المثال، يستخدم التمثيل البصري للجدول سمات مخصّصة للسماح لك بتحديد أسماء فئات أو أنماط عشوائية للخلايا الفردية.

ولكل خلية في الجدول قيمة. يمكن أن تحتوي الخلايا على قيمة فارغة أو على قيمة من النوع المحدد في العمود. يمكن للخلايا بشكل اختياري أن تأخذ نسخة "منسقة" من البيانات، وهي إصدار سلسلة من البيانات تم تنسيقه لعرضه من خلال التمثيل البصري. يمكن للتمثيل البصري (ولكن ليس إلزاميًا) أن يستخدم النسخة المنسَّقة للعرض، ولكنّه سيستخدم دائمًا البيانات نفسها في أي عمليات ترتيب أو عمليات حسابية يتم إجراؤها (مثل تحديد مكان وضع نقطة على الرسم البياني). ومن الأمثلة على ذلك تخصيص القيم "منخفضة" و"متوسطة" و "مرتفعة" كقيم منسَّقة للقيم الرقمية للخلايا 1 و2 و3.

لإضافة صفوف بيانات بعد استدعاء الدالة الإنشائية، يمكنك استدعاء إما addRow() لصف واحد، أو addRows() لصفوف متعددة. يمكنك إضافة أعمدة أيضًا من خلال استدعاء طرق addColumn(). وتتوفّر طرق إزالة للصفوف والأعمدة أيضًا، ولكن بدلاً من إزالة الصفوف أو الأعمدة، ننصحك بإنشاء DataView تمثّل طريقة عرض انتقائية لـ DataTable.

إذا غيّرت القيم في DataTable بعد تمريرها إلى طريقة draw() في العرض المرئي، لن تؤدي التغييرات إلى تغيير الرسم البياني فورًا. يجب طلب draw() مرة أخرى لإظهار أي تغييرات.

ملاحظة: لا تُجري "مخططات Google" أي تحقق على جداول البيانات. (إذا كان الأمر كذلك، فسيكون عرض المخططات أبطأ). إذا قدمت رقمًا يتوقع فيه العمود سلسلة، أو العكس، ستبذل مخططات Google أفضل مستواها لتفسير القيمة بطريقة منطقية، ولكنها لن تضع علامة على الأخطاء.

يوضّح المثال التالي إنشاء مثيل DataTable وتعبئته بسلسلة حرفية، باستخدام البيانات نفسها كما هو موضّح في مثال JavaScript أعلاه:

var dt = new google.visualization.DataTable({
    cols: [{id: 'task', label: 'Task', type: 'string'},
           {id: 'hours', label: 'Hours per Day', type: 'number'}],
    rows: [{c:[{v: 'Work'}, {v: 11}]},
           {c:[{v: 'Eat'}, {v: 2}]},
           {c:[{v: 'Commute'}, {v: 2}]},
           {c:[{v: 'Watch TV'}, {v:2}]},
           {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}]
    }, 0.6);

ينشئ المثال التالي DataTable جديدًا فارغًا ثم تتم تعبئته يدويًا بالبيانات نفسها الواردة أعلاه:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);

الطُرق

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}
]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.

data.addRows([
  ['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null] // No date set for Bob.
]);

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}

{"cols":[{"id":"Col1","label":"","type":"date"}],
 "rows":[
   {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]},
   {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]}
 ]
}

تنسيق معلَمة البيانات الحرفية لـ JavaScript للمنشئ

يمكنك إعداد DataTable من خلال إدخال كائن حرفي لسلسلة JavaScript إلى مَعلمة data. نُطلق على هذا الكائن اسم الكائن data. ويمكنك ترميز هذا العنصر يدويًّا وفقًا للوصف أدناه، أو يمكنك استخدام مكتبة Python المساعدة إذا كنت تعرف كيفية استخدام Python وكان موقعك الإلكتروني قادرًا على استخدامها. إذا كنت تريد إنشاء العنصر يدويًا، سيصف هذا القسم البنية.

أولاً، إليك مثال على كائن JavaScript بسيط يصف جدولاً مؤلفًا من ثلاثة صفوف وثلاثة أعمدة (أنواع السلسلة والرقم والتاريخ):

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ],
  p: {foo: 'hello', bar: 'world!'}
}

دعنا الآن نصف بناء الجملة:

يتألف عنصر data من سمتَين مطلوبتَين من المستوى الأعلى، وهما cols وrows، وسمة p اختيارية تعرض قيمًا عشوائية.

ملاحظة: جميع أسماء السمات وثبات السلسلة المعروضة حسّاسة لحالة الأحرف. ويجب أيضًا وضع قيمتها بين علامتَي اقتباس، وذلك في السمات التي يتم وصفها باعتبارها قيمة سلسلة. على سبيل المثال، إذا أردت تحديد السمة type على أنّها رقم، سيتم التعبير عنها على النحو التالي: type: 'number'، بينما سيتم التعبير عن القيمة نفسها باعتبارها رقمية على النحو التالي: v: 42

الموقع الإلكتروني "cols"

cols هي مصفوفة من العناصر التي تصف رقم التعريف ونوع كل عمود. كل سمة هي كائن له السمات التالية (حساسة لحالة الأحرف):

• type [مطلوبة] نوع البيانات الواردة في العمود ويمكن استخدام قيم السلسلة التالية (تشمل الأمثلة السمة v: ، كما هو موضّح لاحقًا):
  • "منطقي" - قيمة منطقية JavaScript ("صحيح" أو "خطأ"). مثال على القيمة: v:'true'
  • "number" - قيمة رقم JavaScript أمثلة على القيم: v:7 ، v:3.14، v:-55
  • "string" - قيمة سلسلة JavaScript مثال على القيمة: v:'hello'
  • "date" - كائن "تاريخ JavaScript" (شهر يستند إلى صفر)، مع اقتطاع الوقت. مثال على القيمة: v:new Date(2008, 0, 15)
  • "datetime" - كائن "تاريخ JavaScript" بما في ذلك الوقت. مثال على القيمة: v:new Date(2008, 0, 15, 14, 30, 45)
  • "timeofday" - مصفوفة من ثلاثة أرقام ورقم رابع اختياري، يمثل الساعة (0 يشير إلى منتصف الليل) والدقيقة والثانية والملي ثانية الاختيارية. أمثلة على القيم: v:[8, 15, 0] وv: [6, 12, 1, 144]
• id [اختياري] رقم تعريف سلسلة للعمود يجب أن يكون فريدًا في الجدول. استخدِم الأحرف الأبجدية الرقمية الأساسية، كي لا تتطلب صفحة المضيف أي أحرف إنجليزية كبيرة للوصول إلى العمود في JavaScript. احرص على عدم اختيار كلمة رئيسية تستخدم JavaScript. مثال: id:'col_1'
• label [اختيارية] وهي قيمة سلسلة تعرضها بعض العروض المرئية لهذا العمود. مثال: label:'Height'
• pattern [اختياري] نمط سلسلة استخدمه مصدر بيانات لتنسيق القيم الرقمية أو النصية أو الزمنية هذه المعلومات هي كمرجع لك فقط، ولن تحتاج على الأرجح إلى قراءة النمط، وليس من الضروري أن تكون متوفّرة. لا يستخدم برنامج "التمثيل المرئي من Google" هذه القيمة (يقرأ القيمة المنسَّقة للخلية). إذا كانت السمة DataTable واردة من مصدر بيانات استجابةً لطلب بحث يتضمّن عبارة format، من المحتمل أن يتم عرض النمط الذي حدّدته في تلك العبارة في هذه القيمة. معيارا الأنماط المقترَحان هما ICU decimalFormat و SimpleDateFormat .
• p [اختياري] كائن عبارة عن خريطة للقيم المخصّصة التي يتم تطبيقها على الخلية. ويمكن أن تكون هذه القيم من أي نوع JavaScript. إذا كان التمثيل البصري يتيح أي سمات على مستوى الخلية، سيصفها. وبخلاف ذلك، سيتم تجاهل هذه السمة. مثال: p:{style: 'border: 1px solid green;'}.

مثال cols

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

rows الموقع

تحتوي السمة rows على مصفوفة من عناصر الصفوف.

يتضمّن كل عنصر صف سمة واحدة مطلوبة تُسمّى c، وهي مصفوفة من الخلايا في هذا الصف. ويتضمّن أيضًا السمة p الاختيارية التي تحدّد خريطة للقيم المخصّصة العشوائية لتخصيصها للصف بأكمله. إذا كان العرض المرئي يتيح استخدام أي سمات على مستوى الصف، سيصفها وإلّا، سيتم تجاهل هذه السمة.

كائنات الخلية

يتم وصف كل خلية في الجدول بواسطة كائن له الخصائص التالية:

• v [اختيارية] قيمة الخلية يجب أن يتطابق نوع البيانات مع نوع بيانات العمود. إذا كانت الخلية فارغة، يجب أن تكون السمة v فارغة، ولكن يمكن أن تحتوي على السمتَين f وp.
• f [اختيارية] نسخة سلسلة من القيمة v يتم تنسيقها للعرض. وستتم مطابقة القيم عادةً، بدون الحاجة إلى ذلك، لذا إذا حددت Date(2008, 0, 1) للسمة v، عليك تحديد "1 كانون الثاني (يناير) 2008" أو بعض هذه السلسلة لهذه السمة. ولا يتم التحقّق من هذه القيمة مقابل قيمة v. لن يستخدم التمثيل المرئي هذه القيمة للحساب، بل كتصنيف للعرض فقط. وفي حال حذفها، سيتم إنشاء إصدار سلسلة من v تلقائيًا باستخدام أداة التنسيق التلقائية. يمكن تعديل قيم f باستخدام أداة التنسيق الخاصة بك، أو ضبطها باستخدام setFormattedValue() أو setCell()، أو استردادها باستخدام getFormattedValue().
• p [اختياري] كائن عبارة عن خريطة للقيم المخصّصة التي يتم تطبيقها على الخلية. ويمكن أن تكون هذه القيم من أي نوع JavaScript. إذا كان العرض المرئي يتيح استخدام أي سمات على مستوى الخلية، سيصفها. يمكن استرداد هذه السمات باستخدام الطريقتَين getProperty() وgetProperties(). مثال: p:{style: 'border: 1px solid green;'}.

يجب أن تكون الخلايا في مصفوفة الصفوف بالترتيب نفسه مثل أوصاف الأعمدة في cols. للإشارة إلى خلية فارغة، يمكنك تحديد null أو ترك حقل فارغ لخلية في مصفوفة أو حذف أعضاء المصفوفة اللاحقة. وبالتالي، للإشارة إلى صف يتضمّن قيمة خالية في أول خليتين، يمكنك تحديد [ , , {cell_val}] أو [null, null, {cell_val}].

فيما يلي نموذج لكائن جدول مكون من ثلاثة أعمدة مملوءة بثلاثة صفوف من البيانات:

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ]
}

خاصية p

السمة p على مستوى الجدول هي خريطة للقيم المخصّصة التي يتم تطبيقها على DataTable بالكامل. ويمكن أن تكون هذه القيم من أي نوع JavaScript. إذا كان التمثيل البصري يتيح أي سمات على مستوى جدول البيانات، سيصفها، وإلا ستكون هذه السمة متاحة لاستخدام التطبيق. مثال: p:{className: 'myDataTable'}.

فئة DataView

عرض للقراءة فقط DataTable أساسي. وتتيح السمة DataView اختيار مجموعة فرعية فقط من الأعمدة و/أو الصفوف. ويسمح أيضًا بإعادة ترتيب الأعمدة/الصفوف، وتكرار الأعمدة/الصفوف.

طريقة العرض هي نافذة مباشرة على DataTable الأساسي، وليست لقطة ثابتة للبيانات. وعليك توخي الحذر عند تغيير بنية الجدول نفسه على النحو الموضّح هنا:

• لن تنعكس إضافة الأعمدة أو إزالتها من الجدول الأساسي في العرض، وقد تتسبب في حدوث سلوك غير متوقّع في الملفّ الشخصي. عليك إنشاء DataView جديد من DataTable لمتابعة هذه التغييرات.
• من الآمن إضافة الصفوف أو إزالتها من الجدول الأساسي، وسيتم نشر التغييرات في العرض فورًا (ولكن عليك طلب draw() على أي مرئيات بعد هذا التغيير لعرض مجموعة الصفوف الجديدة). يُرجى العِلم بأنّه إذا أجرى ملفك الشخصي فلترة للصفوف من خلال استدعاء إحدى طرق setRows() or hideRows()، وأضفت صفوفًا أو أزلتها من الجدول الأساسي، لن يكون السلوك متوقّعًا، وعليك إنشاء DataView جديد لإظهار الجدول الجديد.
• من الآمن تغيير قيم الخلايا في الخلايا الحالية، ويتم نشر التغييرات فورًا إلى DataView (ولكن عليك طلب draw() في أي مرئيات بعد هذا التغيير لعرض قيم الخلايا الجديدة).

ويمكن أيضًا إنشاء DataView من DataView آخر. يُرجى العِلم أنّه عند ذكر جدول أو طريقة عرض أساسية، يشير ذلك إلى المستوى الذي يليه مباشرةً. وبمعنى آخر، يشير إلى عنصر البيانات المستخدَم لإنشاء سمة DataView هذه.

تتيح DataView أيضًا الأعمدة المحسوبة، وهي الأعمدة التي يتم احتساب قيمتها بشكل سريع باستخدام إحدى الدوال التي توفّرها. على سبيل المثال، يمكنك تضمين عمود يمثّل مجموع عمودين سابقين أو عمودًا يحسب ربع السنة التقويمي لتاريخ من عمود آخر ويعرضه. يمكنك الاطّلاع على setColumns() لمزيد من التفاصيل.

عند تعديل DataView من خلال إخفاء الصفوف أو الأعمدة أو عرضها، لن يتأثر التمثيل البصري حتى تطلب draw() في العرض المرئي مرة أخرى.

يمكنك الجمع بين DataView.getFilteredRows() وDataView.setRows() لإنشاء DataView مع مجموعة فرعية مثيرة للاهتمام من البيانات، كما هو موضّح هنا:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

الشركات المصنِّعة

تتوفّر طريقتان لإنشاء مثيل DataView جديد:

المنشئ 1

var myView = new google.visualization.DataView(data)

data

يتم استخدام DataTable أو DataView لإعداد الملف الشخصي. تتضمّن طريقة العرض تلقائيًا جميع الأعمدة والصفوف في جدول أو طريقة عرض البيانات الأساسية بالترتيب الأصلي. لإخفاء الصفوف أو الأعمدة أو إظهارها في طريقة العرض هذه، يمكنك طلب طريقة set...() أو hide...() المناسبة.

يُرجى الاطّلاع أيضًا على:

setColumns(), hideColumns() وsetRows()، وhideRows().

المنشئ 2

تنشئ دالة الإنشاء هذه DataView جديدًا من خلال تحديد DataView تسلسلية إلى DataTable. يساعدك في إعادة إنشاء DataView الذي تسلسلته باستخدام DataView.toJSON().

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)

البيانات

الكائن DataTable الذي استخدمته لإنشاء DataView، والذي كان اسمه DataView.toJSON(). إذا كان هذا الجدول مختلفًا كثيرًا عن الجدول الأصلي، ستحصل على نتائج غير متوقّعة.

viewAsJson

سلسلة JSON التي تعرضها DataView.toJSON(). هذا وصف للصفوف التي سيتم إظهارها أو إخفائها من data DataTable.

الطُرق

// Show some columns directly from the underlying data.
// Shows column 3 twice.
view.setColumns([3, 4, 3, 2]);

// Underlying table has a column specifying a value in centimeters.
// The view imports this directly, and creates a calculated column
// that converts the value into inches.
view.setColumns([1,{calc:cmToInches, type:'number', label:'Height in Inches'}]);
function cmToInches(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}

فئة ChartWrapper

يتم استخدام الفئة ChartWrapper لتجميع الرسم البياني ومعالجة جميع طلبات التحميل والرسومات ومصادر البيانات للرسم البياني. تعرض الفئة طرق ملائمة لضبط القيم على الرسم البياني ورسمها. تبسّط هذه الفئة القراءة من مصدر بيانات، لأنّك لست مضطرًا إلى إنشاء معالج استدعاء طلب بحث. يمكنك أيضًا استخدامه لحفظ المخطط بسهولة لإعادة استخدامه.

من الميزات الأخرى التي يوفّرها استخدام ChartWrapper إمكانية خفض عدد عمليات تحميل المكتبة باستخدام التحميل الديناميكي. بالإضافة إلى ذلك، ليس عليك تحميل الحِزم بشكل صريح، لأنّ ChartWrapper سيتولى البحث عن حزم الرسومات وتحميلها نيابةً عنك. راجِع الأمثلة أدناه لمعرفة التفاصيل.

في المقابل، لا تنشر السمة ChartWrapper حاليًا إلا مجموعة فرعية من الأحداث التي تم إنشاؤها من خلال رسوم بيانية: الاختيار والجاهز والخطأ. ولا يتم نقل أحداث أخرى من خلال مثيل ChartWrapper. للحصول على أحداث أخرى، يجب استدعاء getChart() والاشتراك في الأحداث مباشرةً على مقبض الرسم البياني، كما هو موضّح هنا:

var wrapper;
function drawVisualization() {

  // Draw a column chart
  wrapper = new google.visualization.ChartWrapper({
    chartType: 'ColumnChart',
    dataTable: [['Germany', 'USA', 'Brazil', 'Canada', 'France', 'RU'],
                [700, 300, 400, 500, 600, 800]],
    options: {'title': 'Countries'},
    containerId: 'visualization'
  });

  // Never called.
  google.visualization.events.addListener(wrapper, 'onmouseover', uselessHandler);

  // Must wait for the ready event in order to
  // request the chart and subscribe to 'onmouseover'.
  google.visualization.events.addListener(wrapper, 'ready', onReady);

  wrapper.draw();

  // Never called
  function uselessHandler() {
    alert("I am never called!");
  }

  function onReady() {
    google.visualization.events.addListener(wrapper.getChart(), 'onmouseover', usefulHandler);
  }

  // Called
  function usefulHandler() {
    alert("Mouseover event!");
  }
}

الشركة المصنِّعة

ChartWrapper(opt_spec)

opt_spec

[اختيارية]: يمكنك استخدام كائن JSON يحدّد الرسم البياني أو إصدار سلسلة تسلسلية لذلك العنصر. يظهر تنسيق هذا الكائن في مستندات drawChart(). وإذا لم يتم تحديد هذه السمة، يجب ضبط جميع السمات المناسبة باستخدام الطرق set... التي يعرضها هذا الكائن.

الطُرق

يعرض ChartWrapper الطرق الإضافية التالية:

فعاليات

يطرح كائن ChartWrapper الأحداث التالية. تجدر الإشارة إلى أنّه يجب الاتصال بـ ChartWrapper.draw() قبل عقد أي أحداث.

مثال

ينشئ المقتطفان التاليان رسمًا بيانيًا خطيًا مكافئًا. يستخدم المثال الأول التدوين الحرفي JSON لتحديد الرسم البياني، ويستخدم المثال الثاني طرق ChartWrapper لضبط هذه القيم.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Visualization API Sample</title>
<!--
  One script tag loads all the required libraries!
-->
<script type="text/javascript"
      src='https://www.gstatic.com/charts/loader.js'></script>
<script>
  google.charts.load('current);
  google.charts.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    var wrap = new google.visualization.ChartWrapper({
       'chartType':'LineChart',
       'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
       'containerId':'visualization',
       'query':'SELECT A,D WHERE D > 100 ORDER BY D',
       'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
       });
     wrap.draw();
  }
</script>
</head>
<body>
  <div id="visualization" style="height: 400px; width: 400px;"></div>
</body>
</html>

نفس المخطط، الآن باستخدام طرق setter:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html; charset=utf-8'/>
<title>Google Visualization API Sample</title>
<!-- One script tag loads all the required libraries!
-->
<script type="text/javascript"
    src='https://www.gstatic.com/charts/loader.js'></script>
<script type="text/javascript">
  google.charts.load('current');
  google.charts.setOnLoadCallback(drawVisualization);
  function drawVisualization() {
    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>
</head>
<body>
  <div id='visualization' style='height: 400px; width: 400px;'></div>
</body>
</html>

فئة محرّر الرسوم البيانية

تُستخدَم الفئة ChartEditor لفتح مربّع حوار في الصفحة يتيح للمستخدم تخصيص مرئيات بشكل سريع.

لاستخدام ChartEditor:

1. حمِّل حزمة charteditor. في google.charts.load()، حمِّل الحزمة 'charteditor'. لا تحتاج إلى تحميل الحِزم لنوع الرسم البياني الذي تعرضه في المحرّر، لأنّ محرِّر الرسم البياني سيحمّل أي حزمة حسب الحاجة.
2. أنشِئ كائن ChartWrapper يحدّد الرسم البياني الذي تريد أن يخصّصه المستخدم. سيتم عرض هذا الرسم البياني في مربّع الحوار، وسيستخدم المستخدم المحرِّر لإعادة تصميم الرسم البياني أو تغيير أنواع الرسوم البيانية أو حتى تغيير بيانات المصدر.
3. أنشِئ مثيل ChartEditor جديد وسجِّل للاستماع إلى حدث "ok". يتم طرح هذا الحدث عندما ينقر المستخدم على الزر "حسنًا" في مربّع الحوار. وعند تلقّيها، عليك طلب ChartEditor.getChartWrapper() لاسترداد الرسم البياني الذي عدَّله المستخدم.
4. الاتصال بالرقم ChartEditor.openDialog()، مرورًا في ChartWrapper سيؤدي هذا إلى فتح مربع الحوار. تتيح أزرار مربّع الحوار للمستخدم إغلاق المحرِّر. يتوفّر مثيل ChartEditor ما دام ضمن النطاق، ولا يتم حذفه تلقائيًا بعد أن يغلق المستخدم مربّع الحوار.
5. لتعديل الرسم البياني في الرمز، يمكنك طلب الرقم setChartWrapper().

الطُرق

الخيارات

يتيح محرر الرسم البياني الخيارات التالية:

فعاليات

يطرح محرر الرسم البياني الأحداث التالية:

مثال

يفتح المثال التالي مربع حوار محرر مخطط مع مخطط خطي معبأ. إذا نقر المستخدم على "حسنًا"، سيتم حفظ الرسم البياني المعدَّل في <div> المحدد على الصفحة.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  <title>
    Google Visualization API Sample
  </title>
  <script type="text/javascript"
    src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
    google.charts.load('current', {packages: ['charteditor']});
  </script>
  <script type="text/javascript">
    google.charts.setOnLoadCallback(loadEditor);
    var chartEditor = null;

    function loadEditor() {
      // Create the chart to edit.
      var wrapper = new google.visualization.ChartWrapper({
         'chartType':'LineChart',
         'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
         'query':'SELECT A,D WHERE D > 100 ORDER BY D',
         'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
      });

      chartEditor = new google.visualization.ChartEditor();
      google.visualization.events.addListener(chartEditor, 'ok', redrawChart);
      chartEditor.openDialog(wrapper, {});
    }

    // On "OK" save the chart to a <div> on the page.
    function redrawChart(){
      chartEditor.getChartWrapper().draw(document.getElementById('vis_div'));
    }

  </script>
</head>
<body>
  <div id="vis_div" style="height: 400px; width: 600px;"></div>
</body>
</html>

طرق معالجة البيانات

تتضمن مساحة الاسم google.visualization.data طرقًا ثابتة لتنفيذ عمليات تشبه SQL على كائنات DataTable، مثل ضمها أو التجميع حسب قيمة العمود.

تعرض مساحة الاسم google.visualization.data الطرق التالية:

group()

تأخذ كائن DataTable معبأ لتنفيذ عملية GROUP BY تشبه SQL، وتعرض جدولاً يحتوي على صفوف مجمّعة حسب قيم الأعمدة المحدّدة. يُرجى العِلم أنّ هذا الإجراء لا يؤدي إلى تعديل الإدخال DataTable.

يتضمن الجدول المعروض صفًا واحدًا لكل مجموعة من القيم في الأعمدة الرئيسية المحددة. ويشمل كل صف الأعمدة الرئيسية، بالإضافة إلى عمود واحد يتضمّن قيمة عمود مجمّعة في جميع الصفوف التي تطابق مجموعة المفاتيح (على سبيل المثال، مجموع أو عدد جميع القيم في العمود المحدَّد).

تحتوي مساحة الاسم google.visualization.data على عدة قيم مفيدة لتجميع البيانات (مثل sum وcount)، ولكن يمكنك تحديد قيمة خاصة بك (على سبيل المثال، standardDeviation أوsecondHighest). وتُقدَّم التعليمات حول كيفية تحديد موقع التجميع الخاص بك بعد وصف الطريقة.

البنية

google.visualization.data.group(data_table, keys, columns)

data_table

الإدخال DataTable. لن يتم تعديل هذا من خلال طلب الرقم group().

مفاتيح

مصفوفة من أرقام و/أو عناصر تحدّد الأعمدة التي يجب التجميع وفقًا لها. يتضمّن جدول النتائج كل عمود في هذا الصفيف، بالإضافة إلى كل عمود في الأعمدة. إذا كان رقمًا، يكون فهرس عمود للإدخال DataTable المطلوب التجميع حسبه. إذا كان العنصر، سيتضمن دالة يمكنها تعديل العمود المحدد (مثلاً، إضافة 1 إلى القيمة في هذا العمود). يجب أن يحتوي الكائن على السمات التالية:

• عمود: رقم هو فهرس عمود من dt لتطبيق التحويل عليه.
• modifier: هي دالة تقبل قيمة واحدة (قيمة الخلية في هذا العمود لكل صف)، وتعرض القيمة المعدّلة. تُستخدَم هذه الدالة لتعديل قيمة العمود للمساعدة في التجميع، على سبيل المثال، عن طريق استدعاء دالة whoQuarter تحتسب ربعًا من عمود التاريخ، بحيث يمكن لواجهة برمجة التطبيقات تجميع الصفوف حسب ربع السنة. يتم عرض القيمة المحسوبة في الأعمدة الرئيسية في الجدول المعروض. يمكن تعريف هذه الدالة بأنّها مضمّنة داخل هذا الكائن، أو يمكن أن تكون دالة يتم تحديدها في مكان آخر في الرمز البرمجي (يجب أن تكون ضمن نطاق الاستدعاء). توفّر واجهة برمجة التطبيقات دالة تعديل واحدة بسيطة، إليك تعليمات حول كيفية إنشاء دوال خاصة بك وأكثر فائدة. يجب أن تعرف نوع البيانات التي يمكن لهذه الدالة قبولها، وتطلبه فقط على الأعمدة من هذا النوع. وعليك أيضًا معرفة نوع الإرجاع لهذه الدالة، وتعريفه في السمة type الموضّحة أدناه.
• type - النوع الذي تعرضه الدالة modifier. ويجب أن يكون اسمًا لنوع سلسلة JavaScript، مثل "رقم" أو "منطقي".
• label - [اختيارية] تصنيف سلسلة لتخصيص هذا العمود في DataTable المعروضة
• id - [اختيارية] رقم تعريف سلسلة لتخصيص هذا العمود في DataTable المعروضة.

أمثلة: [0] و[0,2] و[0,{column:1, modifier:myPlusOneFunc, type:'number'},2]

الأعمدة

[اختيارية] تتيح لك تحديد الأعمدة، بالإضافة إلى الأعمدة الرئيسية، لتضمينها في جدول الإخراج. بما أنّه يتم ضغط جميع الصفوف في مجموعة الصفوف إلى صف إخراج واحد، عليك تحديد القيمة التي تريد عرضها لمجموعة الصفوف هذه. على سبيل المثال، يمكنك اختيار عرض قيمة العمود من الصف الأول في المجموعة أو عرض متوسط جميع الصفوف فيها. الأعمدة هي مصفوفة من العناصر التي تتضمّن السمات التالية:

• column: رقم يحدد فهرس العمود المطلوب عرضه.
• aggregation - دالة تقبل صفيفًا من كل قيم هذا العمود في مجموعة الصفوف هذه وترجع قيمة واحدة لعرضها في صف النتيجة. يجب أن تكون القيمة المعروضة من النوع الذي تحدّده السمة type الخاصة بالكائن. وفي ما يلي تفاصيل حول إنشاء دالة التجميع الخاصة بك. يجب أن تعرف أنواع البيانات التي تقبلها هذه الطريقة وأن تطلبها فقط على الأعمدة من النوع المناسب. توفّر واجهة برمجة التطبيقات العديد من دوال التجميع المفيدة. راجِع دوال التجميع المقدَّمة أدناه للاطّلاع على قائمة، أو إنشاء دالة تجميع للتعرّف على كيفية كتابة دالة التجميع الخاصة بك.
• type - نوع إرجاع دالة التجميع. ويجب أن يكون اسمًا من نوع سلسلة JavaScript، مثل "رقم" أو "منطقي".
• label - [اختياري] تصنيف سلسلة لتطبيقه على هذا العمود في الجدول المعروض.
• id - [اختيارية] رقم تعريف سلسلة لتطبيقه على هذا العمود في الجدول المعروض.

القيمة المعروضة

تمثّل هذه السمة DataTable عمودًا واحدًا لكل عمود مدرَج في المفاتيح وعمود واحد لكل عمود مُدرَج في الأعمدة. يتم ترتيب الجدول حسب الصفوف الرئيسية، من اليسار إلى اليمين.

مثال

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
  dt,
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

دوال المُعدِّل المقدَّمة

توفّر واجهة برمجة التطبيقات دوال التعديل التالية التي يمكنك تمريرها إلى المفاتيح. modifier لتخصيص سلوك التجميع.

وظائف التجميع المقدَّمة

توفّر واجهة برمجة التطبيقات دوال التجميع التالية التي يمكنك ضبطها في الأعمدة. aggregation صفيفًا.

إنشاء دالة تعديل

يمكنك إنشاء دالة تعديل لتنفيذ عملية تحويل بسيطة لقيم مفتاح التحكّم قبل أن تجمّع الدالة group() صفوفك. تستخدم هذه الدالة قيمة خلية واحدة، وتنفِّذ إجراءً عليها (على سبيل المثال، تضيف 1 إلى القيمة)، وتعرضها. وليس من الضروري أن يكون نوع الإدخال والإرجاع من النوع نفسه، ولكن يجب أن يعرف المتصل نوعَي الإدخال والمخرجات. في ما يلي مثال على دالة تقبل التاريخ وتعرض الربع:

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
  return Math.floor(someDate.getMonth()/3) + 1;
}

إنشاء دالة تجميع

يمكنك إنشاء دالة تجميع تقبل مجموعة من قيم الأعمدة في مجموعة صفوف وتعرض رقمًا واحدًا، على سبيل المثال، عرض عدد أو متوسط عدد القيم. في ما يلي تنفيذ لدالة تجميع الأعداد المتوفرة، والتي تعرض عدد الصفوف في مجموعة الصفوف:

// Input type: Array of any type
// Return type: number
function count(values) {
  return values.length;
}

join()

تجمع هذه الطريقة بين جدولَي بيانات (كائن DataTable أو DataView) في جدول نتائج واحد، على غرار عبارة SQL JOIN. ويمكنك تحديد زوج أو أكثر من أزواج الأعمدة (أعمدة مفتاح) بين الجدولَين، وسيتضمن جدول النتائج الصفوف وفقًا لطريقة الدمج التي تحدّدها: الصفوف التي يتطابق فيها كلا المفتاحَين فقط أو جميع الصفوف من جدول واحد أو جميع الصفوف من كلا الجدولَين، سواء كانت المفاتيح متطابقة أم لا. لا يتضمّن جدول النتائج سوى الأعمدة الرئيسية، بالإضافة إلى أي أعمدة إضافية تحدّدها. يُرجى العِلم أنّه لا يمكن أن يتضمّن dt2 مفاتيح مكرّرة، ولكن يمكن أن يتضمّن dt1 مفاتيح مكرّرة. ويعني مصطلح "مفتاح" تركيبة كل قيم الأعمدة الرئيسية، وليس قيمة عمود مفتاح رئيسي، لذلك إذا كان الصف يحتوي على قيم الخلية A | B | C والعمودان 0 و1 هما عمودان رئيسيان، يصبح مفتاح هذا الصف هو AB.

البنية

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);

dt1

قيمة DataTable تمت تعبئتها للانضمام إلى dt2.

dt2

عنصر DataTable تمت تعبئته للانضمام إليه مع dt1. ولا يمكن أن يحتوي هذا الجدول على عدة مفاتيح متطابقة (حيث يكون المفتاح عبارة عن مجموعة من قيم الأعمدة الرئيسية).

joinMethod

سلسلة تحدد نوع الصلة. إذا كانت dt1 تحتوي على صفوف متعدّدة تتطابق مع صف dt2، سيتضمّن جدول الإخراج جميع صفوف dt1 المطابقة. اختَر من بين القيم التالية:

• "full": يشتمل جدول الإخراج على جميع الصفوف من كلا الجدولين، بغض النظر عما إذا كانت المفاتيح متطابقة أم لا. ستحتوي الصفوف غير المتطابقة على إدخالات خلية فارغة، ويتم ضم الصفوف المتطابقة.
• "inner" - عملية الدمج الكاملة التي تمت فلترتها لتضمين الصفوف التي تتطابق فيها المفاتيح فقط.
• "left" - يحتوي جدول الإخراج على جميع الصفوف من dt1، سواء كانت هناك أي صفوف مطابقة من dt2 أم لا.
• "right" - يتضمن جدول الإخراج جميع الصفوف من dt2، سواء كانت هناك أي صفوف مطابقة من dt1 أم لا.

مفاتيح

مصفوفة من الأعمدة الرئيسية المطلوب مقارنتها من كلا الجدولين. كل زوج هو مصفوفة من عنصرَين، الأول عبارة عن مفتاح في dt1، والثاني عبارة عن مفتاح في dt2. يمكن لهذه المصفوفة تحديد الأعمدة حسب الفهرس أو رقم التعريف أو التصنيف. يمكنك مراجعة getColumnIndex.
يجب أن تكون الأعمدة من النوع نفسه في كلا الجدولين. يجب أن تتطابق جميع المفاتيح المحدّدة وفقًا للقاعدة المحدّدة في joinMethod لتضمين صف من الجدول. ويتم دائمًا تضمين الأعمدة الرئيسية في جدول الإخراج. الجدول الأيمن فقط هو dt1، الذي يمكن أن يتضمّن مفاتيح مكرّرة، ويجب أن تكون المفاتيح في dt2 فريدة. ويشير مصطلح "مفتاح" هنا إلى مجموعة فريدة من الأعمدة الرئيسية، وليس قيم أعمدة فردية. على سبيل المثال، إذا كان العمودان الرئيسيان A وB، لن يحتوي الجدول التالي إلا على قيم أساسية فريدة (وبالتالي يمكن استخدامه على النحو dt2):

جيم	B
جين	أحمر
جين	بالأزرق
فريد	أحمر

مثال: يقارن [[0,0], [2,1]] بين قيم العمود الأول في كلا الجدولين والعمود الثالث من dt1 مع العمود الثاني من dt1.

dt1Columns

مصفوفة من الأعمدة من dt1 لتضمينها في جدول الإخراج، بالإضافة إلى الأعمدة الرئيسية في dt1. يمكن لهذه المصفوفة تحديد الأعمدة حسب الفهرس أو رقم التعريف أو التصنيف. يمكنك مراجعة getColumnIndex.

dt2Columns

مصفوفة من الأعمدة من dt2 لتضمينها في جدول الإخراج، بالإضافة إلى الأعمدة الرئيسية في dt2. يمكن لهذه المصفوفة تحديد الأعمدة حسب الفهرس أو رقم التعريف أو التصنيف. يمكنك مراجعة getColumnIndex.

القيمة المعروضة

DataTable يتضمن الأعمدة الرئيسية وdt1Columns وdt1Columns. يتم ترتيب هذا الجدول حسب الأعمدة الرئيسية، من اليسار إلى اليمين. عندما تكون joinMethod 'inner'، يجب تعبئة جميع الخلايا الرئيسية. بالنسبة إلى طُرق الدمج الأخرى، في حال عدم العثور على مفتاح مطابق، سيحتوي الجدول على قيمة فارغة لأي خلايا رئيسية غير متطابقة.

أمثلة

*Tables*
dt1                        dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle

أدوات التنسيق

توفّر واجهة برمجة التطبيقات Google Visualization API أدوات التنسيق التي يمكن استخدامها لإعادة تنسيق البيانات في العرض المرئي. وتُغيّر أدوات التنسيق هذه القيمة المنسَّقة للعمود المحدّد في جميع الصفوف. تجدر الإشارة إلى ما يلي:

• تعمل أدوات التنسيق على تعديل القيم المنسّقة فقط، وليس القيم الأساسية. على سبيل المثال، ستكون القيمة المعروضة "$1,000.00"، لكنّ القيمة الأساسية ستظلّ "1000".
• تؤثر أدوات التنسيق في عمود واحد فقط في كل مرة. لإعادة تنسيق أعمدة متعددة، يجب تطبيق أداة تنسيق على كل عمود تريد تغييره.
• إذا كنت تستخدم أيضًا أدوات التنسيق التي يحددها المستخدم، ستلغي بعض أدوات تنسيق العروض المرئية في Google جميع أدوات التنسيق التي يحددها المستخدم.

يتم اشتقاق التنسيق الفعلي المطبَّق على البيانات من اللغة التي تم تحميل واجهة برمجة التطبيقات بها. لمزيد من التفاصيل، راجِع تحميل الرسوم البيانية بلغة معيّنة .

ملاحظة مهمة: لا يمكن استخدام أدوات التنسيق إلا مع DataTable، ولا يمكن استخدامها مع DataView (كائنات DataView للقراءة فقط).

في ما يلي الخطوات العامة لاستخدام أداة التنسيق:

1. احصل على عنصر DataTable الذي تمت تعبئته.
2. بالنسبة إلى كل عمود تريد إعادة تنسيقه:
   1. أنشئ كائنًا يحدِّد جميع خيارات أداة التنسيق. وهذا عبارة عن كائن JavaScript أساسي يضم مجموعة من السمات والقيم. يُرجى الاطّلاع على مستندات أداة التنسيق لمعرفة السمات المتوافقة. (اختياريًا، يمكنك تمرير كائن الترميز الحرفي في كائن لتحديد خياراتك).
   2. أنشئ أداة التنسيق، مع تمرير كائن الخيارات.
   3. يمكنك استدعاء formatter.format(table, colIndex)، وإدخال الرمز DataTable ورقم عمود البيانات (المستند إلى الصفر) المطلوب إعادة تنسيقها. ويُرجى العِلم بأنّه لا يمكنك تطبيق سوى أداة تنسيق واحدة على كل عمود، وسيؤدي تطبيق تنسيق ثانٍ إلى استبدال تأثيرات العمود الأول.
      ملاحظة: يتطلب العديد من أدوات التنسيق علامات HTML لعرض تنسيق خاص. وإذا كان التمثيل المرئي يتيح استخدام خيار allowHtml، يجب ضبطه على "صحيح".

في ما يلي مثال على تغيير قيم التاريخ المنسَّقة في عمود التاريخ لاستخدام تنسيق تاريخ طويل ("1 كانون الثاني/يناير 2009"):

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));

// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});

// Reformat our data.
formatter.format(data, 1);

// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});

تعرض معظم أدوات التنسيق الطريقتين التاليتين:

الطريقة	الوصف
google.visualization.formatter_name(options)	دالة إنشاء، حيث يكون formatter_name اسمًا محددًا لفئة التنسيق. options - كائن JavaScript عام يحدد الخيارات الخاصة بأداة التنسيق تلك. هذا الكائن هو كائن عام يضم أزواج السمة/القيمة وسمات خاصة بأداة التنسيق تلك. يمكنك الاطّلاع على المستندات الخاصة بجهة التنسيق المحددة لمعرفة الخيارات المتاحة. في ما يلي مثالان على طريقتين لاستدعاء الدالة الإنشائية لكائن DateFormat، وتمرير خاصيتين: // Object literal technique var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5}); // Equivalent property setting technique var options = new Object(); options['formatType'] = 'long'; options['timeZone'] = -5; var formatter = new google.visualization.DateFormat(options);
format(data, colIndex)	لإعادة تنسيق البيانات في العمود المحدّد. data: DataTable التي تحتوي على البيانات المطلوب إعادة تنسيقها. لا يمكنك استخدام DataView هنا. colIndex - الفهرس الصفري للعمود المطلوب تنسيقه. لتنسيق أعمدة متعددة، عليك استدعاء هذه الطريقة عدة مرات بقيم colIndex مختلفة.

 

توفر واجهة برمجة التطبيقات Google Visualization API أدوات التنسيق التالية:

اسم المنسّق	الوصف
ArrowFormat	لإضافة سهم متّجه للأعلى أو للأسفل، للإشارة إلى ما إذا كانت قيمة الخلية أعلى من قيمة محدّدة أو أسفلها
BarFormat	تضيف هذه السمة شريطًا ملونًا، ويشير الاتجاه واللون إلى ما إذا كانت قيمة الخلية أعلى أو أقل من قيمة محددة.
ColorFormat	ألوان خلية وفقًا لما إذا كانت القيم تقع ضمن نطاق محدد.
DateFormat	لتنسيق قيمة التاريخ أو التاريخ والوقت بعدة طرق، بما في ذلك "1 كانون الثاني (يناير) 2009" و"1/1/09" و "1 كانون الثاني (يناير) 2009".
NumberFormat	لتنسيق الجوانب المختلفة للقيم الرقمية
PatternFormat	تعمل على إنشاء تسلسل لقيم الخلايا في الصف نفسه في خلية محددة، بالإضافة إلى نص عشوائي.

ArrowFormat

لإضافة سهم لأعلى أو لأسفل إلى خلية رقمية، بناءً على ما إذا كانت القيمة أعلى أو أقل من قيمة أساسية محددة. في حال تساوي القيمة الأساسية، لن يتم عرض أي سهم.

الخيارات

تتيح ArrowFormat الخيارات التالية، والتي تم تمريرها إلى الدالة الإنشائية:

Option	الوصف
base	رقم يشير إلى القيمة الأساسية، يُستخدَم للمقارنة مع قيمة الخلية. إذا كانت قيمة الخلية أعلى، ستتضمّن الخلية سهمًا أخضر للأعلى. وإذا كانت قيمة الخلية أقل، ستتضمّن سهمًا أحمر لأسفل، وإذا كان الأمر كذلك، لن يكون هناك سهم.

نموذج التعليمات البرمجية

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues Change');
data.addRows([
  ['Shoes', {v:12, f:'12.0%'}],
  ['Sports', {v:-7.3, f:'-7.3%'}],
  ['Toys', {v:0, f:'0%'}],
  ['Electronics', {v:-2.1, f:'-2.1%'}],
  ['Food', {v:22, f:'22.0%'}]
]);

var table = new google.visualization.Table(document.getElementById('arrowformat_div'));

var formatter = new google.visualization.ArrowFormat();
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true});

BarFormat

تضيف شريطًا ملونًا إلى خلية رقمية تشير إلى ما إذا كانت قيمة الخلية أعلى أو أقل من قيمة أساسية محددة.

الخيارات

تتيح BarFormat الخيارات التالية، والتي تم تمريرها إلى الدالة الإنشائية:

Option	مثال الوصف
base	يشير ذلك المصطلح إلى رقم يمثّل القيمة الأساسية التي يجب مقارنة قيمة الخلية بها. إذا كانت قيمة الخلية أعلى، سيتم رسمها إلى يمين القاعدة، وإذا كانت أقل، سيتم رسمها إلى اليسار. القيمة التلقائية هي 0.
colorNegative	سلسلة تشير إلى قسم القيمة السالبة من الأشرطة. القيم المحتملة هي "أحمر" و"أخضر" و"أزرق"، والقيمة التلقائية هي "أحمر".
colorPositive	سلسلة تشير إلى لون قسم القيمة الموجبة للأشرطة. القيم المحتملة هي "أحمر" و"أخضر" و"أزرق". اللون الافتراضي هو "الأزرق".
drawZeroLine	قيمة منطقية تشير إلى ما إذا كان سيتم رسم خط أساسي داكن بحجم 1 بكسل عند وجود قيم سالبة. الخط الداكن موجود لتحسين المسح المرئي للأشرطة. القيمة التلقائية هي "خطأ".
max	الحد الأقصى للرقم في نطاق الشريط. والقيمة التلقائية هي أعلى قيمة في الجدول.
min	الحد الأدنى لقيمة الرقم لنطاق الشريط. والقيمة التلقائية هي أدنى قيمة في الجدول.
showValue	إذا كانت القيمة true، سيتم عرض القيم والأشرطة، وإذا كانت false، سيتم عرض الأشرطة فقط. القيمة التلقائية هي true.
width	يشير إلى سُمك كل شريط بالبكسل. القيمة التلقائية هي 100.

نموذج التعليمات البرمجية

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('barformat_div'));

var formatter = new google.visualization.BarFormat({width: 120});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

ColorFormat

تحدّد الألوان لمقدمة أو خلفية خلية رقمية، استنادًا إلى قيمة الخلية. تُعدّ طريقة التنسيق هذه غير عادية، إذ إنّها لا تتيح خياراتها في الدالة الإنشائية. بدلاً من ذلك، عليك طلب addRange() أو addGradientRange() لعدد غير محدود من المرّات لإضافة نطاقات الألوان قبل طلب format(). يمكن تحديد الألوان بأي تنسيق HTML مقبول، على سبيل المثال "أسود" أو "#000000" أو "#000".

الطُرق

يتيح ColorFormat استخدام الطرق التالية:

الطريقة	الوصف
google.visualization.ColorFormat()	المنشئ. لا يتم استخدام أي وسيطات.
addRange(from, to, color, bgcolor)	تحدِّد لون المقدّمة و/أو لون الخلفية لخلية ما، بناءً على قيمة الخلية. أي خلية تحتوي على قيمة في النطاق المحدّد من from إلى to سيتم تعيينها إلى color وbgcolor. من المهم أن ندرك أنّ النطاق غير شامل، لأنّ إنشاء نطاق يتراوح بين 1 و1,000 وثانية من 1,000 إلى 2,000 لن يشمل القيمة 1,000. from - [String, Number, Date, DateTime, or TimeOfDay] الحد الأدنى (شاملاً) للنطاق، أو قيمة فارغة. وإذا كانت القيمة "فارغة"، ستطابق -∞، وتتم مقارنة حدود السلسلة أبجديًا مقابل قيم السلسلة. to - [String, Number, Date, DateTime, or TimeOfDay] الحد المرتفع (غير شامل) للنطاق، أو قيمة فارغة. إذا كانت القيمة "فارغة"، ستطابق +∞، وتتم مقارنة حدود السلسلة أبجديًا مقابل قيم السلسلة. color - اللون المطلوب تطبيقه على النص في الخلايا المطابقة. يمكن أن تكون القيم إما قيم " #RRGGBB" أو ثوابت ألوان محدّدة (مثال: " #FF0000" أو "أحمر"). bgcolor - اللون المطلوب تطبيقه على خلفية الخلايا المطابقة. يمكن أن تكون القيم إما " #RRGGBB" أو ثوابت ألوان محدّدة (مثال: " #FF0000" أو "أحمر").
addGradientRange(from, to, color, fromBgColor, toBgColor)	يعيّن لون الخلفية من نطاق وفقًا لقيمة الخلية. ويتم تغيير حجم اللون ليطابق قيمة الخلية داخل نطاق يتراوح من لون الحد الأدنى إلى لون الحد الأعلى. تجدر الإشارة إلى أنّ هذه الطريقة لا يمكن أن تقارن بين قيم السلاسل، كما هو الحال مع addRange(). ملاحظة: غالبًا ما يصعب على المشاهدين قياس نطاقات الألوان بدقة، ويكون النطاق الأبسط وأسهل في القراءة هو من لون مشبّع بالكامل إلى أبيض (على سبيل المثال، #FF0000—FFFFFF). from - [Number, Date, DateTime, or TimeOfDay] الحد الأدنى (شاملاً) للنطاق، أو قيمة فارغة. إذا كانت القيمة خالية، فإنها تطابق -∞. to - [Number, Date, DateTime, or TimeOfDay] الحد الأعلى (غير شامل) للنطاق، أو قيمة فارغة. إذا كانت القيمة خالية، فإنها تطابق +∞. color - اللون المطلوب تطبيقه على النص في الخلايا المطابقة. ويكون هذا اللون موحّدًا في جميع الخلايا بغض النظر عن قيمتها. fromBgColor - لون الخلفية للخلايا التي تحتوي على القيم في النهاية المنخفضة للتدرج. يمكن أن تكون القيم إما " #RRGGBB" أو ثوابت ألوان محدّدة (مثال: "#FF0000" أو "red"). toBgColor - لون خلفية الخلايا التي تحتوي على قيم في النهاية العليا للتدرج. يمكن أن تكون القيم إما " #RRGGBB" أو ثوابت ألوان محدّدة (مثال: "#FF0000" أو "red").
format(dataTable, columnIndex)	طريقة format() العادية لتطبيق التنسيق على العمود المحدّد.

نموذج التعليمات البرمجية

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('colorformat_div'));

var formatter = new google.visualization.ColorFormat();
formatter.addRange(-20000, 0, 'white', 'orange');
formatter.addRange(20000, null, 'red', '#33ff33');
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

DateFormat

تنسيق قيمة Date في JavaScript بعدة طرق، بما في ذلك "1 كانون الثاني (يناير) 2016" و"1/1/16" و "1 كانون الثاني (يناير) 2016".

الخيارات

تتيح DateFormat الخيارات التالية، والتي تم تمريرها إلى الدالة الإنشائية:

Option	الوصف
formatType	خيار تنسيق سريع للتاريخ. تتوفّر قيم السلسلة التالية، مع إعادة تنسيق التاريخ 28 شباط (فبراير) 2016 كما هو موضّح: "short" - تنسيق قصير: مثال "2/28/16" "متوسط" - تنسيق متوسط: على سبيل المثال، "28 شباط (فبراير) 2016" "long" (طويل) - تنسيق طويل: مثل "28 شباط (فبراير) 2016" لا يمكنك تحديد كل من formatType وpattern.
pattern	نمط تنسيق مخصّص يتم تطبيقه على القيمة، وهو مشابه لتنسيق التاريخ والوقت في ICU. مثلاً: var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"}); لا يمكنك تحديد كل من formatType وpattern. يمكنك الاطّلاع على المزيد من التفاصيل حول الأنماط في القسم التالي.
timeZone	المنطقة الزمنية التي يجب عرض قيمة التاريخ فيها. هذه قيمة رقمية تشير إلى توقيت غرينيتش + هذا العدد من المناطق الزمنية (يمكن أن يكون سالبًا). ويتم إنشاء عنصر التاريخ بشكل تلقائي باستخدام المنطقة الزمنية المفترضة للكمبيوتر الذي تم إنشاؤها عليه، ويستخدم هذا الخيار لعرض هذه القيمة في منطقة زمنية مختلفة. على سبيل المثال، إذا أنشأت عنصر التاريخ الساعة 5 مساءً على جهاز كمبيوتر موجود في غرينتش في إنجلترا، وحدّدت المنطقة الزمنية على 5- (options['timeZone'] = -5، أو توقيت شرق المحيط الهادئ في الولايات المتحدة)، ستكون القيمة المعروضة هي 12 ظهرًا.

الطُرق

يتيح DateFormat استخدام الطرق التالية:

الطريقة	الوصف
google.visualization.DateFormat(options)	المنشئ. راجِع قسم الخيارات أعلاه للحصول على مزيد من المعلومات.
format(dataTable, columnIndex)	طريقة format() العادية لتطبيق التنسيق على العمود المحدّد.
formatValue(value)	تعرض القيمة المنسقة لقيمة معينة. ولا تتطلّب هذه الطريقة إضافة DataTable.

نموذج التعليمات البرمجية

function drawDateFormatTable() {
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date (Long)');
  data.addColumn('date', 'Start Date (Medium)');
  data.addColumn('date', 'Start Date (Short)');
  data.addRows([
    ['Mike', new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26)],
    ['Bob', new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0)],
    ['Alice', new Date(2006, 7, 16),
              new Date(2006, 7, 16),
              new Date(2006, 7, 16)]
  ]);

  // Create three formatters in three styles.
  var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
  var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
  var formatter_short = new google.visualization.DateFormat({formatType: 'short'});

  // Reformat our data.
  formatter_long.format(data, 1);
  formatter_medium.format(data,2);
  formatter_short.format(data, 3);

  // Draw our data
  var table = new google.visualization.Table(document.getElementById('dateformat_div'));
  table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
}

مزيد من المعلومات عن أنماط التواريخ

في ما يلي بعض التفاصيل الإضافية حول الأنماط المتاحة:

تتشابه الأنماط مع تنسيق التاريخ والوقت في ICU، ولكن الأنماط التالية غير متاحة بعد: A e D F g Y u w W. ولتجنُّب التعارض مع الأنماط، يجب أن يكون أي نص حرفي تريد ظهوره في الناتج محاطًا بعلامات اقتباس مفردة، باستثناء علامة الاقتباس المفردة التي يجب مضاعفتها: على سبيل المثال، "K 'o''clock.'".

النمط	الوصف	مثال على الإخراج
أخضر	محدد العصر.	إعلان
yy أو yyyy	سنة.	1996
ن	شهر في السنة. بالنسبة إلى كانون الثاني (يناير): M ينتج 1 يُنتج MM 01 نتائج شهر يناير ينتج عنها شهر يناير نتائج شهر يناير ينتج عنها MMMM	"يوليو" "07"
d	يوم في الشهر ستضيف القيم الإضافية "d" أصفارًا بادئة.	10
س	ساعة في مقياس 12 ساعة ستضيف القيم الإضافية "h" أصفارًا بادئة.	12
H	ساعة بمقياس 24 ساعة ستضيف قيم Extra Hk أصفارًا بادئة.	0
د	دقيقة بالساعة. ستضيف قيم "M" الإضافية أصفارًا بادئة.	30
ث	ثانيًا في الدقيقة. ستضيف قيم 's الإضافية أصفارًا بادئة.	55
S	الكسر الثاني. سيتم ملء قيم 'S' الإضافية على اليمين بالأصفار.	978
E	يوم من الأسبوع النتائج التالية ليوم "الثلاثاء": تقوم E بإنتاج T EE أو EEE منتج الثلاثاء أو الثلاثاء عرض EEEE يوم الثلاثاء	"الثلاثاء" "الثلاثاء"
aa	ص/م	"مساء"
k	ساعة في اليوم (من 1 إلى 24) ستضيف القيم الإضافية "k" أصفارًا بادئة.	24
K	الساعة في ص/م (0~11). ستضيف القيم الإضافية "k" أصفارًا بادئة.	0
z	المنطقة الزمنية. بالنسبة إلى المنطقة الزمنية 5، يتم عرض "UTC+5"	"التوقيت العالمي المنسق +5"
Z	المنطقة الزمنية بتنسيق RFC 822. بالنسبة إلى المنطقة الزمنية -5: إنتاج Z وZZ وZZZ و-0500 ZZZZ والمزيد من المنتجات إنتاج "GMT -05:00"	"-0800" "غرينيتش -05:00"
v	المنطقة الزمنية (عامّة).	"توقيت المحيط الهادئ/توقيت جرينتش - 5"
'	حرف الإلغاء للنص	'Date='
''	علامة الاقتباس المفردة	نعم

NumberFormat

يصف كيف يجب تنسيق الأعمدة الرقمية. وتشمل خيارات التنسيق تحديد رمز بادئة (مثل علامة الدولار) أو علامة الترقيم لاستخدامها كعلامة الآلاف.

الخيارات

تتيح NumberFormat الخيارات التالية، والتي تم تمريرها إلى الدالة الإنشائية:

Option	الوصف
decimalSymbol	حرف لاستخدامه كعلامة عشرية. القيمة الافتراضية هي النقطة (.).
fractionDigits	رقم يحدد عدد الأرقام التي سيتم عرضها بعد العلامة العشرية. والعدد التلقائي هو 2. إذا حدّدت أرقامًا أكثر من العدد الذي يحتويه الرقم، سيتم عرض أصفار للقيم الأصغر. سيتم تقريب القيم المقطّعة (5 تقريب إلى أعلى).
groupingSymbol	حرف يتم استخدامه لتجميع الأرقام الموجودة على يسار العلامة العشرية إلى مجموعات من ثلاثة أرقام. ويتم استخدام الفاصلة (,) بشكل تلقائي.
negativeColor	لون النص للقيم السالبة لم يتم تحديد قيمة تلقائية. ويمكن أن تكون القيم أي قيمة لون HTML مقبولة، مثل "أحمر" أو "#FF0000".
negativeParens	قيمة منطقية، حيث تشير القيمة "صحيح" إلى أنّ القيم السالبة يجب أن تحيط بأقواس. الإعداد التلقائي صحيح.
pattern	سلسلة التنسيق عند توفير هذه السمة، يتم تجاهل جميع الخيارات الأخرى باستثناء negativeColor. سلسلة التنسيق هي مجموعة فرعية من مجموعة أنماط ICU . على سبيل المثال، سينتج عن {pattern:'#,###%'} قيم الناتج "1,000%" و"750%" و "50%" للقيم 10 و7.5 و0.5.
prefix	بادئة سلسلة للقيمة، على سبيل المثال "$".
suffix	لاحقة سلسلة للقيمة، مثل "%".

الطُرق

يتيح NumberFormat استخدام الطرق التالية:

الطريقة	الوصف
google.visualization.NumberFormat(options)	المنشئ. راجِع قسم الخيارات أعلاه للحصول على مزيد من المعلومات.
format(dataTable, columnIndex)	طريقة format() العادية لتطبيق التنسيق على العمود المحدّد.
formatValue(value)	تعرض القيمة المنسقة لقيمة معينة. ولا تتطلّب هذه الطريقة إضافة DataTable.

نموذج التعليمات البرمجية

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('numberformat_div'));

var formatter = new google.visualization.NumberFormat(
    {prefix: '$', negativeColor: 'red', negativeParens: true});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

PatternFormat

تتيح لك هذه الميزة دمج قيم الأعمدة المحدّدة في عمود واحد، بالإضافة إلى نص عشوائي. على سبيل المثال، إذا كان لديك عمود للاسم الأول وعمود لاسم العائلة، يمكنك تعبئة العمود الثالث بـ {last name}، {first name}. لا تتّبع أداة التنسيق هذه اصطلاحات الدالة الإنشائية والطريقة format(). راجِع قسم "الطرق" أدناه للحصول على تعليمات.

الطُرق

يتيح PatternFormat استخدام الطرق التالية:

الطريقة	الوصف
google.visualization.PatternFormat(pattern)	المنشئ. لا يقبل كائن خيارات. بدلاً من ذلك، يتم استخدام مَعلمة pattern للسلسلة. هذه سلسلة تصف قيم الأعمدة التي يجب وضعها في عمود الوجهة، بالإضافة إلى أي نص عشوائي. يمكنك تضمين العناصر النائبة في السلسلة للإشارة إلى قيمة من عمود آخر لتضمينه. العناصر النائبة هي {#}، حيث يمثّل الرقم # فهرس عمود المصدر المطلوب استخدامه. الفهرس هو فهرس في المصفوفة srcColumnIndices من طريقة format() أدناه. لتضمين حرف { أو } حرفي، يمكنك الهروب منه على النحو التالي: \{ أو \}. لتضمين علامة \ حرفية، يمكنك تجنّبه كـ \\. نموذج التعليمات البرمجية يوضّح المثال التالي دالة إنشاء لنمط ينشئ عنصر ارتساء، مع الحصول على العنصرين الأول والثاني من الطريقة format(): var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>');
format(dataTable, srcColumnIndices, opt_dstColumnIndex)	استدعاء التنسيق العادي، مع بعض المعلمات الإضافية: dataTable - جدول البيانات الذي سيتم العمل عليه. srcColumnIndices: مصفوفة من فهارس عمود واحدة أو أكثر (مستندة إلى صفر) يتم سحبها كمصادر من جدول البيانات الأساسي. وسيتم استخدامه كمصدر بيانات للمَعلمة pattern في الدالة الإنشائية. لا يجب أن تكون أرقام الأعمدة مرتبة. opt_dstColumnIndex - [اختياري] عمود الوجهة لعرض ناتج معالجة النمط. إذا لم يتم تحديد العنصر، سيتم استخدام العنصر الأول في srcColumIndices كوجهة. الاطّلاع على أمثلة التنسيق بعد الجدول.

في ما يلي بعض الأمثلة على المدخلات والمخرجات لجدول من أربعة أعمدة.

Row before formatting (4 columns, last is blank):
John  |  Paul  |  Jones  |  [empty]

var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
  John  |  Paul  |  Jones  |  John Paul Jones

var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
  John  |  Paul  |  Jones  |  Jones, John

نموذج التعليمات البرمجية

يوضّح المثال التالي كيفية دمج البيانات من عمودَين لإنشاء عنوان بريد إلكتروني. تستخدِم هذه الأداة كائن DataView لإخفاء أعمدة المصدر الأصلي:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Name');
data.addColumn('string', 'Email');
data.addRows([
  ['John Lennon', 'john@beatles.co.uk'],
  ['Paul McCartney', 'paul@beatles.co.uk'],
  ['George Harrison', 'george@beatles.co.uk'],
  ['Ringo Starr', 'ringo@beatles.co.uk']
]);

var table = new google.visualization.Table(document.getElementById('patternformat_div'));

var formatter = new google.visualization.PatternFormat(
    '<a href="mailto:{1}">{0}</a>');
// Apply formatter and set the formatted value of the first column.
formatter.format(data, [0, 1]);

var view = new google.visualization.DataView(data);
view.setColumns([0]); // Create a view with the first column only.

table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

GadgetHelper

فئة مساعدة لتبسيط أدوات الكتابة التي تستخدم Google Visualization API.

الشركة المصنِّعة

google.visualization.GadgetHelper()

الطُرق

الطريقة	القيمة المعروضة	الوصف
createQueryFromPrefs(prefs)	google.visualization.Query	ثابت يمكنك إنشاء مثيل جديد من google.visualization.Query وضبط خصائصه وفقًا للقيم من الإعدادات المفضّلة للأداة. يكون نوع المَعلمة prefs هو _IG_Prefs. يتم استخدام التفضيل _table_query_url لضبط عنوان URL لمصدر بيانات طلب البحث. يتم استخدام التفضيل _table_query_refresh_interval لضبط الفاصل الزمني لإعادة تحميل طلب البحث (بالثواني).
validateResponse(response)	منطقي	ثابت المَعلمة response هي من النوع google.visualization.QueryResponse. تعرض true إذا كان الرد يحتوي على بيانات. تعرض false في حال تعذّر تنفيذ طلب البحث ولم تكن الاستجابة تحتوي على بيانات. في حال حدوث خطأ، تعرض هذه الطريقة رسالة خطأ.

فئات طلبات البحث

تتوفر العناصر التالية لإرسال طلبات البحث عن البيانات إلى مصدر بيانات خارجي، مثل جداول بيانات Google.

• طلب البحث: يؤدي هذا الخيار إلى التفاف طلب البيانات الصادر.
• QueryResponse: للتعامل مع الردّ من مصدر البيانات.

طلب البحث

يمثل طلب بحث يتم إرساله إلى مصدر بيانات.

الشركة المصنِّعة

google.visualization.Query(dataSourceUrl, opt_options)

المَعلمات

dataSourceUrl

[مطلوبة، وعنوان URL سلسلة] لإرسال طلب البحث إليه ويمكنك الاطّلاع على مستندات الرسومات البيانية وجداول البيانات الخاصة بجداول بيانات Google.

opt_options

[اختياري، عنصر] خريطة بخيارات الطلب. ملاحظة: إذا كنت تصل إلى مصدر بيانات محظور ، يجب عدم استخدام هذه المَعلمة. في ما يلي السمات المتوافقة:

• sendMethod - [اختيارية، سلسلة] تحدِّد الطريقة المستخدمة لإرسال طلب البحث. اختَر إحدى قيم السلسلة التالية:
  • 'xhr' - أرسِل طلب البحث باستخدام XmlHttpRequest.
  • 'scriptInjection' - إرسال طلب البحث باستخدام إدخال النص البرمجي.
  • 'makeRequest' - [متاح فقط للأدوات التي تم إيقافها نهائيًا] إرسال طلب البحث باستخدام طريقة makeRequest() لواجهة برمجة تطبيقات الأداة. في حال تحديدها، عليك أيضًا تحديد makeRequestParams.
  • 'auto' - استخدِم الطريقة التي تحدّدها مَعلمة عنوان URL tqrt من عنوان URL لمصدر البيانات. يمكن أن يحتوي tqrt على القيم التالية: "xhr" أو "scriptInjection" أو "makeRequest". إذا كانت السمة tqrt غير متوفرة أو تحتوي على قيمة غير صالحة، تكون القيمة التلقائية هي "xhr" للطلبات الواردة من النطاق نفسه و"scriptInjection" للطلبات على مستوى عدة نطاقات.
• makeRequestParams - [Object] خريطة للمعلَمات لطلب بحث makeRequest(). يتم استخدامها وتكون مطلوبة فقط إذا كانت sendMethod هي 'makeRequest'.

الطُرق

الطريقة	القيمة المعروضة	الوصف
abort()	لا ينطبق	لإيقاف إرسال طلب البحث التلقائي الذي بدأ باستخدام setRefreshInterval().
setRefreshInterval(seconds)	لا ينطبق	لضبط الطلب على استدعاء الطريقة send تلقائيًا كل مدة محددة (عدد الثواني)، بدءًا من أول استدعاء صريح إلى send. seconds هو رقم أكبر من أو يساوي صفر. وفي حال استخدام هذه الطريقة، يجب طلبها قبل استدعاء طريقة send. يمكنك إلغاء هذه الطريقة إما من خلال طلبها مجددًا باستخدام صفر (الخيار التلقائي) أو من خلال طلب abort().
setTimeout(seconds)	لا ينطبق	تحدِّد هذه السياسة عدد الثواني لانتظار استجابة مصدر البيانات قبل إظهار خطأ انتهاء المهلة. seconds هو رقم أكبر من صفر. المهلة التلقائية هي 30 ثانية. ويجب استدعاء هذه الطريقة، في حال استخدامها، قبل طلب الطريقة send.
setQuery(string)	لا ينطبق	لإعداد سلسلة طلب البحث يجب أن تكون قيمة المعلمة string طلب بحث صالحًا. يجب استدعاء هذه الطريقة، في حال استخدامها، قبل استدعاء الطريقة send. مزيد من المعلومات حول لغة الاستعلام
send(callback)	لا ينطبق	يرسل الطلب إلى مصدر البيانات. يجب أن تكون الدالة callback دالة سيتم استدعاؤها عند استجابة مصدر البيانات. ستتلقّى دالة رد الاتصال معلَمة واحدة من النوع google.visualization.QueryResponse.

QueryResponse

ويمثّل ذلك استجابة لتنفيذ طلب بحث كما هو وارد من مصدر البيانات. ويتم تمرير مثيل من هذه الفئة كوسيطة إلى دالة الاستدعاء التي تم ضبطها عند استدعاء Query.send.

الطُرق

الطريقة	القيمة المعروضة	الوصف
getDataTable()	DataTable	تعرض جدول البيانات على النحو الذي يعرضه مصدر البيانات. تعرض null في حال تعذّر تنفيذ طلب البحث ولم يتم عرض أي بيانات.
getDetailedMessage()	سلسلة	عرض رسالة خطأ مفصّلة لطلبات البحث التي تعذّر تنفيذها. وإذا تم تنفيذ الطلب بنجاح، ستعرض هذه الطريقة سلسلة فارغة. الرسالة المعروضة هي رسالة موجَّهة للمطوّرين وقد تحتوي على معلومات فنية، على سبيل المثال "العمود {salary} غير موجود".
getMessage()	سلسلة	عرض رسالة خطأ قصيرة لطلبات البحث التي تعذّر إجراؤها. إذا تم تنفيذ الطلب بنجاح، ستعرض هذه الطريقة سلسلة فارغة. الرسالة التي يتم عرضها هي رسالة قصيرة موجَّهة للمستخدمين النهائيين، على سبيل المثال، "طلب بحث غير صالح" أو "تم رفض الوصول".
getReasons()	مصفوفة من السلاسل	لا تعرض صفيفًا من الإدخالات الإضافية. وكل إدخال هو سلسلة قصيرة تحتوي على رمز خطأ أو تحذير تم عرضه أثناء تنفيذ طلب البحث. الرموز المحتملة: access_denied لا يملك المستخدم أذونات للوصول إلى مصدر البيانات. invalid_query يحتوي طلب البحث المحدّد على خطأ في البنية. data_truncated لم يتم عرض صف بيانات واحد أو أكثر يتطابق مع اختيار طلب البحث بسبب حدود حجم الناتج. (تحذير). timeout لم يستجب الطلب خلال الوقت المتوقّع.
hasWarning()	منطقي	تعرض true إذا كان تنفيذ طلب البحث يحتوي على أي رسائل تحذير.
isError()	منطقي	تعرض true في حال تعذّر تنفيذ طلب البحث، ولا تحتوي الاستجابة على أي جدول بيانات. تعرض <false> إذا كان تنفيذ طلب البحث ناجحًا وكانت الاستجابة تحتوي على جدول بيانات.

عرض رسالة الخطأ

توفّر واجهة برمجة التطبيقات العديد من الوظائف لمساعدتك في عرض رسائل خطأ مخصَّصة للمستخدمين. لاستخدام هذه الدوال، عليك توفير عنصر حاوية على الصفحة (عادةً ما يكون <div>)، وسترسم فيه واجهة برمجة التطبيقات رسالة خطأ منسَّقة. يمكن أن تكون هذه الحاوية عنصر حاوية العرض أو حاوية للأخطاء فقط. إذا حددت عنصر الاحتواء المرئي، سيتم عرض رسالة الخطأ أعلى العرض المرئي. ثم استدع الدالة المناسبة أدناه لعرض رسالة الخطأ أو إزالتها.

جميع الدوال هي دوال ثابتة في مساحة الاسم google.visualization.errors.

يمكن للعديد من التصورات أن تعرض حدث خطأ؛ انظر حدث الخطأ أدناه لمعرفة المزيد عن ذلك.

يمكنك الاطّلاع على مثال عن خطأ مخصّص في مثال على التفاف طلب البحث.

الوظيفة	القيمة المعروضة	الوصف
addError(container, message, opt_detailedMessage, opt_options)	قيمة رقم تعريف السلسلة التي تحدِّد كائن الخطأ الذي تم إنشاؤه. وهي قيمة فريدة على الصفحة، ويمكن استخدامها لإزالة الخطأ أو العثور على العنصر الذي يتضمّنه.	يضيف كتلة عرض خطأ إلى عنصر الصفحة المحدد، مع نص وتنسيق محدد. container - عنصر DOM المطلوب إدراج رسالة الخطأ فيه. إذا تعذّر العثور على الحاوية، ستعرض الدالة خطأ JavaScript. message: رسالة نصية يتم عرضها. opt_detailedMessage - سلسلة اختيارية للرسالة التفصيلية. ويكون هذا النص تلقائيًا نص تمرير الماوس، ولكن يمكن تغييره في السمة opt_options.showInToolTip الموضّحة أدناه. opt_options - كائن اختياري بسمات يضبط خيارات عرض متنوعة للرسالة. تتوفّر الخيارات التالية: showInTooltip - قيمة منطقية تعرض فيها القيمة true الرسالة التفصيلية كنص تلميح فقط، بينما تعرض القيمة "خطأ" الرسالة التفصيلية في نص الحاوية بعد الرسالة القصيرة. القيمة التلقائية هي true. type - سلسلة تصف نوع الخطأ، وتحدد أنماط css التي يجب تطبيقها على هذه الرسالة. القيمتان المسموح بإدراجهما هما "خطأ" و"تحذير". القيمة التلقائية هي "خطأ". style - سلسلة نمط لرسالة الخطأ. سيلغي هذا النمط أي أنماط مطبّقة على نوع التحذير (opt_options.type). مثال: 'background-color: #33ff99; padding: 2px;' القيمة التلقائية هي سلسلة فارغة. removable - قيمة منطقية تعني true أنه يمكن إغلاق الرسالة بنقرة ماوس من جانب المستخدم. القيمة التلقائية هي "خطأ".
addErrorFromQueryResponse(container, response)	قيمة رقم تعريف السلسلة التي تحدّد عنصر الخطأ الذي تم إنشاؤه، أو القيمة "خالية" إذا لم تدل الاستجابة على خطأ. وهي قيمة فريدة على الصفحة، ويمكن استخدامها لإزالة الخطأ أو العثور على العنصر الذي يتضمّنه.	عليك تمرير استجابة طلب بحث وحاوية رسالة خطأ إلى هذه الطريقة: إذا كان ردّ طلب البحث يشير إلى خطأ في طلب البحث، سيتم عرض رسالة خطأ في عنصر الصفحة المحدّد. إذا كانت استجابة طلب البحث فارغة، ستعرض الطريقة خطأ JavaScript. مرِّر QueryResponse إلينا في معالج طلب البحث إلى هذه الرسالة لعرض خطأ. سيحدّد أيضًا نمط العرض المناسب للنوع (خطأ أو تحذير، على غرار addError(opt_options.type)). container - عنصر DOM المطلوب إدراج رسالة الخطأ فيه. إذا تعذّر العثور على الحاوية، ستعرض الدالة خطأ JavaScript. response - هو كائن QueryResponse يتلقّاه معالج طلب البحث استجابةً إلى طلب البحث. وإذا كانت القيمة خالية، ستعرض الطريقة خطأ JavaScript.
removeError(id)	قيمة منطقية: true إذا تمت إزالة الخطأ، أو false في الحالات الأخرى.	يزيل الخطأ المحدد بواسطة رقم التعريف من الصفحة. id - رقم تعريف السلسلة لخطأ تم إنشاؤه باستخدام addError() أو addErrorFromQueryResponse().
removeAll(container)	لا ينطبق	يزيل جميع مجموعات الأخطاء من الحاوية المحددة. إذا لم تكن الحاوية المحددة متوفرة، سيؤدي ذلك إلى حدوث خطأ. container - عنصر DOM الذي يحمل سلاسل الخطأ المطلوب إزالتها. إذا تعذّر العثور على الحاوية، ستعرض الدالة خطأ JavaScript.
getContainer(errorId)	التعامل مع عنصر DOM الذي يتضمن الخطأ المحدَّد، أو التعامل مع القيمة "فارغ" إذا تعذّر العثور عليه	يسترد مؤشرًا لعنصر الحاوية الذي يتضمن الخطأ المحدّد من خلال errorID. errorId - رقم تعريف سلسلة لخطأ تم إنشاؤه باستخدام addError() أو addErrorFromQueryResponse()

الأحداث

تُطلق معظم التصورات الأحداث للإشارة إلى حدوث شيء ما. وبصفتك مستخدمًا للرسم البياني، قد تحتاج غالبًا إلى الاستماع إلى هذه الأحداث. إذا كنت ترمّز ترميز العرض المرئي الخاص بك، ننصحك أيضًا بتشغيل هذه الأحداث بنفسك.

تتيح الطرق التالية للمطوّرين الاستماع إلى الأحداث أو إزالة معالِجات الأحداث الحالية أو تشغيل الأحداث من داخل العرض المرئي.

• google.visualization.events.addListener() وgoogle.visualization.events.addOneTimeListener() لمراقبة الأحداث.
• google.visualization.events.removeListener() لإزالة مستمع حالي.
• إزالة google.visualization.events.removeAllListeners() لجميع أدوات معالجة الرسم البياني
• يؤدي google.visualization.events.trigger() إلى تنشيط حدث.

addListener()

ويمكنك طلب هذه الطريقة للتسجيل من أجل تلقّي الأحداث التي تم إطلاقها من خلال تمثيل بصري مستضاف على صفحتك. وعليك توثيق وسيطات الحدث، إن وُجدت، التي سيتم تمريرها إلى دالة المناولة.

google.visualization.events.addListener(source_visualization,
  event_name, handling_function)

source_visualization

اسم معرِّف لمثيل العرض المرئي المصدر

event_name

اسم سلسلة الحدث المطلوب الاستماع إليه. يجب أن يوثّق التصور الأحداث التي يطلقها.

handling_function

اسم دالة JavaScript المحلية المطلوب طلبها عند تنشيط source_visualization للحدث event_name. سيتم تمرير دالة المناولة أي وسيطات حدث كمَعلمات.

المرتجعات

أداة معالجة المستمعين للمستمِع الجديد ويمكن استخدام المعالج لإزالة هذا المستمع لاحقًا إذا لزم الأمر من خلال استدعاء google.visualization.events.removeListener().

مثال

في ما يلي مثال على التسجيل لتلقّي حدث الاختيار.

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

addOneTimeListener()

هذه السمة مماثلة لترميز addListener()، لكنّها مخصّصة للأحداث التي يجب الاستماع إليها مرة واحدة فقط. لن تؤدي عمليات الطرح اللاحقة للحدث إلى استدعاء وظيفة المناولة.

مثال على الحالات التي يكون فيها ذلك مفيدًا: يؤدي كل سحب إلى طرح حدث ready. إذا كنت تريد أن ينفّذ أول ready رمزك البرمجي، ننصحك باستخدام addOneTimeListener بدلاً من addListener.

removeListener()

ويمكنك استدعاء هذه الطريقة لإلغاء تسجيل أداة معالجة حدث حالية.

google.visualization.events.removeListener(listener_handler)

listener_handler

معالج المستمع المطلوب إزالته، على النحو الذي يعرضه google.visualization.events.addListener().

removeAllListeners()

استدعِ هذه الطريقة لإلغاء تسجيل جميع أدوات معالجة الأحداث لمثيل تصور معين.

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

هو معرِّف لمثيل العرض المرئي المصدر الذي يجب إزالة جميع أدوات معالجة الأحداث منه.

trigger()

يتم استدعاء هذا الإجراء من خلال عناصر التمثيل المرئي. ويمكنك طلب هذه الطريقة من التمثيل البصري لتنشيط حدث يحمل اسمًا عشوائيًا ومجموعة قيم.

google.visualization.events.trigger(source_visualization, event_name,
  event_args)

source_visualization

هو معرِّف لمثيل العرض المرئي المصدر. إذا كنت تستدعي هذه الدالة من داخل طريقة تحدّدها التمثيل البصري للإرسال، يمكنك ببساطة تمرير الكلمة الرئيسية this التي تريدها.

event_name

اسم سلسلة لطلب الحدث. يمكنك اختيار أي قيمة سلسلة تريدها.

event_args

[اختيارية] خريطة لأزواج الاسم/القيمة يتم تمريرها إلى طريقة الاستلام على سبيل المثال: {message: "مرحبًا بكم!", النتيجة: 10، الاسم: "أشرف"}. يمكنك ضبط قيمة فارغة إذا لم تكن هناك حاجة إلى أي أحداث، ويجب أن يكون المستلِم مستعدًا لقبول القيمة "فارغة" لهذه المَعلمة.

مثال

في ما يلي مثال على عرض مرئي يعرض طريقة باسم "select" عند استدعاء طريقة TrueView. ولا يمرّر أي قيم.

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Trigger a select event.
  google.visualization.events.trigger(this, 'select', null);
}

طرق وخصائص التمثيل البصري العادية

يجب أن يعرض كل عرض مرئي المجموعة التالية من الطرق والخصائص المطلوبة والاختيارية. مع ذلك، يُرجى العِلم أنّه لا يتم التحقّق من النوع لفرض هذه المعايير، لذا عليك قراءة المستندات المتعلّقة بكل عرض مرئي.

• المنشئ
• الرسم()
• getAction() [اختيارية]
• getSelection() [اختيارية]
• removeAction() [اختيارية]
• setAction() [اختياري]
• setSelection() [اختيارية]

ملاحظة: تتوفّر هذه الطرق في مساحة الاسم في العرض المرئي، وليس مساحة الاسم google.visualization.

المنشئ

يجب أن تحمل الدالة الإنشائية اسم فئة التصورات، وتعرض مثالاً لتلك الفئة.

visualization_class_name(dom_element)

dom_element

مؤشر إلى عنصر DOM حيث يجب تضمين التمثيل المرئي

مثال

var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

()الرسم

لرسم التصور على الصفحة. ويمكن أن يؤدي ذلك إلى جلب رسم من خادم أو إنشاء رسم على الصفحة باستخدام الرمز المرئي المرتبط. وعليك استدعاء هذه الطريقة في كل مرة تتغير فيها البيانات أو الخيارات. ويجب رسم الكائن داخل عنصر DOM الذي تم إدخاله في الدالة الإنشائية.

draw(data[, options])

البيانات

عنصر DataTable أو DataView يحمل البيانات لاستخدامها في رسم الرسم البياني. ما مِن طريقة عادية لاستخراج DataTable من رسم بياني.

الخيارات

[اختيارية] خريطة لأزواج الاسم/القيمة من الخيارات المخصّصة وتشمل الأمثلة الارتفاع والعرض وألوان الخلفية والترجمة. ويجب أن تتضمّن مستندات العرض المرئي الخيارات المتاحة، كما يجب أن تتيح استخدام الخيارات التلقائية في حال عدم تحديد هذه المَعلمة. يمكنك استخدام البنية الحرفية لكائن JavaScript لتمرير خريطة الخيارات: على سبيل المثال، {x:100, y:200, title:'An Example'}

مثال

chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

getAction()

يتم عرض ذلك بشكل اختياري من خلال المرئيات التي تحتوي على تلميحات وتسمح بإجراءات التلميحات.

عرض كائن إجراء التلميح مع actionID المطلوب.

مثال:

// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');

getSelection()

يتم عرض ذلك بشكل اختياري من خلال المرئيات التي تريد السماح لك بالوصول إلى البيانات المحددة حاليًا في الرسم البياني.

selection_array getSelection()

المرتجعات

selection_array مصفوفة من الكائنات المحددة، تصف كل عنصر منها عنصر بيانات في الجدول الأساسي المستخدَم في إنشاء العرض المرئي (DataView أو DataTable). ويتميز كل كائن بسمة row و/أو column مع فهرس الصف و/أو عمود العنصر المحدد في السمة DataTable الأساسية. إذا كانت السمة row فارغة، يكون التحديد عمودًا، وإذا كانت السمة column فارغة، يكون الاختيار صفًا، وإذا لم يكن كلاهما فارغًا، يكون العنصر عنصر بيانات محدّدًا. يمكنك استدعاء الطريقة DataTable.getValue() للحصول على قيمة العنصر المحدد. يمكن تمرير الصفيف الذي تم استرداده إلى setSelection().

مثال

function myClickHandler(){
  var selection = myVis.getSelection();
  var message = '';

  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      message += '{row:' + item.row + ',column:' + item.column + '}';
    } else if (item.row != null) {
      message += '{row:' + item.row + '}';
    } else if (item.column != null) {
      message += '{column:' + item.column + '}';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

removeAction()

يتم عرض ذلك بشكل اختياري من خلال المرئيات التي تحتوي على تلميحات وتسمح بإجراءات التلميحات.

يزيل كائن إجراء التلميح باستخدام actionID المطلوب من الرسم البياني.

مثال:

// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');

setAction()

يتم عرض ذلك بشكل اختياري من خلال المرئيات التي تحتوي على تلميحات وتسمح بإجراءات التلميحات. تعمل هذه الميزة فقط مع المخطَّطات الأساسية (شريطي، عمودي، خطّي، مساحي، مبعثر، مختلط، فقاعة، دائري، دائري مجوف، شموع، رسم بياني، منطقة متدرجة).

ضبط إجراء تلميح ليتم تنفيذه عندما ينقر المستخدم على نص الإجراء.

setAction(action object)

تستخدم طريقة setAction كائنًا كمعلمة الإجراء الخاصة به. ويجب أن يحدّد هذا الكائن 3 سمات، وهي: id، رقم تعريف الإجراء الذي يتم ضبطه، وtext، النص الذي يجب أن يظهر في التلميح الخاص بالإجراء، وaction الوظيفة التي يجب تشغيلها عندما ينقر المستخدم على نص الإجراء.

يجب ضبط كل إجراءات التلميحات قبل استدعاء طريقة draw() للرسم البياني.

مثال:

// Sets a tooltip action which will pop an alert box on the screen when triggered.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  }
});

ويمكن أن تحدّد الطريقة setAction أيضًا سمتَين إضافيتَين: visible وenabled. يجب أن تكون هذه السمات عبارة عن دوال تعرض قيم boolean تشير إلى ما إذا كان إجراء التلميح مرئيًا و/أو سيتم تفعيله.

مثال:

// The visible/enabled functions can contain any logic to determine their state
// as long as they return boolean values.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  },
  visible: function() {
    return true;
  },
  enabled: function() {
    return true;
  }
});

setSelection()

يمكنك اختياريًا تحديد إدخال بيانات في العرض المرئي، مثل نقطة في رسم بياني مساحي أو شريط في رسم بياني شريطي. عند استدعاء هذه الطريقة، يجب أن يشير التمثيل البصري مرئيًا إلى التحديد الجديد، لكن تنفيذ setSelection() يجب ألا يؤدي إلى تنشيط حدث "select". قد تتجاهل العروض المرئية جزءًا من التحديد. على سبيل المثال، قد يتجاهل الجدول الذي يمكنه عرض الصفوف المختارة فقط عناصر الخلية أو الأعمدة عند تنفيذ setSelection()، أو قد يختار الصف بأكمله.

وفي كل مرة يتم فيها استدعاء هذه الطريقة، يتم إلغاء اختيار جميع العناصر المحدّدة، ويجب تطبيق قائمة الاختيارات الجديدة التي تم تمريرها. ليست هناك طريقة واضحة لإلغاء اختيار عناصر فردية، ولإلغاء اختيار عناصر فردية، يمكنك طلب setSelection() مع العناصر ليظل تم اختيارها، وإلغاء اختيار كل العناصر، أو طلب setSelection() أو setSelection(null) أو setSelection([]).

setSelection(selection_array)

selection_array

مصفوفة من الكائنات، يحتوي كل منها على سمة صف و/أو عمود رقمي. row وcolumn هما رقم الصف أو العمود المستنِد إلى صفر لعنصر في جدول البيانات المطلوب اختياره. لاختيار عمود كامل، اضبط row على "null" (فارغ) ولاختيار صف بأكمله، اضبط column على قيمة فارغة. مثال: تحدد setSelection([{row:0,column:1},{row:1, column:null}]) الخلية في (0,1) والصف 1 بالكامل.

الطرق الثابتة المتنوعة

يتضمّن هذا القسم طرقًا مفيدة مختلفة معروضة في مساحة الاسم google.visualization.

arrayToDataTable()

تستخدم هذه الطريقة صفيفًا ثنائي الأبعاد وتحوله إلى جدول بيانات.

يتم تحديد أنواع بيانات الأعمدة تلقائيًا من خلال البيانات المقدمة. يمكن أيضًا تحديد أنواع بيانات الأعمدة باستخدام الترميز الحرفي للكائن في الصف الأول (صف عنوان العمود) من المصفوفة (أي {label: 'Start Date', type: 'date'}). يمكن أيضًا استخدام أدوار البيانات الاختيارية، ولكن يجب تحديدها بشكل صريح باستخدام الترميز الحرفي للكائنات. ويمكن أيضًا استخدام التدوين الحرفي للكائن مع أي خلية، ما يسمح لك بتحديد كائنات الخلية).

البنية

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

مصفوفة ثنائية الأبعاد، حيث يمثّل كل صف صفًا في جدول البيانات. إذا كانت قيمة opt_firstRowIsData غير صحيحة (القيمة التلقائية)، سيتم تفسير الصف الأول على أنّه تصنيفات عناوين. يتم تفسير أنواع البيانات لكل عمود تلقائيًا من البيانات المقدمة. إذا لم تكن الخلية لا تحتوي على قيمة، حدِّد قيمة فارغة أو فارغة حسب الحاجة.

opt_firstRowIsData

ما إذا كان الصف الأول يحدّد صف عنوان أم لا: إذا كانت القيمة true، يتم افتراض أن جميع الصفوف هي بيانات. وإذا كانت القيمة خاطئة، يُفترض أن يكون الصف الأول صف عنوان، ويتم تخصيص القيم كتصنيفات للأعمدة. القيمة التلقائية هي "خطأ".

المرتجعات

DataTable جديد

أمثلة

يوضح الرمز التالي ثلاث طرق لإنشاء كائن DataTable نفسه:

// Version 1: arrayToDataTable method
var data2 = google.visualization.arrayToDataTable([
  [{label: 'Country', type: 'string'},
   {label: 'Population', type: 'number'},
   {label: 'Area', type: 'number'},
   {type: 'string', role: 'annotation'}],
  ['CN', 1324, 9640821, 'Annotated'],
  ['IN', 1133, 3287263, 'Annotated'],
  ['US', 304, 9629091, 'Annotated'],
  ['ID', 232, 1904569, 'Annotated'],
  ['BR', 187, 8514877, 'Annotated']
]);

// Version 2: DataTable.addRows
var data3 = new google.visualization.DataTable();
data3.addColumn('string','Country');
data3.addColumn('number','Population');
data3.addColumn('number','Area');
data3.addRows([
  ['CN', 1324, 9640821],
  ['IN', 1133, 3287263],
  ['US', 304, 9629091],
  ['ID', 232, 1904569],
  ['BR', 187, 8514877]
]);

// Version 3: DataTable.setValue
var data = new google.visualization.DataTable();
data.addColumn('string','Country');
data.addColumn('number', 'Population');
data.addColumn('number', 'Area');
data.addRows(5);
data.setValue(0, 0, 'CN');
data.setValue(0, 1, 1324);
data.setValue(0, 2, 9640821);
data.setValue(1, 0, 'IN');
data.setValue(1, 1, 1133);
data.setValue(1, 2, 3287263);
data.setValue(2, 0, 'US');
data.setValue(2, 1, 304);
data.setValue(2, 2, 9629091);
data.setValue(3, 0, 'ID');
data.setValue(3, 1, 232);
data.setValue(3, 2, 1904569);
data.setValue(4, 0, 'BR');
data.setValue(4, 1, 187);
data.setValue(4, 2, 8514877);

drawChart()

تنشئ هذه الطريقة رسمًا بيانيًا في استدعاء واحد. وتكمن الفائدة من استخدام هذه الطريقة في أنّها تتطلب تعليمات برمجية أقل إلى حدٍّ ما، ويمكنك إنشاء تسلسل للبيانات وحفظ الرسوم البيانية كسلاسل نصية لإعادة استخدامها. لا تؤدي هذه الطريقة إلى عرض اسم معرِّف على الرسم البياني الذي تم إنشاؤه، لذا لا يمكنك تحديد أدوات معالجة الأحداث لرصد أحداث الرسم البياني.

البنية

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

إمّا سلسلة JSON الحرفية أو كائن JavaScript مع السمات التالية (حسّاسة لحالة الأحرف):

الموقع	النوع	مطلوب	تلقائي	الوصف
chartType	سلسلة	مطلوب	لا ينطبق	اسم فئة التصور. يمكن حذف اسم الحزمة google.visualization في الرسوم البيانية من Google. إذا لم يسبق تحميل مكتبة العروض المرئية المناسبة، ستعمل هذه الطريقة على تحميل المكتبة نيابةً عنك إذا كان هذا العرض تمثيلاً من Google، ويجب تحميل المرئيات التابعة لجهات خارجية بشكل صريح. أمثلة: Table أو PieChart أو example.com.CrazyChart.
containerId	سلسلة	مطلوب	لا ينطبق	رقم تعريف عنصر DOM على صفحتك التي ستستضيف العرض المرئي.
الخيارات	الكائن	اختيارية	لا ينطبق	كائن يصف خيارات التمثيل البصري. يمكنك استخدام تدوين JavaScript الحرفي أو توفير اسم معرِّف للكائن. مثال: "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
dataTable	الكائن	اختيارية	لا ينطبق	هي سمة DataTable تُستخدَم لتعبئة التمثيل البصري. يمكن أن يكون تمثيلاً لسلسلة JSON حرفية لجدول بيانات DataTable، كما هو موضّح أعلاه، أو اسمًا لكائن google.visualization.DataTable معبأ، أو مصفوفة ثنائية الأبعاد، مثل مصفوفة البيانات التي تقبلها في arrayToDataTable(opt_firstRowIsData=false) . يجب تحديد هذه السمة أو السمة dataSourceUrl.
dataSourceUrl	سلسلة	اختيارية	لا ينطبق	طلب بحث لمصدر بيانات لتعبئة بيانات الرسم البياني (على سبيل المثال، جدول بيانات Google). يجب تحديد هذه السمة أو السمة dataTable.
query	سلسلة	اختيارية	لا ينطبق	في حال تحديد dataSourceUrl، يمكنك اختياريًا تحديد سلسلة طلب بحث تشبه SQL باستخدام لغة طلب التصور لفلترة البيانات أو معالجتها.
refreshInterval	العدد	اختيارية	لا ينطبق	كم مرة يجب أن يحدّث التصور مصدر الاستعلام الخاص به بالثواني. لا تستخدِم هذه السمة إلا عند تحديد dataSourceUrl.
عرض	كائن أو مصفوفة	اختيارية	لا ينطبق	تضبط هذه السياسة كائن إعداد DataView الذي يعمل كفلتر على البيانات الأساسية، على النحو المحدّد في المعلَمة dataTable أو dataSourceUrl. يمكنك تمرير سلسلة أو كائن أداة الإعداد DataView ، مثل ذلك الذي يتم عرضه من خلال dataview.toJSON(). مثال: "view": {"columns": [1, 2]} يمكنك أيضًا تمرير مصفوفة من عناصر إعداد DataView، وفي هذه الحالة يتم تطبيق أول DataView في المصفوفة على البيانات الأساسية لإنشاء جدول بيانات جديد، ويتم تطبيق DataView الثاني على جدول البيانات الناتج عن تطبيق DataView الأول، وهكذا.

أمثلة

تنشئ مخططًا جدوليًا استنادًا إلى مصدر بيانات جدول بيانات، وتتضمن الاستعلام SELECT A,D WHERE D > 100 ORDER BY D

<script type="text/javascript">
  google.charts.load('current');  // Note: No need to specify chart packages.
  function drawVisualization() {
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",
      "query":"SELECT A,D WHERE D > 100 ORDER BY D",
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true
      }
   });
 }
google.charts.setOnLoadCallback(drawVisualization);
</script>

ينشئ المثال التالي الجدول نفسه، ولكنه ينشئ DataTable على الجهاز:

<script type='text/javascript'>
  google.charts.load('current');
  function drawVisualization() {
    var dataTable = [
      ["Country", "Population Density"],
      ["Indonesia", 117],
      ["China", 137],
      ["Nigeria", 142],
      ["Pakistan", 198],
      ["India", 336],
      ["Japan", 339],
      ["Bangladesh", 1045]
    ];
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataTable": dataTable,
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true,
      }
    });
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

يعرض هذا المثال تمثيل سلسلة JSON للرسم البياني، والذي يُحتمل أنّك حمَّلته من ملف:

<script type="text/javascript">
  google.charts.load('current');
  var myStoredString = '{"containerId": "visualization_div",' +
    '"dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",' +
    '"query":"SELECT A,D WHERE D > 100 ORDER BY D",' +
    '"refreshInterval": 5,' +
    '"chartType": "Table",' +
    '"options": {' +
    '   "alternatingRowStyle": true,' +
    '   "showRowNumber" : true' +
    '}' +
  '}';
  function drawVisualization() {
    google.visualization.drawChart(myStoredString);
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

drawToolbar()

هذا هو الدالة الإنشائية لعنصر شريط الأدوات الذي يمكن إرفاقه بالعديد من التصورات. ويسمح شريط الأدوات هذا للمستخدم بتصدير بيانات العروض المرئية بتنسيقات مختلفة، أو توفير نسخة قابلة للتضمين من العرض المرئي لاستخدامها في أماكن مختلفة. راجِع صفحة شريط الأدوات للحصول على مزيد من المعلومات ومثال على الرمز البرمجي.