مرجع واجهة برمجة تطبيقات Google المرئي

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

ملاحظة: مساحة الاسم لواجهة برمجة التطبيقات في Google المرئية هي google.visualization.*

1. فئة جدول البيانات
2. فئة DataView
3. فئة "مخطِّط الرسم البياني"
4. فئة "محرِّر الرسم البياني"
5. طرق معالجة البيانات
   1. group()
   2. join()
6. أدوات التنسيق
   1. ArrowFormat
   2. التنسيق الشريطي
   3. ColorFormat
   4. تنسيق التاريخ
   5. NumberFormat
   6. PatternFormat
7. فئة GadgetHelper
8. فئات طلب البحث
   1. طلب بحث
   2. QueryResponse
9. خطأ في عرض الصف
10. الأحداث
    1. google.Visualization.events.addListener()
    2. google.visibleization.events.addOneTimeListener()
    3. google.Visualization.events.removeListener()
    4. google.visibleization.events.removeAllListeners()
    5. google.visibleization.events.trigger()
11. خصائص وطُرق التمثيل البصري العادية
    1. المنشئ
    2. draw()
    3. getAction()
    4. getSelection()
    5. removeAction()
    6. setAction()
    7. setSelection()
12. طرق متنوعة متنوعة
    1. arrayToDataTable()
    2. drawChart()
    3. drawtoolbar()

ملاحظة حول المصفوفات

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

data = ['a','b','c', ,]; // BAD
data = ['a','b','c'];   // OK
data = ['a','b', ,'d']; // Also OK. The third value is undefined.

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

يمثل جدول قيم ثنائي الأبعاد قابل للتغيير. لإنشاء نسخة للقراءة فقط من 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'}]
]);

هل يجب عليّ إنشاء جدول البيانات في JavaScript أم في الترميز الحرفي للكائن؟

يمكنك إنشاء DataTable إما عن طريق استدعاء دالة إنشاء بدون معلمات ثم إضافة قيم عن طريق استدعاء الطرق addColumn()/ addRows() المدرجة أدناه، أو عن طريق تمرير كائن JavaScript حرفي معبأ لإعداده. يتم وصف كلتا الطريقتين أدناه. أَيُّ خِيَارْ يَجِبُ اسْتِخْدَامُهُ؟

• إنّ إنشاء جدول وملؤه بجافا سكريبت عن طريق طلب addColumn() وaddRow() وaddRows() هو رمز قابل للقراءة جدًا. وتكون هذه الطريقة مفيدة عند إدخال الرمز يدويًا. وهو أبطأ من استخدام الترميز الحرفي للكائنات (كما هو موضّح في ما يلي)، ولكن في الجداول الأصغر (مثل 1,000 خلية)، قد لا تلاحظ اختلافًا كبيرًا.
• يكون التعريف المباشر لكائن DataTable باستخدام الترميز الحرفي للعنصر أسرع بشكل ملحوظ في الجداول الكبيرة. ومع ذلك، قد يكون من الصعب استخدام هذه البنية بشكل صحيح، لذلك ننصحك باستخدام هذه الخاصية إذا كان بإمكانك إنشاء البنية الحرفية للكائن في الرمز، ما يقلّل من احتمال حدوث أخطاء.

 

الطُرق

الطريقة	قيمة الإرجاع	الوصف
addColumn(type, opt_label, opt_id) أو addColumn(description_object)	الرقم	لإضافة عمود جديد إلى جدول البيانات، وعرض فهرس العمود الجديد. يتم تخصيص قيمة null لجميع خلايا العمود الجديد. تشتمل هذه الطريقة على توقيعين: يحتوي التوقيع الأول على المعلمات التالية: type - سلسلة بنوع البيانات الخاص بقيم العمود. يمكن أن يكون النوع واحدًا مما يلي: 'string', 'number', 'boolean', 'date', 'datetime', و'timeofday'. opt_label - [اختيارية] سلسلة تتضمّن تصنيف العمود. ويتم عادةً عرض تصنيف العمود كجزء من التمثيل البصري، مثلاً كعنوان في عمود في الجدول أو كتسمية توضيحية في رسم بياني دائري. في حال عدم تحديد أي قيمة، يتم تحديد سلسلة فارغة. opt_id - [اختيارية] سلسلة ذات معرّف فريد للعمود. إذا لم يتم تحديد أي قيمة، يتم تعيين سلسلة فارغة. يتضمّن التوقيع الثاني معلّمة كائن واحدة مع الأعضاء التاليين: type - سلسلة تصف نوع بيانات العمود. نفس قيم type الواردة أعلاه. label - [سلسلة اختيارية] تصنيف للعمود id - [اختيارية، سلسلة] رقم تعريف للعمود. role - [اختيارية، سلسلة] دور للعمود pattern - [سلسلة اختيارية] عبارة عن سلسلة تنسيق رقم (أو تاريخ) تحدد كيفية عرض قيمة العمود. يُرجى الاطِّلاع أيضًا على: getColumnId وgetColumnLabel وgetColumnType وinsertColumn وgetColumnRole.
addRow(opt_cellArray)	الرقم	لإضافة صف جديد إلى جدول البيانات، وعرض فهرس الصف الجديد. opt_cellArray [اختيارية] كائن صف، في ترميز JavaScript، لتحديد البيانات للصف الجديد. وفي حال عدم تضمين هذه المعلّمة، ستضيف هذه الطريقة صفًا جديدًا فارغًا إلى نهاية الجدول. هذه المعلمة عبارة عن مصفوفة من قيم الخلايا: إذا كنت تريد تحديد قيمة لخلية فقط، فامنح قيمة الخلية فقط (مثل 55 أو 'hello'); إذا كنت تريد تحديد قيمة منسقة و/أو خصائص للخلية، فاستخدم كائن الخلية (على سبيل المثال، {v:55, f:'خمسة وخمسون'}). يمكنك مزج القيم البسيطة وكائنات الخلايا في استدعاء الطريقة نفسها). استخدِم null أو إدخال مصفوفة فارغًا لخلية فارغة. أمثلة: 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.
addRows(numOrArray)	الرقم	لإضافة صفوف جديدة إلى جدول البيانات، وعرض فهرس آخر صف تمت إضافته. ويمكنك استدعاء هذه الطريقة لإنشاء صفوف فارغة جديدة، أو باستخدام البيانات المستخدمة لتعبئة الصفوف، كما هو موضّح أدناه. numOrArray - إما رقمًا أو مصفوفة: Number - رقم يحدد عدد الصفوف الجديدة غير المعبأة المراد إضافتها. مصفوفة - مصفوفة من كائنات الصفوف المُستخدمة لتعبئة مجموعة من الصفوف الجديدة. يمثل كل صف كائنًا كما هو موضّح في addRow(). استخدِم null أو إدخال مصفوفة فارغًا لخلية فارغة. مثال: 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. ]); راجع أيضًا: insertRows
clone()	جدول البيانات	لعرض نسخة من جدول البيانات. والنتيجة هي نسخة عميقة من جدول البيانات باستثناء خصائص الخلية وخصائص الصف وخصائص الجدول وخصائص العمود، وهي نُسخ ضحلة، وهذا يعني أن الخصائص غير الأولية يتم نسخها كمرجع، ولكن يتم نسخ الخصائص الأساسية حسب القيمة.
getColumnId(columnIndex)	سلسلة	لعرض معرّف عمود معيّن تم تحديده من خلال فهرس العمود في الجدول الأساسي. بالنسبة إلى جداول البيانات التي يتم استردادها من خلال طلبات البحث، يتم تحديد معرّف العمود بواسطة مصدر البيانات، ويمكن استخدامه للإشارة إلى الأعمدة عند استخدام لغة طلب البحث. يُرجى الاطِّلاع أيضًا على: Query.setQuery
getColumnIndex(columnIdentifier)	سلسلة، رقم	لعرض فهرس عمود معيّن تم تحديده من خلال فهرس العمود أو رقم التعريف أو التصنيف إذا كان متوفرًا في هذا الجدول، وبخلاف ذلك -1. عندما تكون columnIdentifier سلسلة، يُستخدم للعثور على العمود حسب رقم تعريفه أولاً، ثم حسب تصنيفه. يُرجى الاطِّلاع أيضًا على: getColumnId و getColumnLabel
getColumnLabel(columnIndex)	سلسلة	لعرض تصنيف عمود معين تم تحديده عن طريق فهرس العمود في الجدول الأساسي. يتم عادةً عرض تصنيف العمود كجزء من التمثيل البصري. على سبيل المثال، يمكن عرض تصنيف العمود كرأس عمود في الجدول، أو كتسمية توضيحية في رسم بياني دائري. بالنسبة إلى جداول البيانات التي يتم استردادها من خلال طلبات البحث، يتم ضبط تصنيف العمود من خلال مصدر البيانات أو من خلال العبارة label في لغة طلب البحث. يُرجى الاطِّلاع أيضًا على: setColumnLabel
getColumnPattern(columnIndex)	سلسلة	لعرض نمط التنسيق المستخدم لتنسيق قيم العمود المحدد. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). بالنسبة إلى جداول البيانات التي يتم استردادها من خلال طلبات البحث، يتم تحديد نمط العمود بواسطة مصدر البيانات، أو من خلال عبارة format في لغة طلب البحث. مثال على النمط هو '#,##0.00'. للحصول على مزيد من المعلومات حول الأنماط، يمكنك الاطّلاع على مرجع لغة طلب البحث.
getColumnProperties(columnIndex)	اعتراض	لعرض خريطة بكل الخصائص للعمود المحدد. لاحظ أنه يتم عرض كائن الخصائص من خلال الرجوع، لذا يؤدي تغيير القيم في العنصر الذي تم استرداده إلى تغييرها في DataTable. columnIndex هو الفهرس الرقمي للعمود المطلوب استرداد خصائصه.
getColumnProperty(columnIndex, name)	تلقائي	لعرض قيمة الخاصية المسماة أو null إذا لم يتم تعيين هذه الخاصية للعمود المحدد. يختلف نوع العرض حسب الموقع الإلكتروني. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). name هو اسم الخاصية، كسلسلة. يُرجى الاطّلاع أيضًا على: setColumnProperty setColumnProperties
getColumnRange(columnIndex)	اعتراض	لعرض القيم الدنيا والقصوى للقيم في عمود محدد. الكائن المعروض يحتوي على الخاصيتين min وmax. إذا كان النطاق لا يتضمن أي قيم، سيحتوي min وmax على null. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الأعمدة التي يتم عرضها باستخدام طريقة getNumberOfColumns().
getColumnRole(columnIndex)	سلسلة	لعرض دور العمود المحدّد.
getColumnType(columnIndex)	سلسلة	لعرض نوع عمود معين تم تحديده بواسطة فهرس العمود. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). يمكن أن يكون نوع العمود المعروض واحدًا مما يلي: 'string', 'number', 'boolean', 'date', 'datetime', و'timeofday'
getDistinctValues(columnIndex)	مصفوفة من الكائنات	لعرض القيم الفريدة في عمود معيّن، تصاعديًا. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). نوع الكائنات المعروضة هو النوع نفسه الذي تم عرضه باستخدام طريقة getValue.
getFilteredRows(filters)	مصفوفة من الكائنات	لعرض فهارس الصفوف للصفوف التي تتطابق مع جميع الفلاتر المحددة. ويتم عرض الفهارس بشكل تصاعدي. يمكن استخدام ناتج هذه الطريقة كإدخال إلى DataView.setRows() لتغيير المجموعة المعروضة من الصفوف في التمثيل البصري. filters - مصفوفة من العناصر تصف قيمة خلية مقبولة. ويتم عرض فهرس الصف بهذه الطريقة إذا كان يتطابق مع جميع الفلاتر المحدّدة. كل فلتر هو كائن له خاصية column رقمية تحدّد فهرس العمود في الصف المطلوب تقييمه، بالإضافة إلى أي مما يلي: الخاصية value بقيمة يجب أن تتطابق تمامًا مع الخلية في العمود المحدّد. يجب أن تكون القيمة من النوع نفسه للعمود، أو أحد الخاصيتين التاليتين أو كلتيهما، النوع نفسه للعمود الذي تتم تصفيته: minValue - الحد الأدنى لقيمة الخلية. يجب أن تكون قيمة الخلية في العمود المحدّد أكبر من أو تساوي هذه القيمة. maxValue - الحد الأقصى لقيمة الخلية. يجب أن تكون قيمة الخلية في العمود المحدّد أقل من أو تساوي هذه القيمة. تعني القيمة الفارغة أو غير المحددة للسمة minValue (أو maxValue) أنه لن يتم فرض الحد الأدنى (أو الأعلى) من النطاق. تحدد الخاصية الاختيارية الأخرى test الوظيفة التي سيتم دمجها مع تصفية القيمة أو النطاق. ويتم استدعاء الدالة باستخدام قيمة الخلية وفهارس الصف والعمود وجدول البيانات. ويجب أن تعرض القيمة "false" إذا كان يجب استبعاد الصف من النتيجة. مثال: تعرض getFilteredRows([{column: 3, value: 42}, {column: 2, minValue: 'bar', maxValue: 'foo'}, {column: 1, test: (value, rowId, columnId, datatable) => { return value == "baz"; }}]) مصفوفة تحتوي على فهارس جميع الصفوف التي يتضمّن العمود الرابع (فهرس العمود 3) الخاص بها الترتيب 42 بالضبط، والعمود الثالث (فهرس العمود 2) بين 'bar' و'foo' (حصريًا).
getFormattedValue(rowIndex, columnIndex)	سلسلة	لعرض القيمة المنسقة للخلية في فهارس الأعمدة والصفوف المحددة. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون ColumnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). للحصول على مزيد من المعلومات عن تنسيق قيم الأعمدة، يمكنك الاطّلاع على مرجع لغة طلب البحث. يُرجى الاطِّلاع أيضًا على: setFormattedValue
getNumberOfColumns()	الرقم	لعرض عدد الأعمدة في الجدول.
getNumberOfRows()	الرقم	لعرض عدد الصفوف في الجدول.
getProperties(rowIndex, columnIndex)	اعتراض	لعرض خريطة بجميع الخصائص للخلية المحددة. لاحظ أن كائن الخصائص يتم عرضه كمرجع، لذا يؤدي تغيير القيم في الكائن المسترد إلى تغييرها في DataTable. rowIndex هو فهرس صف الخلية. columnIndex هو فهرس عمود الخلية.
getProperty(rowIndex, columnIndex, name)	تلقائي	لعرض قيمة الخاصية المسماة أو null إذا لم يتم تعيين هذه الخاصية للخلية المحددة. يختلف نوع العرض حسب الموقع الإلكتروني. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). name عبارة عن سلسلة تحمل اسم الخاصية. يُرجى الاطّلاع أيضًا على: setCell setProperties setProperty
getRowProperties(rowIndex)	اعتراض	لعرض خريطة بكل الخصائص للصف المحدّد. لاحظ أنه يتم عرض كائن الخصائص من خلال الرجوع، لذا يؤدي تغيير القيم في العنصر الذي تم استرداده إلى تغييرها في DataTable. rowIndex هو فهرس الصف لاسترداد خصائصه.
getRowProperty(rowIndex, name)	تلقائي	لعرض قيمة الخاصية المُسمّاة أو null إذا لم يتم ضبط هذه الخاصية للصف المحدّد. يختلف نوع العرض حسب الموقع الإلكتروني. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). name عبارة عن سلسلة تحمل اسم الخاصية. يُرجى الاطِّلاع أيضًا على: setRowProperty setRowProperties
getSortedRows(sortColumns)	مصفوفة الأرقام	لعرض نسخة مصنفة من الجدول بدون تعديل ترتيب البيانات الأساسية. لترتيب البيانات الأساسية بشكل دائم، يُرجى الاتصال بالرقم sort(). يمكنك تحديد الترتيب بعدة طرق وفقًا للنوع الذي تمرِّر به المعلمة sortColumns: يحدد رقم واحد فهرس العمود للتصنيف بحسبه. سيكون الترتيب تصاعديًا. مثال: سيرتب sortColumns(3) حسب العمود الرابع، تصاعديًا. كائن واحد يحتوي على رقم فهرس العمود للترتيب حسب، بالإضافة إلى خاصية منطقية اختيارية desc. في حال ضبط desc على "صحيح"، سيتم ترتيب العمود المحدّد تنازليًا، وإلا يتم الترتيب تصاعديًا. أمثلة: سيرتب sortColumns({column: 3}) حسب العمود الرابع تصاعديًا، وسيتم ترتيب sortColumns({column: 3, desc: true}) حسب العمود الرابع بالترتيب التنازلي. مصفوفة من الأرقام من فهارس الأعمدة المطلوب ترتيبها. الرقم الأول هو العمود الأساسي الذي سيتم الترتيب من خلاله، والرقم الثاني هو العمود الثانوي، وهكذا. وهذا يعني أنه عند تساوي قيمتين في العمود الأول، تتم مقارنة القيم في العمود التالي، وهكذا. مثال: سيتم ترتيب sortColumns([3, 1, 6]) أولاً حسب العمود الرابع (بترتيب تصاعدي)، ثم حسب العمود الثاني (بترتيب تصاعدي)، ثم حسب العمود السابع (بترتيب تصاعدي). مصفوفة من العناصر، يحتوي كل منها على رقم فهرس العمود المطلوب الترتيب حسبه، بالإضافة إلى خاصية منطقية اختيارية desc. في حال ضبط desc على "صحيح"، سيتم ترتيب العمود المحدّد تنازليًا (التلقائي هو الترتيب التصاعدي). الكائن الأول هو العمود الأساسي الذي يتم الترتيب من خلاله، والثاني هو العمود الثانوي، وهكذا. وهذا يعني أنه عند تساوي قيمتين في العمود الأول، تتم مقارنة القيم في العمود التالي وهكذا. مثال: سيتم ترتيب sortColumn([{column: 3}, {column: 1, desc: true}, {column: 6, desc: true}]) أولاً حسب العمود الرابع (بترتيب تصاعدي)، ثم العمود 2 بترتيب تنازلي، ثم العمود 7 بترتيب تنازلي. القيمة المعروضة عبارة عن مصفوفة من الأرقام، كل رقم عبارة عن فهرس لصف DataTable. سيؤدي التكرار في الصفوف DataTable حسب ترتيب الصفيف المعروض إلى ترتيب الصفوف حسب sortColumns المحدّدة. يمكن استخدام الناتج كإدخال إلى DataView.setRows() لتغيير مجموعة الصفوف المعروضة في التمثيل البصري بسرعة. يُرجى العِلم أنّ عملية الترتيب تضمن أن تكون ثابتة: هذا يعني أنه في حال الترتيب على قيم متساوية في صفَين، ستعرض عملية الترتيب نفسها الصفوف بالترتيب نفسه في كل مرة. يُرجى الاطِّلاع أيضًا على: sort مثال: للتكرار في الصفوف مرتبة حسب العمود الثالث، استخدم: var rowInds = data.getSortedRows([{column: 2}]); for (var i = 0; i < rowInds.length; i++) { var v = data.getValue(rowInds[i], 2); }
getTableProperties	اعتراض	لعرض خريطة بكل خصائص الجدول.
getTableProperty(name)	تلقائي	لعرض قيمة الخاصية المسماة أو null إذا لم يتم تعيين هذه الخاصية للجدول. يختلف نوع العرض حسب الموقع الإلكتروني. name عبارة عن سلسلة تحمل اسم الخاصية. يُرجى الاطّلاع أيضًا على: setTableProperties setTableProperty
getValue(rowIndex, columnIndex)	اعتراض	لعرض قيمة الخلية في فهارس الصفوف والأعمدة المحددة. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). ويعتمد نوع القيمة المعروضة على نوع العمود (يُرجى الاطّلاع على getColumnType): إذا كان نوع العمود هو "سلسلة"، تكون القيمة سلسلة. إذا كان نوع العمود "رقم"، تكون القيمة رقمًا. إذا كان نوع العمود "منطقي"، تكون القيمة منطقية. إذا كان نوع العمود هو "date" أو "datetime"، تكون القيمة هي كائن التاريخ. إذا كان نوع العمود هو "timeofday"، تكون القيمة عبارة عن مصفوفة من أربعة أرقام: [ساعة، دقيقة، ثانية، مللي ثانية]. إذا كانت قيمة الخلية قيمة فارغة، فإنها تعرض null.
insertColumn(columnIndex, type [,label [,id]])	لا ينطبق	إدراج عمود جديد في جدول البيانات في الفهرس المحدد. ويتم تحويل جميع الأعمدة الحالية في الفهرس المحدّد أو بعده إلى فهرس أعلى. columnIndex عبارة عن رقم يتضمن الفهرس المطلوب للعمود الجديد. يجب أن تكون type سلسلة بنوع البيانات الخاص بقيم العمود. ويمكن أن يكون النوع واحدًا مما يلي: 'string', 'number', 'boolean', 'date', 'datetime', و 'timeofday'. يجب أن تكون السمة label سلسلة تحمل اسم العمود. يتم عادةً عرض تصنيف العمود كجزء من التمثيل البصري، مثلاً كعنوان في عمود في الجدول أو كتسمية توضيحية في رسم بياني دائري. إذا لم يتم تحديد أي قيمة، يتم تعيين سلسلة فارغة. يجب أن تكون id سلسلة بمعرّف فريد للعمود. إذا لم يتم تحديد أي قيمة، يتم تعيين سلسلة فارغة. راجع أيضًا: addColumn
insertRows(rowIndex, numberOrArray)	لا ينطبق	إدراج عدد الصفوف المحدّد في فهرس الصفوف المحدّد. rowIndex هو رقم الفهرس حيث يمكن إدراج الصفوف الجديدة. ستتم إضافة الصفوف بدءًا من رقم الفهرس المحدّد. numberOrArray عبارة عن عدد من الصفوف الجديدة الفارغة أو المراد إضافتها أو مصفوفة من صف واحد أو أكثر تمت تعبئته لإضافته إلى الفهرس. يمكنك الاطّلاع على addRows() لمعرفة بنية إضافة مصفوفة من عناصر الصفوف. راجع أيضًا: addRows
removeColumn(columnIndex)	لا ينطبق	إزالة العمود في الفهرس المحدد. يجب أن يكون columnIndex رقمًا مع فهرس عمود صالح. راجع أيضًا: إزالة الأعمدة
removeColumns(columnIndex, numberOfColumns)	لا ينطبق	إزالة العدد المحدد للأعمدة بدءًا من العمود في الفهرس المحدد. numberOfColumns هو عدد الأعمدة المطلوب إزالتها. يجب أن يكون columnIndex رقمًا مع فهرس عمود صالح. راجع أيضًا: removeColumn
removeRow(rowIndex)	لا ينطبق	إزالة الصف في الفهرس المحدد. يجب أن يكون rowIndex رقمًا مع فهرس صف صالح. راجع أيضًا: removeRows
removeRows(rowIndex, numberOfRows)	لا ينطبق	إزالة عدد الصفوف المحدد بدءًا من الصف في الفهرس المحدد. numberOfRows هو عدد الصفوف المطلوب إزالتها. يجب أن يكون rowIndex رقمًا مع فهرس صف صالح. راجع أيضًا: removeRow
setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]])	لا ينطبق	لتعيين قيمة و/أو قيمة منسقة و/أو خصائص خلية. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). value [اختيارية] هي القيمة المخصَّصة للخلية المحدَّدة. لتجنّب استبدال هذه القيمة، اضبط هذه المعلمة على undefined. لمحو هذه القيمة، اضبطها على null. ويعتمد نوع القيمة على نوع العمود (يُرجى الاطّلاع على getColumnType()): إذا كان نوع العمود هو "سلسلة"، يجب أن تكون القيمة سلسلة. إذا كان نوع العمود "رقم"، يجب أن تكون القيمة رقمًا. إذا كان نوع العمود "منطقي"، يجب أن تكون القيمة منطقية. إذا كان نوع العمود هو "date" أو "datetime"، يجب أن تكون القيمة كائن "التاريخ". إذا كان نوع العمود هو "timeofday"، يجب أن تكون القيمة مصفوفة من أربعة أرقام: [ساعة، دقيقة، ثانية، مللي ثانية]. formattedValue [اختيارية] عبارة عن سلسلة بتنسيق القيمة كسلسلة. لتجنّب استبدال هذه القيمة، اضبط هذه المعلمة على undefined. لمحو هذه القيمة واجعل واجهة برمجة التطبيقات تطبّق التنسيق التلقائي على value حسب الحاجة، اضبطها على null. لضبط قيمة فارغة منسقة بشكل صريح، اضبطها على سلسلة فارغة. وتستخدم التمثيلات البصرية عادةً القيمة المنسّقة لعرض تصنيفات القيم. على سبيل المثال، يمكن أن تظهر القيمة المنسّقة كنص تصنيف ضمن رسم بياني دائري. properties [اختيارية] عبارة عن Object (خريطة اسم/قيمة) تحتوي على خصائص إضافية لهذه الخلية. لتجنّب استبدال هذه القيمة، اضبط هذه المعلمة على undefined. لمحو هذه القيمة، اضبطها على null. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. يُرجى الاطِّلاع أيضًا على: setValue(), setFormattedValue(), setProperty(), setProperties().
setColumnLabel(columnIndex, label)	لا ينطبق	لتعيين تصنيف العمود. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). label عبارة عن سلسلة بالتصنيف المراد تعيينه للعمود. ويتم عادةً عرض تصنيف العمود كجزء من التمثيل البصري. على سبيل المثال، يمكن عرض تصنيف العمود كرأس عمود في الجدول، أو كتصنيف التسمية التوضيحية في الرسم البياني الدائري. راجع أيضًا: getColumnLabel
setColumnProperty(columnIndex, name, value)	لا ينطبق	لتعيين موقع على عمود واحد. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). name عبارة عن سلسلة تحمل اسم الخاصية. value هي قيمة من أي نوع لتعيينها للخاصية المُسمّاة المحددة للعمود المحدد. يُرجى الاطِّلاع أيضًا على:setColumnProperties getColumnProperty
setColumnProperties(columnIndex, properties)	لا ينطبق	لتعيين خصائص أعمدة متعددة. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). properties هي Object (خريطة الاسم/القيمة) مع خصائص إضافية لهذا العمود. إذا تم تحديد null، ستتم إزالة جميع الخصائص الإضافية للعمود. يُرجى الاطّلاع أيضًا على: setColumnProperty getColumnProperty
setFormattedValue(rowIndex, columnIndex, formattedValue)	لا ينطبق	لتعيين القيمة المنسقة للخلية. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). formattedValue عبارة عن سلسلة بتنسيق القيمة للعرض. لمحو هذه القيمة وجعل واجهة برمجة التطبيقات تطبّق التنسيق التلقائي على قيمة الخلية حسب الحاجة، اضبطها على formattedValue null، ولضبط قيمة فارغة بالتنسيق الصريح، اضبطها على سلسلة فارغة. يُرجى الاطِّلاع أيضًا على: getFormattedValue
setProperty(rowIndex, columnIndex, name, value)	لا ينطبق	لتعيين خاصية خلية. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). name عبارة عن سلسلة تحمل اسم الخاصية. value هي قيمة من أي نوع لتعيينها إلى الخاصية المحدّدة المحدّدة من الخلية المحدّدة. يُرجى الاطّلاع أيضًا على: setCell setProperties getProperty
setProperties(rowIndex, columnIndex, properties)	لا ينطبق	لتعيين خصائص خلايا متعددة. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). properties هي Object (خريطة الاسم/القيمة) مع خصائص إضافية لهذه الخلية. إذا تم تحديد null، ستتم إزالة جميع الخصائص الإضافية للخلية. يُرجى الاطّلاع أيضًا على: setCell setProperty getProperty
setRowProperty(rowIndex, name, value)	لا ينطبق	لضبط خاصية صف. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). name عبارة عن سلسلة تحمل اسم الخاصية. value هي قيمة من أي نوع لتعيينها للسمة المحدّدة المحدّدة للصف المحدّد. يُرجى الاطِّلاع أيضًا على: setRowProperties getRowProperty
setRowProperties(rowIndex, properties)	لا ينطبق	لتعيين خصائص صفوف متعددة. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). properties هي Object (خريطة الاسم/القيمة) مع خصائص إضافية لهذا الصف. وإذا تم تحديد null، ستتم إزالة جميع الخصائص الإضافية للصف. يُرجى الاطِّلاع أيضًا على: setRowProperty getRowProperty
setTableProperty(name, value)	لا ينطبق	لتعيين خاصية جدول واحدة. وتتيح بعض التمثيلات البصرية خصائص الجدول أو الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. name عبارة عن سلسلة تحمل اسم الخاصية. value هي قيمة من أي نوع لتعيينها إلى الخاصية المحدّدة المحدّدة في الجدول. يُرجى الاطّلاع أيضًا على: setTableProperties getTableProperty
setTableProperties(properties)	لا ينطبق	لتعيين خصائص جدول متعددة. وتتيح بعض التمثيلات البصرية خصائص الجدول أو الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة. properties هي Object (خريطة الاسم/القيمة) مع خصائص إضافية للجدول. إذا تم تحديد null، ستتم إزالة جميع خصائص الجدول الإضافية. يُرجى الاطِّلاع أيضًا على: setTableProperty getTableProperty
setValue(rowIndex, columnIndex, value)	لا ينطبق	لتعيين قيمة خلية. بالإضافة إلى استبدال أي قيمة خلية حالية، ستمحو هذه الطريقة أيضًا أي قيمة وخصائص منسَّقة للخلية. يجب أن يكون rowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows(). يجب أن يكون columnIndex رقمًا أكبر من أو يساوي الصفر، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). لا تسمح لك هذه الطريقة بضبط قيمة منسَّقة لهذه الخلية. لإجراء ذلك، يمكنك استدعاء setFormattedValue(). value هي القيمة المعينة للخلية المحددة. ويعتمد نوع القيمة المعروضة على نوع العمود (يُرجى الاطّلاع على السمة getColumnType): إذا كان نوع العمود هو "سلسلة"، يجب أن تكون القيمة سلسلة. إذا كان نوع العمود "رقم"، يجب أن تكون القيمة رقمًا. إذا كان نوع العمود "منطقي"، يجب أن تكون القيمة منطقية. إذا كان نوع العمود هو "date" أو "datetime"، يجب أن تكون القيمة كائن "التاريخ". إذا كان نوع العمود هو "timeofday"، يجب أن تكون القيمة مصفوفة من أربعة أرقام: [ساعة، دقيقة، ثانية، مللي ثانية]. بالنسبة إلى أي نوع عمود، يمكن ضبط القيمة على null. راجِع أيضًا: setCell و setFormattedValue و setProperty و setProperties
sort(sortColumns)	لا ينطبق	لترتيب الصفوف، وفقًا لأعمدة الترتيب المحددة. ويتم تعديل DataTable بهذه الطريقة. يمكنك الاطّلاع على getSortedRows() للحصول على وصف لتفاصيل الترتيب. لا تعرض هذه الطريقة البيانات المرتبة. يُرجى الاطِّلاع أيضًا على: getSortedRows مثال: للترتيب حسب العمود الثالث ثم حسب العمود الثاني، استخدِم: data.sort([{column: 2}, {column: 1}]);
toJSON()	سلسلة	لعرض تمثيل JSON لـ DataTable الذي يمكن تمريره إلى المُنشئ DataTable. على سبيل المثال: {"cols":[{"id":"Col1","label":"","type":"date"}], "rows":[ {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]}, {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]} ] }

تنسيق معلمة البيانات الحرفية بلغة المُنشئ

يمكنك إعداد DataTable عن طريق تمرير كائن حرفي لسلسلة JavaScript إلى معلمة 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: 'number' ولكن سيتم التعبير عن القيمة نفسها، كرقمية، على النحو التالي: v: 42

موقع إلكتروني واحد (cols)

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

• type [مطلوبة] تشير هذه السمة إلى نوع البيانات في العمود. تتوافق مع قيم السلسلة التالية (تشمل الأمثلة الخاصية v: التي تم وصفها لاحقًا):
  • "منطقي" - قيمة منطقية جافا سكريبت ("صحيح" أو "خطأ"). مثال على القيمة: v:'true'
  • 'number' - قيمة رقم جافا سكريبت. أمثلة على القيم: v:7، v:3.14، v:-55
  • "string" - قيمة سلسلة جافا سكريبت. مثال على القيمة: 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، من المحتمل أن يتم عرض النمط الذي حدّدته في تلك الفقرة ضمن هذه القيمة. والمعايير المقترَحة للنمط هي وحدة العناية المركزة وحدة وحدة عشرية و 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 على مستوى الجدول هي خريطة للقيم المخصّصة يتم تطبيقها على DataTable بالكامل. يمكن أن تكون هذه القيم من أي نوع JavaScript. إذا كان التمثيل البصري يتيح أي خصائص على مستوى جدول البيانات، سيصفها، وبخلاف ذلك، ستتوفر هذه الخاصية لاستخدام التطبيق. مثال: p:{className: 'myDataTable'}.

فئة DataView

عرض للقراءة فقط لأحد جداول البيانات الأساسية. تسمح الخاصية 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 جديد:

المنشئ

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

data

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

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

setColumn() وhideColumn() وsetRows() وhideRows().

 

المنشئ

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

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

البيانات

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

viewAsJson

سلسلة JSON التي تعرضها DataView.toJSON(). هذا وصف للصفوف المطلوب إظهارها أو إخفاؤها من جدول البيانات data.

الطُرق

الطريقة	قيمة الإرجاع	الوصف
getColumnId getColumnLabel getColumnPattern getColumnProperty getColumnRange getColumnType getDistinctValues getFilteredRows getFormattedValue getNumberOfColumns getNumberOfRows getProperty getProperties getRowProperty getSortedRows getTableProperty getValue	يمكنك الاطّلاع على الأوصاف باللغة DataTable.	هذه الطريقة مماثلة لطُرق DataTable المكافئة، باستثناء أنّ فهارس الصفوف/الأعمدة تشير إلى الفهرس في الملف الشخصي وليس في الجدول/طريقة العرض الأساسية.
getTableColumnIndex(viewColumnIndex)	الرقم	لعرض الفهرس في الجدول الأساسي (أو العرض) لعمود معيّن تم تحديده من خلال الفهرس في هذا العرض. يجب أن يكون viewColumnIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الأعمدة التي تعرضها طريقة getNumberOfColumns(). لعرض -1 إذا كان هذا عمودًا تم إنشاؤه. مثال: إذا تم استدعاء setColumns([3, 1, 4]) في السابق، سيعرض getTableColumnIndex(2) القيمة 4.
getTableRowIndex(viewRowIndex)	الرقم	لعرض الفهرس في الجدول الأساسي (أو العرض) لصف معين محدّد بالفهرس في طريقة العرض هذه. يجب أن يكون viewRowIndex رقمًا أكبر من أو يساوي صفرًا، وأقل من عدد الصفوف التي تعرضها طريقة getNumberOfRows(). مثال: إذا تم استدعاء setRows([3, 1, 4]) في السابق، سيعرض getTableRowIndex(2) القيمة 4.
getViewColumnIndex(tableColumnIndex)	الرقم	لعرض الفهرس في طريقة العرض هذه التي تم تعيينها إلى عمود معين محدد بواسطة الفهرس في الجدول الأساسي (أو العرض). إذا كان هناك أكثر من فهرس، يتم عرض أول (أصغر) فهرس. في حالة عدم وجود هذا الفهرس (العمود المحدد ليس في العرض)، يتم إرجاع -1. يجب أن يكون tableColumnIndex عددًا أكبر من أو يساوي صفرًا، وأقل من عدد الأعمدة التي يتم عرضها باستخدام طريقة getNumberOfColumns() في الجدول/طريقة العرض الأساسية. مثال: إذا تم استدعاء setColumns([3, 1, 4]) في السابق، سيعرض getViewColumnIndex(4) القيمة 2.
getViewColumns()	مصفوفة الأرقام	لعرض الأعمدة في هذا العرض بالترتيب. وهذا يعني أنه إذا تم استدعاء setColumns مع بعض المصفوفة ثم الاستدعاء getViewColumns()، من المفترض أن تحصل على مصفوفة متطابقة.
getViewRowIndex(tableRowIndex)	الرقم	لعرض الفهرس في طريقة العرض هذه التي تم تعيينها لصف معين محدد بواسطة الفهرس في الجدول الأساسي (أو العرض). إذا كان هناك أكثر من فهرس، يتم عرض أول (أصغر) فهرس. في حالة عدم وجود مثل هذا الفهرس (الصف المحدد ليس في العرض)، يتم إرجاع -1. يجب أن يكون tableRowIndex رقمًا أكبر من الصفر أو مساويًا له، وأقل من عدد الصفوف الذي يتم عرضه باستخدام طريقة getNumberOfRows() في الجدول/طريقة العرض الأساسية. مثال: إذا تم استدعاء setRows([3, 1, 4]) في السابق، سيعرض getViewRowIndex(4) القيمة 2.
getViewRows()	مصفوفة الأرقام	لعرض الصفوف في هذا العرض بالترتيب. وهذا يعني أنه إذا استدعيت setRows مع بعض المصفوفة ثم استدعيت getViewRows()، من المفترض أن تحصل على مصفوفة متطابقة.
hideColumns(columnIndexes)	لا ينطبق	لإخفاء الأعمدة المحددة من العرض الحالي. columnIndexes عبارة عن مصفوفة من الأرقام تمثل فهارس الأعمدة المراد إخفاؤها. وهذه الفهارس هي أرقام الفهرس في الجدول الأساسي/طريقة العرض. لا يلزم أن تكون الأرقام في columnIndexes بالترتيب (أي [3،4،1] مقبولة). وتحتفظ الأعمدة المتبقية بترتيب الفهرس عند تكرارها. لا يُعد إدخال رقم فهرس لعمود مخفي من قبل خطأً، ولكن إدخال فهرس غير موجود في الجدول/الملف الشخصي الأساسي سيؤدي إلى حدوث خطأ. لإظهار الأعمدة، اتصل بـ setColumns(). مثال: إذا كان لديك جدول يحتوي على 10 أعمدة واستدعيت setColumns([2,7,1,7,9])، ثم hideColumns([7,9])، ستكون الأعمدة في العرض هي [2,1].
hideRows(min, max)	لا ينطبق	لإخفاء جميع الصفوف التي تتضمن فهارس تقع بين الحد الأدنى والحد الأقصى (شامل) من العرض الحالي. هذه بنية ملاءمة لـ hideRows(rowIndexes) أعلاه. على سبيل المثال، hideRows(5, 10) يساوي hideRows([5, 6, 7, 8, 9, 10]).
hideRows(rowIndexes)	لا ينطبق	لإخفاء الصفوف المحددة من العرض الحالي. rowIndexes عبارة عن مصفوفة من الأرقام تمثل فهارس الصفوف المراد إخفاؤها. وهذه الفهارس هي أرقام الفهرس الواردة في الجدول/العرض الأساسي. لا يلزم أن تكون الأرقام في rowIndexes بالترتيب (أي [3،4،1] مقبولة). وتحتفظ الصفوف المتبقية بترتيب الفهرس. لا يُعد إدخال رقم فهرس لصف مخفي فعلاً خطأ، إلا أن إدخال فهرس غير موجود في الجدول/طريقة العرض الأساسية سيؤدي إلى عرض رسالة خطأ. لإظهار الصفوف، يمكنك طلب setRows(). مثال: إذا كان لديك جدول يتكون من 10 صفوف، واستدعيت setRows([2,7,1,7,9])، ثم hideRows([7,9])، ستكون الصفوف في الملف الشخصي [2,1].
setColumns(columnIndexes)	لا ينطبق	لتحديد الأعمدة التي تظهر في هذا العرض. وسيتم إخفاء أي أعمدة لم يتم تحديدها. هذه هي مجموعة من فهارس الأعمدة في الجدول/العرض الأساسي أو الأعمدة المحسوبة. في حال عدم استدعاء هذه الطريقة، يكون الوضع التلقائي هو عرض جميع الأعمدة. ويمكن أن تحتوي المصفوفة أيضًا على نُسخ مكررة، لعرض العمود نفسه عدة مرات. سيتم عرض الأعمدة بالترتيب المحدد. columnIndexes - مصفوفة من الأرقام و/أو الكائنات (يمكن مزجها): الأرقام تحدد فهرس عمود البيانات المصدر لتضمينه في الملف الشخصي. ويتم جلب البيانات من خلال دون تعديل. إذا أردت تحديد دور أو خصائص عمود إضافية بشكل صريح، حدِّد كائنًا بخاصية sourceColumn. العناصر تحدّد عمودًا مَحسوبًا. ينشئ العمود المَحسوب قيمة بشكل فوري لكل صف ويضيفها إلى العرض. يجب أن يكون للكائن الخصائص التالية: calc [الوظيفة] - دالة سيتم استدعاؤها لكل صف في العمود لحساب قيمة لهذه الخلية. توقيع الدالة هو func(dataTable, row)، حيث dataTable هو المصدر DataTable، وrow هو فهرس صف البيانات المصدر. يجب أن تعرض الدالة قيمة واحدة من النوع المحدّد بواسطة type. type <string] - نوع JavaScript للقيمة التي تعرضها دالة calc. label [اختيارية، سلسلة] - علامة اختيارية لتخصيصها للعمود الذي تم إنشاؤه. وفي حال عدم تحديد العمود، لن يحمل عمود "العرض" أي تصنيف. id [اختيارية، سلسلة] - معرّف اختياري يمكن تحديده لهذا العمود الذي تم إنشاؤه. sourceColumn - [اختيارية، number] عمود المصدر المطلوب استخدامه كقيمة، وإذا كان محدّدًا، لا تحدّد السمة calc أو type. يشبه ذلك تمرير رقم بدلاً من كائن، ولكنه يتيح لك تحديد دور وخصائص للعمود الجديد. properties [اختيارية, object] - كائن يحتوي على أي مواقع عشوائية يمكن تحديدها لهذا العمود. وإذا لم يتم تحديده، لن يتضمّن عمود العرض أي خصائص. role [اختيارية، سلسلة] - دور مطلوب تخصيصه لهذا العمود. وفي حال عدم التحديد، لن يتم استيراد الدور الحالي. أمثلة: // 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); }
setRows(min, max)	لا ينطبق	لتعيين الصفوف في هذا الملف الشخصي بحيث تكون جميع الفهارس (في الجدول/الملف الشخصي الأساسي) التي تقع بين الحد الأدنى والحد الأقصى (شامل). في ما يلي بنية مناسبة لـ setRows(rowIndexes) أدناه. على سبيل المثال، setRows(5, 10) يساوي setRows([5, 6, 7, 8, 9, 10]).
setRows(rowIndexes)	لا ينطبق	يضبط الصفوف المرئية في طريقة العرض هذه، استنادًا إلى أرقام الفهرس من الجدول/طريقة العرض الأساسية. يجب أن يكون rowIndexes مصفوفة من أرقام الفهرس التي تحدِّد الصفوف التي سيتم عرضها في العرض. تحدد الصفيف الترتيب الذي يجب عرض الصفوف به، ويمكن تكرار الصفوف فيه. ملاحظة: سيتم عرض الصفوف المحدّدة في rowIndexes فقط، وتمحو هذه الطريقة جميع الصفوف الأخرى من العرض. يمكن أن تحتوي المصفوفة أيضًا على عناصر مكرّرة، ما يؤدي إلى تكرار الصف المحدّد في هذا الملف الشخصي (على سبيل المثال، سيؤدي setRows([3, 4, 3, 2]) إلى ظهور الصف 3 مرتين في هذا العرض). وبالتالي، توفّر المصفوفة تعيينًا للصفوف من الجدول/الملف الشخصي الأساسي إلى هذا الملف الشخصي. ويمكنك استخدام getFilteredRows() أو getSortedRows() لإنشاء إدخال لهذه الطريقة. مثال: لإنشاء طريقة عرض تحتوي على الصفَّين الثالث والصفر من جدول/طريقة عرض أساسية: view.setRows([3, 0])
toDataTable()	جدول البيانات	لعرض عنصر DataTable تمت تعبئته بالصفوف والأعمدة المرئية في DataView.
toJSON()	سلسلة	لعرض تمثيل سلسلة لـ DataView. لا تحتوي هذه السلسلة على البيانات الفعلية، فهي تحتوي فقط على الإعدادات الخاصة بـ DataView مثل الصفوف والأعمدة المرئية. يمكنك تخزين هذه السلسلة وتمريرها إلى دالة إنشاء DataView.fromJSON() الثابتة لإعادة إنشاء هذا العرض. ولن يشمل ذلك الأعمدة التي تم إنشاؤها.

فئة التفاف الملف البياني

يتم استخدام صف 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 الطرق الإضافية التالية:

الطريقة	نوع القيمة التي يتم عرضها	الوصف
draw(opt_container_ref)	لا ينطبق	لرسم المخطط. يجب استدعاء هذه الطريقة بعد أي تغييرات تجريها على الرسم البياني أو البيانات لعرض التغييرات. opt_container_ref [اختيارية] - مرجع إلى عنصر حاوية صالح في الصفحة. في حالة تحديد ذلك، سيتم رسم المخطط هناك. وإذا لم يكن الأمر كذلك، سيتم رسم الرسم البياني في العنصر الذي يحمل المعرّف المحدّد من خلال containerId.
toJSON()	سلسلة	لعرض إصدار سلسلة من تمثيل JSON للرسم البياني.
clone()	مغلّف الرسم البياني	لعرض نسخة عميقة من برنامج تضمين المخطط.
getDataSourceUrl()	سلسلة	إذا كان هذا الرسم البياني يحصل على بياناته من مصدر بيانات، سيعرض عنوان URL لمصدر البيانات هذا. وإلا، فسيتم إرجاع القيمة فارغة.
getDataTable()	google.Visualization.DataTable	إذا حصل هذا الرسم البياني على بياناته من DataTable محدد محليًا، فإنه سيعرض مرجعًا إلى DataTable في الرسم البياني. إذا حصل هذا الرسم البياني على بياناته من مصدر بيانات، فسيعرض قيمة خالية. وستظهر أي تغييرات تجريها على العنصر المعروض في الرسم البياني في المرة التالية التي يتم فيها استدعاء ChartWrapper.draw().
getChartType()	سلسلة	اسم فئة الرسم البياني الملتف. إذا كان هذا الرسم البياني من Google، لن يكون الاسم مؤهّلاً باستخدام google.visualization. على سبيل المثال، إذا كان الرسم البياني Treemap، سيعرض "Treemap" بدلاً من "google.visibleization.treemap".
getChartName()	سلسلة	لعرض اسم الرسم البياني الذي تم تعيينه من قِبل setChartName().
getChart()	مرجع كائن الرسم البياني	لعرض مرجع إلى المخطط الذي تم إنشاؤه بواسطة مخطط الرسم البياني هذا، على سبيل المثال google.visualization.BarChart أو google.visualization.ColumnChart . وسيؤدي ذلك إلى عرض قيمة فارغة حتى يتم استدعاء الدالة draw() على كائن ChartWrapper، ومن ثمّ إنشاء حدث جاهز. ستنعكس الطرق التي تم استدعاؤها على العنصر المعروض على الصفحة.
getContainerId()	سلسلة	رقم تعريف عنصر حاوية DOM في الرسم البياني.
getQuery()	سلسلة	سلسلة طلب البحث لهذا الرسم البياني، إذا كانت تحتوي على سلسلة واستفسر عن مصدر بيانات.
getRefreshInterval()	الرقم	أي فاصل زمني لإعادة التحميل لهذا الرسم البياني، في حال كان يرسل طلب بحث إلى مصدر بيانات. يشير الصفر إلى عدم إعادة التحميل.
getOption(key, opt_default_val)	أي نوع	لعرض قيمة خيار المخطط المحدد key - اسم خيار الاسترداد. قد يكون اسمًا مؤهلاً، مثل 'vAxis.title'. opt_default_value [اختيارية] - إذا كانت القيمة المحدّدة غير محدّدة أو فارغة، سيتم عرض هذه القيمة.
getOptions()	اعتراض	لعرض كائن الخيارات لهذا الرسم البياني.
getView()	كائن أو مصفوفة	لعرض كائن المُنشئ DataView بالتنسيق dataview.toJSON() نفسه أو مصفوفة من هذه العناصر.
setDataSourceUrl(url)	لا ينطبق	تحدّد عنوان URL لمصدر بيانات لاستخدامه لهذا الرسم البياني. في حال ضبط جدول بيانات أيضًا لهذا العنصر، سيتم تجاهل عنوان URL لمصدر البيانات.
setDataTable(table)	لا ينطبق	لتعيين جدول البيانات للمخطط. مرِّر أحد الخيارات التالية: null أو كائن DataTable أو تمثيل JSON لجدول بيانات أو مصفوفة تتبع بنية arrayToDataTable().
setChartType(type)	لا ينطبق	لتعيين نوع المخطط. مرّر اسم فئة الرسم البياني الملتف. إذا كان هذا الرسم البياني من Google، لا يمكنك تأهيله باستخدام google.visualization. على سبيل المثال، بالنسبة إلى الرسم البياني الدائري، يجب إدخال "PieChart".
setChartName(name)	لا ينطبق	لتعيين اسم عشوائي للرسم البياني. ولن يظهر هذا الرسم البياني في أي مكان على الرسم البياني، ما لم يتم تصميم رسم بياني مخصّص بشكل صريح لاستخدامه.
setContainerId(id)	لا ينطبق	لتعيين رقم تعريف عنصر DOM المضمن للرسم البياني.
setQuery(query_string)	لا ينطبق	تعيّن سلسلة طلب بحث، إذا كان هذا الرسم البياني يرسل طلبات بحث إلى مصدر بيانات. وعليك أيضًا ضبط عنوان URL لمصدر البيانات في حال تحديد هذه القيمة.
setRefreshInterval(interval)	لا ينطبق	تُعيّن الفاصل الزمني للتحديث لهذا المخطط، إذا كان يرسل طلب بحث إلى مصدر بيانات. يجب أيضًا ضبط عنوان URL لمصدر البيانات في حال تحديد هذه القيمة. يشير الصفر إلى عدم إعادة التحميل.
setOption(key, value)	لا ينطبق	يتم تعيين قيمة خيار واحدة للرسم البياني، حيث يكون key هو اسم الخيار وvalue هي القيمة. لإلغاء ضبط خيار، مرِّر القيمة الفارغة إلى القيمة. يُرجى العِلم بأن key قد يكون اسمًا مؤهلاً، مثل 'vAxis.title'.
setOptions(options_obj)	لا ينطبق	تعيين كائن خيارات كامل لمخطط.
setView(view_spec)	لا ينطبق	تُحدِّد كائن أداة ضبط DataView الذي يعمل كفلتر على البيانات الأساسية. يجب أن يحتوي برنامج تضمين الرسم البياني على بيانات أساسية من جدول بيانات أو مصدر بيانات لتطبيق هذا العرض عليه. يمكنك تمرير إما سلسلة بيانات أو كائن مُعد DataView، على النحو الذي يتم عرضه بواسطة dataview.toJSON(). يمكنك أيضًا تمرير مجموعة من كائنات DataView المُنشئ، وفي هذه الحالة يتم تطبيق DataView الأولى في المصفوفة على البيانات الأساسية لإنشاء جدول بيانات جديد، ويتم تطبيق DataView الثاني على جدول البيانات الناتج عن تطبيق أول DataView،

الأحداث

يرمي الكائن ChartWrapper الأحداث التالية. ملاحظة: يجب الاتصال بـ ChartWrapper.draw() قبل طرح أي فعاليات.

الاسم	الوصف	أماكن إقامة
error	يتم الإطلاق عند حدوث خطأ عند محاولة عرض الرسم البياني.	id، رسالة
ready	المخطط جاهز لاستدعاءات الطرق الخارجية. إذا كنت تريد التفاعل مع الرسم البياني واستدعاء طُرق الاتصال بعد رسمه، عليك إعداد مستمع لهذا الحدث قبل استدعاء طريقة draw والاتصال بها فقط بعد تنشيط الحدث.	لا ينطبق
select	يتم الإطلاق عندما ينقر المستخدم على شريط أو وسيلة إيضاح. عند اختيار عنصر في الرسم البياني، يتم اختيار الخلية المقابلة في جدول البيانات، وعند اختيار وسيلة إيضاح، يتم اختيار العمود المقابل في جدول البيانات. للاطّلاع على ما تم اختياره، يمكنك الاتصال بالرقم ChartWrapper.getChart(). getSelection(). ويُرجى العِلم أنّه لن يتم تنفيذ هذا الإجراء إلا عندما يقدّم نوع الرسم البياني الأساسي حدث اختيار.	لا ينطبق

مثال

يؤدي المقتطفان التاليان إلى إنشاء مخطط خطي مكافئ. يستخدم المثال الأول الترميز الحرفي بتنسيق 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>

الرسم البياني نفسه، ويستخدم الآن طرق ضبط:

<!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 وسجِّل الفيديو للاستماع إلى الفعالية "حسنًا". يتم طرح هذه الفعالية عندما ينقر المستخدم على الزر "حسنًا" في مربّع الحوار. عند الاستلام، يجب الاتصال بالرقم ChartEditor.getChartWrapper() لاسترداد الرسم البياني الذي عدّله المستخدم.
4. اتصل برقم ChartEditor.openDialog()، مع مرور ChartWrapper. سيؤدي هذا إلى فتح مربع الحوار. وتمكّن أزرار مربّع الحوار المستخدم من إغلاق أداة التعديل. يتوفّر المثيل ChartEditor طالما أنّه في النطاق، ولا يتم إتلافه تلقائيًا بعد إغلاق المستخدم لمربّع الحوار.
5. لتعديل الرسم البياني في الرمز، يمكنك الاتصال بالرقم setChartWrapper().

الطُرق

الطريقة	قيمة الإرجاع	الوصف
openDialog(chartWrapper, opt_options)	قيمة فارغة	لفتح محرر المخطط كمربع حوار مضمن في الصفحة. تعود الدالة على الفور، ولا تنتظر إغلاق مربّع الحوار. إذا لم تفقد نطاق المثيل، يمكنك استدعاء openDialog() مرة أخرى لإعادة فتح مربع الحوار، على الرغم من أنه يجب عليك تمرير كائن ChartWrapper مرة أخرى. chartWrapper - كائن ChartWrapper يحدد المخطط الأولي لعرضه في النافذة. يجب أن يحتوي الرسم البياني إما على DataTable معبأة، أو أن يكون مصدر البيانات صالحًا. يتم نسخ برنامج التضمين هذا داخليًا إلى محرّر الرسم البياني، لذلك لن تظهر أي تغييرات تجريها لاحقًا على مقبض ChartWrapper في نسخة محرّر الرسم البياني. opt_options - [اختياري] كائن يحتوي على أي خيارات لمحرِّر الرسم البياني. اطّلع على جدول الخيارات أدناه.
getChartWrapper()	ChartWrapper	لعرض ChartWrapper الذي يمثل الرسم البياني، مع تعديلات المستخدم.
setChartWrapper(chartWrapper)	قيمة فارغة	استخدِم هذه الطريقة لتعديل الرسم البياني المعروض على المحرِّر. chartWrapper - كائن ChartWrapper يمثل المخطط الجديد المطلوب عرضه. يجب أن يتضمن الرسم البياني DataTable معبأة أو أن يكون متصلاً بمصدر بيانات صالح.
closeDialog()	قيمة فارغة	لإغلاق مربع حوار محرر المخطط.

الخيارات

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

الاسم	النوع	القيمة التلقائية	الوصف
dataSourceInput	مقبض العنصر أو "urlbox"	قيمة فارغة	استخدم هذا الخيار لتمكين المستخدم من تحديد مصدر بيانات للرسم البياني. يمكن أن تكون هذه الخاصية واحدة من قيمتَين: 'urlbox' - اعرض عنوان URL لمصدر بيانات المخطط في مربع الحوار في مربع نص قابل للتعديل. يمكن للمستخدم تعديل هذا، وستتم إعادة رسم الرسم البياني استنادًا إلى مصدر البيانات الجديد. عنصر DOM - يمكنك من توفير عنصر HTML مخصص لاستخدامه لتحديد مصدر بيانات. مرِّر مقبضًا إلى عنصر HTML، إما عنصرًا تم إنشاؤه في الرمز أو تم نسخه من الصفحة. سيتم عرض هذا العنصر في مربع الحوار. ويمكنك استخدامها كطريقة للسماح للمستخدم باختيار مصدر بيانات الرسم البياني. على سبيل المثال، أنشِئ مربّعًا يحتوي على عدة عناوين URL لمصدر بيانات أو أسماء سهلة الاستخدام يمكن للمستخدم الاختيار من بينها. يجب أن ينفذ العنصر معالج اختيار ويستخدمه لتغيير مصدر بيانات الرسم البياني: على سبيل المثال، يمكنك تغيير DataTable الأساسي أو تعديل حقل dataSourceUrl في الرسم البياني.

الأحداث

يقدم محرر المخطط الأحداث التالية:

الاسم	الوصف	أماكن إقامة
ok	يتم الإطلاق عندما ينقر المستخدم على الزر "موافق" في مربع الحوار. وبعد تلقّي هذه الطريقة، عليك استدعاء الدالة getChartWrapper() لاسترداد الرسم البياني الذي أعدّه المستخدم.	لا ينطبق
cancel	يتم الإطلاق عندما ينقر المستخدم على الزر "إلغاء" في مربع الحوار.	لا ينطبق

مثال

يفتح نموذج الرمز التالي مربع حوار محرِّر الرسم البياني مع رسم بياني خطي تمت تعبئته. إذا نقر المستخدم على "حسنًا"، سيتم حفظ الرسم البياني المعدَّل في <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 الطرق التالية:

الطريقة	الوصف
google.visualization.data.group	لتنفيذ إجراء SQL GROUP BY لإرجاع جدول مجمّع حسب القيم في الأعمدة المحددة.
google.visualization.data.join	يضم جدولي بيانات في عمود رئيسي واحد أو أكثر.

group()

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

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

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

البنية

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

جدول_البيانات

الإدخال DataTable. لن يتم تعديل هذا من خلال الاتصال بـ group().

مفاتيح

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

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

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

الأعمدة

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

• column - رقم يحدد فهرس العمود المطلوب عرضه.
• aggregation - دالة تقبل مصفوفة من جميع قيم هذا العمود في مجموعة الصفوف هذه وتعرض قيمة واحدة لعرضها في صف النتيجة. يجب أن تكون قيمة العرض من النوع المحدّد في خاصية type للكائن. في ما يلي تفاصيل عن إنشاء دالة التجميع الخاصة بك. يجب أن تعرف أنواع البيانات التي تقبلها هذه الطريقة وأن تستدعيها في أعمدة من النوع المناسب فقط. توفر واجهة برمجة التطبيقات العديد من دوال التجميع المفيدة. اطّلِع على دالات التجميع المُقدَّمة أدناه للحصول على قائمة، أو إنشاء دالة تجميع للتعرّف على كيفية كتابة دالة التجميع الخاصة بك.
• type - نوع عرض دالة التجميع. ويجب أن يكون اسم نوع سلسلة JavaScript، مثل "number" أو "boolean".
• 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 لتخصيص سلوك التجميع.

الوظيفة	نوع مصفوفة الإدخال	نوع القيمة التي يتم عرضها	الوصف
google.visualization.data.month	التاريخ	number	وعند إدخال تاريخ، سيتم عرض قيمة الشهر المستندة إلى الصفر (0 و1 و2 وما إلى ذلك).

وظائف التجميع المتوفرة

توفر واجهة برمجة التطبيقات دوال التجميع التالية التي يمكنك تمريرها إلى الأعمدة. التجميع.

الوظيفة	نوع مصفوفة الإدخال	نوع القيمة التي يتم عرضها	الوصف
google.visualization.data.avg	number	number	متوسط قيمة الصفيف الذي تم تمريره.
google.visualization.data.count	أي نوع	number	عدد الصفوف في المجموعة. ويتم احتساب القيم الفارغة والمكررة.
google.visualization.data.max	رقم، سلسلة، تاريخ	number، string، Date، null	الحد الأقصى للقيمة في المصفوفة. في ما يتعلّق بالسلاسل، يمثّل هذا العمود العنصر الأوّل في قائمة مرتبة ترتيبًا دلاليًا، أما بالنسبة إلى قيم التاريخ، فهي تمثّل آخر تاريخ. يتم تجاهل القيم الفارغة. يتم عرض قيمة خالية في حال عدم وجود حد أقصى.
google.visualization.data.min	رقم، سلسلة، تاريخ	number، string، Date، null	الحد الأدنى للقيمة في المصفوفة. وبالنسبة إلى السلاسل، يمثّل هذا العنصر آخر عنصر في قائمة مرتبة ترتيبًا لغويًا، أما في قيم التاريخ، فهو التاريخ الأقدم. يتم تجاهل القيم الفارغة. يتم عرض قيمة خالية في حال لم يكن هناك حد أدنى.
google.visualization.data.sum	number	number	مجموع كل القيم في المصفوفة.

إنشاء دالة معدِّل

يمكنك إنشاء دالة معدّل لتنفيذ قيم مفتاح تحويل بسيطة قبل أن تجمع الدالة 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;
}

انضمام()

تعمل هذه الطريقة على دمج جدولي بيانات (كائن 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):

A	ب
جين	أحمر
جين	أزرق
فريد	أحمر

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

dt1الأعمدة

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

dt2الأعمدة

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

قيمة الإرجاع

DataTable مع الأعمدة الرئيسية، dt1الأعمدة، وdt2الأعمدة. يتم ترتيب هذا الجدول حسب الأعمدة الرئيسية، من اليسار إلى اليمين. عندما تكون قيمة 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 أدوات تنسيق يمكن استخدامها في إعادة تنسيق البيانات في التمثيل البصري. تغيّر أدوات التنسيق هذه القيمة المنسّقة للعمود المحدّد في جميع الصفوف. تجدر الإشارة إلى ما يلي:

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

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

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

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

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

في ما يلي مثال على تغيير قيم التاريخ المنسّقة لعمود التاريخ لاستخدام تنسيق تاريخ طويل ("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 اسمًا محددًا لـ formatterclass. 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 التنسيقات التالية:

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

تنسيق السهم

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

الخيارات

يتيح 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 الخيارات التالية التي يتم تمريرها إلى دالة الإنشاء:

Option	مثال الوصف
base	رقم يمثل القيمة الأساسية لمقارنة قيمة الخلية معها. إذا كانت قيمة الخلية أعلى، سيتم رسمها على يمين القاعدة، وإذا كانت أقل، سيتم رسمها إلى اليسار. القيمة التلقائية هي 0.
colorNegative	سلسلة تشير إلى قسم القيمة السالبة للأشرطة. القيم المحتملة هي "أحمر" و"أخضر" و"أزرق"، والقيمة التلقائية هي "أحمر".
colorPositive	سلسلة تشير إلى لون قسم القيمة الموجبة للأشرطة. القيم المحتملة هي "أحمر" و"أخضر" و"أزرق". الإعداد الافتراضي هو "أزرق".
drawZeroLine	قيمة منطقية تشير إلى ما إذا كان يجب رسم خط أساس داكن 1 بكسل عند وجود قيم سالبة. ويتم استخدام الخط الداكن لتحسين المسح الضوئي للأشرطة. القيمة التلقائية هي "false".
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%'});

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

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

الطُرق

ColorFormat يدعم الطرق التالية:

الطريقة	الوصف
google.visualization.ColorFormat()	المُنشئ. لا توجد وسيطات.
addRange(from, to, color, bgcolor)	لتحديد لون المقدمة و/أو لون الخلفية لخلية، بناءً على قيمة الخلية. أي خلية تحتوي على قيمة في النطاق from المحدّد إلى سيتم تخصيصها color (اللون) وbgcolor. من المهم إدراك أن النطاق غير شامل، لأن إنشاء نطاق من 1 إلى 1000 وثانية من 1000 إلى 2000 لن يغطي القيمة 1000. from - [String, Number, Date, DateTime, or TimeOfDay] الحد الأدنى (شاملاً) للنطاق أو فارغ. إذا كانت القيمة فارغة، ستتم مطابقتها مع -∞. تتم مقارنة حدود السلسلة أبجديًا مع قيم السلسلة. to - [String أو Number أو Date أو DateTime أو TimeTimeDay] الحد المرتفع للنطاق (غير شامل) أو فارغ. إذا كانت القيمة فارغة، ستتطابق مع +∞. وستتم مقارنة حدود السلسلة أبجديًا مع قيم السلسلة. color - اللون المراد تطبيقه على النص في الخلايا المطابقة. يمكن أن تكون القيم إما قيم "#RRGGBB" أو ثوابت ألوان محدّدة، (مثال: "#FF0000" أو "أحمر"). bgcolor - اللون المراد تطبيقه على خلفية الخلايا المطابقة. يمكن أن تكون القيم إما قيم "#RRGGBB" أو ثوابت ألوان محدّدة، (مثال: "#FF0000" أو "أحمر").
addGradientRange(from, to, color, fromBgColor, toBgColor)	لتحديد لون خلفية من نطاق، وفقًا لقيمة الخلية. ويتم تغيير حجم اللون لمطابقة قيمة الخلية في نطاق يتراوح من لون الحد السفلي إلى لون الحد العلوي. تجدر الإشارة إلى أن هذه الطريقة لا يمكنها مقارنة قيم السلسلة، حيث إن addRange() يمكنه ذلك. نصيحة: غالبًا ما يصعب على المشاهدين قياس نطاقات الألوان بدقة، في حين أنّ أبسط وأسهل خيار للقراءة هو اللون المشبع كليًا باللون الأبيض (على سبيل المثال، #FF0000—FFFFFF) from - [Number أو Date أو DateTime أو TimeTimeDay] الحد الأدنى (شاملاً) للنطاق أو فارغًا. إذا كانت القيمة فارغة، ستتطابق مع -∞. to - [Number أو Date أو DateTime أو TimeTimeDay] الحد الأعلى (غير شامل) للنطاق أو فارغة. إذا كانت القيمة خالية، ستتطابق مع +∞. color - اللون المراد تطبيقه على النص في الخلايا المطابقة. ويكون هذا اللون هو نفسه لجميع الخلايا، بغض النظر عن قيمتها. fromBgColor - لون الخلفية للخلايا التي تتضمن قيمًا عند نهاية التدرج المنخفض. يمكن أن تكون القيم إما قيم "#RRGGBB" أو ثوابت ألوان محدّدة، (مثال: "#FF0000" أو "أحمر"). toBgColor - لون الخلفية للخلايا التي تحمل قيمًا في أعلى نهاية التدرج. يمكن أن تكون القيم إما قيم "#RRGGBB" أو ثوابت ألوان محدّدة، (مثال: "#FF0000" أو "أحمر").
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%'});

تنسيق التاريخ

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

الخيارات

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

Option	الوصف
formatType	خيار تنسيق سريع للتاريخ. يتم دعم قيم السلسلة التالية، حيث تتم إعادة تنسيق التاريخ في 28 من شباط (فبراير) 2016 كما هو موضح: 'short' - صيغة قصيرة: على سبيل المثال, "28/2/16" 'medium' - التنسيق المتوسط: على سبيل المثال، "28 شباط (فبراير) 2016" 'long' - التنسيق الطويل: على سبيل المثال، "28 شباط (فبراير) 2016" لا يمكنك تحديد كل من formatType وpattern.
pattern	نمط تنسيق مخصّص لتطبيقه على القيمة، يكون مشابهًا لتنسيق التاريخ والوقت في وحدة المعالجة المركزية (ICU). على سبيل المثال: var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"}); لا يمكنك تحديد كل من formatType وpattern. يمكنك الاطّلاع على مزيد من التفاصيل حول الأنماط في القسم التالي.
timeZone	المنطقة الزمنية التي سيتم عرض قيمة التاريخ فيها. هذه قيمة رقمية تشير إلى GMT + هذا العدد من المناطق الزمنية (يمكن أن تكون سالبة). يتم إنشاء كائن التاريخ تلقائيًا باستخدام المنطقة الزمنية المُفترضة لجهاز الكمبيوتر الذي يتم إنشاؤها عليه. ويُستخدم هذا الخيار لعرض هذه القيمة في منطقة زمنية مختلفة. على سبيل المثال، إذا أنشأت كائن التاريخ في الساعة 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 D F g Y u W. ولتجنّب التضارب مع الأنماط، يجب أن يكون أي نص حرفي تريد ظهوره في الإخراج محاطًا بعلامات اقتباس مفردة، باستثناء علامة الاقتباس المفردة التي يجب مضاعفةها: على سبيل المثال، "K 'o''clock.'"

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

تنسيق الأرقام

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

الخيارات

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

Option	الوصف
decimalSymbol	حرف لاستخدامه كعلامة عشرية. القيمة الافتراضية هي نقطة (.)
fractionDigits	رقم يحدد عدد الأرقام المطلوب عرضها بعد العلامة العشرية. القيمة التلقائية هي 2. وإذا حدّدت أرقامًا أكثر من التي يحتوي عليها الرقم، سيتم عرض أصفار للقيم الأصغر. سيتم تقريب القيم المقطوعة (تقريبًا 5 قيم).
groupingSymbol	حرف يتم استخدامه لتجميع الأرقام على يسار العلامة العشرية في مجموعات من ثلاثة أرقام. الإعداد التلقائي هو فاصلة (,).
negativeColor	لون النص للقيم السالبة. ليست هناك قيمة تلقائية. يمكن أن تكون القيم أي قيمة مقبولة لألوان HTML، مثل "أحمر" أو "#FF0000".
negativeParens	قيمة منطقية، حيث تشير القيمة true إلى وجوب وضع القيم السلبية بين قوسين. الإعداد التلقائي صحيح.
pattern	سلسلة تنسيق. ويتم تجاهل جميع الخيارات الأخرى عند تقديمها، باستثناء negativeColor. سلسلة التنسيق هي مجموعة فرعية من مجموعة أنماط وحدة العناية المركزة . على سبيل المثال، سينتج عن القيم {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%'});

النمط

يمكّنك من دمج قيم الأعمدة المحدّدة في عمود واحد، إلى جانب النص العشوائي. لذلك، على سبيل المثال، إذا كان لديك عمود للاسم الأول وعمود للاسم الأخير، يمكنك تعبئة عمود ثالث باسم {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 - [اختيارية] عمود الوجهة لعرض نتائج معالجة pattern. وإذا لم يتم تحديد السمة، سيتم استخدام العنصر الأول في 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', '[e-mail]'],
  ['Paul McCartney', '[e-mail]'],
  ['George Harrison', '[e-mail]'],
  ['Ringo Starr', '[e-mail]']
]);

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%'});

أداة المساعدة

فئة مساعدة لتبسيط كتابة الأدوات التي تستخدم واجهة برمجة التطبيقات للتمثيل البصري في Google.

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

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.visibleization.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.visibleization.QueryResponse.

طلب استجابة

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

الطُرق

الطريقة	قيمة الإرجاع	الوصف
getDataTable()	جدول البيانات	لعرض جدول البيانات كما يعرضه مصدر البيانات. لعرض 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 الرسالة التفصيلية كنص تلميح فقط، ويعرض false الرسالة التفصيلية في نص الحاوية بعد الرسالة القصيرة القيمة التلقائية هي "true". type - سلسلة تصف نوع الخطأ الذي يحدد أنماط CSS التي يجب تطبيقها على هذه الرسالة. القيمتان المسموح بإدراجهما هما "خطأ" و"تحذير". القيمة التلقائية هي "error". style - سلسلة نمط رسالة الخطأ. سيلغي هذا النمط أي أنماط مُطبَّقة على نوع التحذير (opt_options.type). مثال: 'background-color: #33ff99; padding: 2px;' القيمة التلقائية هي سلسلة فارغة. removable (قيمة قابلة للإزالة) - قيمة منطقية، وتعني true أنّه يمكن إغلاق الرسالة من خلال النقر بالماوس من المستخدم. القيمة التلقائية هي false.
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.visibleization.events.addListener() وgoogle.visibleization.events.addOneTimeListener() للاستماع إلى الأحداث.
• تؤدي google.visibleization.events.removeListener() إلى إزالة المستمع الحالي.
• يزيل google.visibleization.events.removeAllListeners() جميع المستمعين إلى رسم بياني معيّن.
• يعمل google.visibleization.events.trigger() على تنشيط الحدث.

addListener()

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

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

عرض_المحتوى_المرئي

مقبض لمثيل التمثيل البصري للمصدر.

event_name

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

function_function

اسم دالة JavaScript المحلية المطلوب استدعاؤها عندما يفعِّل المصدر source (العنصر المرئي) حدث event_name. سيتم تمرير دالة التعامل مع أي وسيطات حدث كمعلمات.

طلبات الإرجاع

معالج معالجة للمستمع الجديد. يمكن استخدام المعالج لإزالة أداة معالجة البيانات هذه لاحقًا إذا لزم الأمر من خلال استدعاء google.visibleization.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)

اسم_المستمع

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

removeAllListeners()

وعليك باستدعاء هذه الطريقة لإلغاء تسجيل جميع المستمعين إلى الحدث من مثيل التمثيل البصري المُحدَّد.

google.visualization.events.removeAllListeners(source_visualization)

عرض_المحتوى_المرئي

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

trigger()

ويتم استدعاؤها من خلال تطبيقي التمثيل البصري. استدعِ هذه الطريقة من التمثيل البصري لتنشيط حدث معيّن باستخدام اسم عشوائي ومجموعة من القيم.

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

عرض_المحتوى_المرئي

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

event_name

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

arg

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

مثال

في ما يلي مثال على التمثيل البصري الذي يرمي طريقة تسمى "select" عند استدعاء طريقة onclick التابعة لها. ولا يتم تمرير أي قيم.

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);
}

أساليب التمثيل البصري العادي وخصائصه

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

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

ملاحظة: تتوفّر هذه الطرق في مساحة الاسم في التمثيل البصري، وليس في مساحة الاسم google.Visualization.

المنشئ

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

visualization_class_name(dom_element)

عنصر_العنصر

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

مثال

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

draw()

لرسم التمثيل البصري على الصفحة. وخلف الكواليس، يمكن أن يؤدي ذلك إلى جلب رسم من خادم أو إنشاء الرسم على الصفحة باستخدام رمز التمثيل البصري المرتبط. وعليك استدعاء هذه الطريقة في كل مرة تتغير فيها البيانات أو الخيارات. يجب رسم العنصر داخل عنصر 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() إلى تنشيط فعالية "الاختيار". وقد تتجاهل التمثيلات البصرية جزءًا من التحديد. على سبيل المثال، قد يتجاهل الجدول الذي يعرض الصفوف المحدّدة فقط عناصر الخلية أو العمود في تنفيذ setSelection()، أو يمكنه اختيار الصف بأكمله.

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

setSelection(selection_array)

selection_array

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

أساليب ثابتة متنوعة

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

الصفيف_DataData()

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

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

البنية

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

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

opt_firstRowIsData

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

طلبات الإرجاع

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، مع الخصائص التالية (حسّاسة لحالة الأحرف):

الخاصية	النوع	مطلوب	تلقائي	الوصف
نوع المخطط	سلسلة	مطلوب	لا ينطبق	اسم فئة التمثيل البصري. يمكن حذف اسم الحزمة google.visualization في الرسوم البيانية من Google. إذا لم يتم تحميل مكتبة التمثيل البصري المناسبة من قبل، ستحمّل هذه الطريقة المكتبة بالنيابة عنك إذا كان هذا التمثيل البياني في Google، ويجب تحميل التمثيلات البصرية للجهات الخارجية بشكل صريح. أمثلة: Table، PieChart، example.com.CrazyChart.
رقم تعريف الحاوية	سلسلة	مطلوب	لا ينطبق	رقم تعريف عنصر DOM على صفحتك التي ستستضيف التمثيل البصري.
الخيارات	اعتراض	اختياري	لا ينطبق	تمثل هذه الخاصية كائنًا يصف خيارات التمثيل البصري. ويمكنك استخدام إما الترميز الحرفي لجافا سكريبت أو تقديم مؤشر للعنصر. مثال: "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
جدول البيانات	اعتراض	اختياري	لا ينطبق	DataTable يُستخدم لتعبئة التمثيل البصري. يمكن أن يكون هذا تمثيلاً حرفيًا لسلسلة JSON لجدول البيانات، كما هو موضّح أعلاه، أو مقبضًا لكائن google.visualization.DataTable معبأ، أو مصفوفة ثنائية الأبعاد مثل مقبولة في arrayToDataTable(opt_firstRowIsData=false) . يجب تحديد هذه الخاصية أو سمة dataSourceUrl.
عنوان URL لمصدر البيانات	سلسلة	اختياري	لا ينطبق	طلب مصدر بيانات لتعبئة بيانات الرسم البياني (على سبيل المثال، جدول بيانات Google). يجب تحديد هذه الخاصية أو السمة dataTable.
طلب بحث	سلسلة	اختياري	لا ينطبق	في حال تحديد dataSourceUrl، يمكنك اختياريًا تحديد سلسلة طلب بحث تشبه SQL باستخدام لغة طلب بحث التمثيل البصري لفلترة البيانات أو معالجتها.
الفاصل الزمني للتحديث	الرقم	اختياري	لا ينطبق	عدد المرّات بالثواني التي يجب خلالها تحديث التمثيل البصري لمصدر طلب البحث. ولا تستخدم هذه السمة إلا عند تحديد 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()

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