تعرض هذه الصفحة العناصر التي تعرضها واجهة برمجة تطبيقات الرسوم المرئية في Google، والطرق العادية التي تعرضها جميع التمثيلات البصرية.
ملاحظة: مساحة الاسم لواجهة برمجة التطبيقات في Google المرئية هي
google.visualization.*
ملاحظة حول المصفوفات
لا تتعامل بعض المتصفحات مع الفواصل اللاحقة في مصفوفات 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'}] ]);
يمكنك إنشاء DataTable
إما عن طريق استدعاء دالة إنشاء بدون معلمات ثم إضافة قيم عن طريق استدعاء الطرق addColumn()
/
addRows()
المدرجة أدناه، أو عن طريق تمرير
كائن JavaScript حرفي معبأ لإعداده. يتم وصف كلتا الطريقتين أدناه. أَيُّ
خِيَارْ يَجِبُ اسْتِخْدَامُهُ؟
-
إنّ إنشاء جدول وملؤه بجافا سكريبت عن طريق طلب
addColumn()
وaddRow()
وaddRows()
هو رمز قابل للقراءة جدًا. وتكون هذه الطريقة مفيدة عند إدخال الرمز يدويًا. وهو أبطأ من استخدام الترميز الحرفي للكائنات (كما هو موضّح في ما يلي)، ولكن في الجداول الأصغر (مثل 1,000 خلية)، قد لا تلاحظ اختلافًا كبيرًا. -
يكون التعريف المباشر لكائن
DataTable
باستخدام الترميز الحرفي للعنصر أسرع بشكل ملحوظ في الجداول الكبيرة. ومع ذلك، قد يكون من الصعب استخدام هذه البنية بشكل صحيح، لذلك ننصحك باستخدام هذه الخاصية إذا كان بإمكانك إنشاء البنية الحرفية للكائن في الرمز، ما يقلّل من احتمال حدوث أخطاء.
الطُرق
الطريقة | قيمة الإرجاع | الوصف |
---|---|---|
أو
|
الرقم |
لإضافة عمود جديد إلى جدول البيانات، وعرض فهرس العمود الجديد. يتم تخصيص قيمة يحتوي التوقيع الأول على المعلمات التالية:
يتضمّن التوقيع الثاني معلّمة كائن واحدة مع الأعضاء التاليين:
يُرجى الاطِّلاع أيضًا على: getColumnId وgetColumnLabel وgetColumnType وinsertColumn وgetColumnRole. |
addRow(opt_cellArray) |
الرقم |
لإضافة صف جديد إلى جدول البيانات، وعرض فهرس الصف الجديد.
أمثلة: 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) |
الرقم |
لإضافة صفوف جديدة إلى جدول البيانات، وعرض فهرس آخر صف تمت إضافته. ويمكنك استدعاء هذه الطريقة لإنشاء صفوف فارغة جديدة، أو باستخدام البيانات المستخدمة لتعبئة الصفوف، كما هو موضّح أدناه.
مثال: 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) |
سلسلة |
لعرض نمط التنسيق المستخدم لتنسيق قيم العمود المحدد.
بالنسبة إلى جداول البيانات التي يتم استردادها من خلال طلبات البحث، يتم تحديد نمط العمود بواسطة مصدر البيانات،
أو من خلال عبارة |
getColumnProperties(columnIndex)
|
اعتراض |
لعرض خريطة بكل الخصائص للعمود المحدد. لاحظ أنه يتم عرض كائن الخصائص
من خلال الرجوع، لذا يؤدي تغيير القيم في العنصر الذي تم استرداده إلى تغييرها في
|
getColumnProperty(columnIndex, name)
|
تلقائي |
لعرض قيمة الخاصية المسماة أو
يُرجى الاطّلاع أيضًا على: setColumnProperty setColumnProperties |
getColumnRange(columnIndex) |
اعتراض |
لعرض القيم الدنيا والقصوى للقيم في عمود محدد. الكائن المعروض يحتوي على الخاصيتين
يجب أن يكون |
getColumnRole(columnIndex) |
سلسلة | لعرض دور العمود المحدّد. |
getColumnType(columnIndex) |
سلسلة |
لعرض نوع عمود معين تم تحديده بواسطة فهرس العمود.
يمكن أن يكون نوع العمود المعروض واحدًا مما يلي: |
getDistinctValues(columnIndex) |
مصفوفة من الكائنات |
لعرض القيم الفريدة في عمود معيّن، تصاعديًا.
نوع الكائنات المعروضة هو النوع نفسه الذي تم عرضه باستخدام طريقة |
getFilteredRows(filters) |
مصفوفة من الكائنات |
لعرض فهارس الصفوف للصفوف التي تتطابق مع جميع الفلاتر المحددة. ويتم عرض الفهارس بشكل تصاعدي. يمكن استخدام ناتج هذه الطريقة كإدخال إلى
تحدد الخاصية الاختيارية الأخرى
مثال: تعرض |
getFormattedValue(rowIndex, columnIndex)
|
سلسلة |
لعرض القيمة المنسقة للخلية في فهارس الأعمدة والصفوف المحددة.
للحصول على مزيد من المعلومات عن تنسيق قيم الأعمدة، يمكنك الاطّلاع على مرجع لغة طلب البحث. يُرجى الاطِّلاع أيضًا على: setFormattedValue |
getNumberOfColumns() |
الرقم | لعرض عدد الأعمدة في الجدول. |
getNumberOfRows() |
الرقم | لعرض عدد الصفوف في الجدول. |
getProperties(rowIndex, columnIndex)
|
اعتراض |
لعرض خريطة بجميع الخصائص للخلية المحددة. لاحظ أن كائن الخصائص
يتم عرضه كمرجع، لذا يؤدي تغيير القيم في الكائن المسترد إلى تغييرها في
|
getProperty(rowIndex, columnIndex, name)
|
تلقائي |
لعرض قيمة الخاصية المسماة أو
يُرجى الاطّلاع أيضًا على: setCell setProperties setProperty |
getRowProperties(rowIndex)
|
اعتراض |
لعرض خريطة بكل الخصائص للصف المحدّد. لاحظ أنه يتم عرض كائن الخصائص
من خلال الرجوع، لذا يؤدي تغيير القيم في العنصر الذي تم استرداده إلى تغييرها في
|
getRowProperty(rowIndex, name)
|
تلقائي |
لعرض قيمة الخاصية المُسمّاة أو
يُرجى الاطِّلاع أيضًا على: setRowProperty setRowProperties |
getSortedRows(sortColumns) |
مصفوفة الأرقام |
لعرض نسخة مصنفة من الجدول بدون تعديل ترتيب البيانات الأساسية.
لترتيب البيانات الأساسية بشكل دائم، يُرجى الاتصال بالرقم
القيمة المعروضة عبارة عن مصفوفة من الأرقام، كل رقم عبارة عن فهرس لصف
يُرجى العِلم أنّ عملية الترتيب تضمن أن تكون ثابتة: هذا يعني أنه في حال الترتيب على قيم متساوية في صفَين، ستعرض عملية الترتيب نفسها الصفوف بالترتيب نفسه في كل مرة. مثال: للتكرار في الصفوف مرتبة حسب العمود الثالث، استخدم: var rowInds = data.getSortedRows([{column: 2}]); for (var i = 0; i < rowInds.length; i++) { var v = data.getValue(rowInds[i], 2); } |
getTableProperties
|
اعتراض | لعرض خريطة بكل خصائص الجدول. |
getTableProperty(name) |
تلقائي |
لعرض قيمة الخاصية المسماة أو
يُرجى الاطّلاع أيضًا على: setTableProperties setTableProperty |
getValue(rowIndex, columnIndex) |
اعتراض |
لعرض قيمة الخلية في فهارس الصفوف والأعمدة المحددة.
ويعتمد نوع القيمة المعروضة على نوع العمود (يُرجى الاطّلاع على getColumnType):
|
insertColumn(columnIndex, type [,label [,id]])
|
لا ينطبق |
إدراج عمود جديد في جدول البيانات في الفهرس المحدد. ويتم تحويل جميع الأعمدة الحالية في الفهرس المحدّد أو بعده إلى فهرس أعلى.
راجع أيضًا: addColumn |
insertRows(rowIndex, numberOrArray) |
لا ينطبق |
إدراج عدد الصفوف المحدّد في فهرس الصفوف المحدّد.
راجع أيضًا: addRows |
removeColumn(columnIndex) |
لا ينطبق |
إزالة العمود في الفهرس المحدد.
راجع أيضًا: إزالة الأعمدة |
removeColumns(columnIndex, numberOfColumns)
|
لا ينطبق |
إزالة العدد المحدد للأعمدة بدءًا من العمود في الفهرس المحدد.
راجع أيضًا: removeColumn |
removeRow(rowIndex) |
لا ينطبق |
إزالة الصف في الفهرس المحدد.
راجع أيضًا: removeRows |
removeRows(rowIndex, numberOfRows) |
لا ينطبق |
إزالة عدد الصفوف المحدد بدءًا من الصف في الفهرس المحدد.
راجع أيضًا: removeRow |
setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]])
|
لا ينطبق |
لتعيين قيمة و/أو قيمة منسقة و/أو خصائص خلية.
يُرجى الاطِّلاع أيضًا على: setValue(), setFormattedValue(), setProperty(), setProperties(). |
setColumnLabel(columnIndex, label)
|
لا ينطبق |
لتعيين تصنيف العمود.
راجع أيضًا: getColumnLabel |
setColumnProperty(columnIndex, name, value)
|
لا ينطبق |
لتعيين موقع على عمود واحد. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطِّلاع أيضًا على:setColumnProperties getColumnProperty |
setColumnProperties(columnIndex, properties)
|
لا ينطبق |
لتعيين خصائص أعمدة متعددة. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطّلاع أيضًا على: setColumnProperty getColumnProperty |
setFormattedValue(rowIndex, columnIndex, formattedValue)
|
لا ينطبق |
لتعيين القيمة المنسقة للخلية.
يُرجى الاطِّلاع أيضًا على: getFormattedValue |
setProperty(rowIndex, columnIndex, name, value)
|
لا ينطبق |
لتعيين خاصية خلية. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطّلاع أيضًا على: setCell setProperties getProperty |
setProperties(rowIndex, columnIndex, properties)
|
لا ينطبق |
لتعيين خصائص خلايا متعددة. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطّلاع أيضًا على: setCell setProperty getProperty |
setRowProperty(rowIndex, name, value)
|
لا ينطبق |
لضبط خاصية صف. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطِّلاع أيضًا على: setRowProperties getRowProperty |
setRowProperties(rowIndex, properties)
|
لا ينطبق |
لتعيين خصائص صفوف متعددة. تتيح بعض التمثيلات البصرية خصائص الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطِّلاع أيضًا على: setRowProperty getRowProperty |
setTableProperty(name, value)
|
لا ينطبق |
لتعيين خاصية جدول واحدة. وتتيح بعض التمثيلات البصرية خصائص الجدول أو الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطّلاع أيضًا على: setTableProperties getTableProperty |
setTableProperties(properties) |
لا ينطبق |
لتعيين خصائص جدول متعددة. وتتيح بعض التمثيلات البصرية خصائص الجدول أو الصف أو العمود أو الخلية لتعديل طريقة العرض أو السلوك، ويمكنك الاطّلاع على مستندات التمثيل البصري لمعرفة الخصائص المتاحة.
يُرجى الاطِّلاع أيضًا على: setTableProperty getTableProperty |
setValue(rowIndex, columnIndex, value) |
لا ينطبق |
لتعيين قيمة خلية. بالإضافة إلى استبدال أي قيمة خلية حالية، ستمحو هذه الطريقة أيضًا أي قيمة وخصائص منسَّقة للخلية.
راجِع أيضًا: 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
على مجموعة من كائنات الصفوف.
يحتوي كل كائن صف على خاصية مطلوبة واحدة تسمى 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.
الطُرق
الطريقة | قيمة الإرجاع | الوصف |
---|---|---|
يمكنك الاطّلاع على الأوصاف باللغة DataTable . |
هذه الطريقة مماثلة لطُرق DataTable المكافئة، باستثناء أنّ فهارس الصفوف/الأعمدة تشير إلى الفهرس في الملف الشخصي وليس في الجدول/طريقة العرض الأساسية.
|
|
getTableColumnIndex(viewColumnIndex)
|
الرقم |
لعرض الفهرس في الجدول الأساسي (أو العرض) لعمود معيّن تم تحديده من خلال الفهرس
في هذا العرض. يجب أن يكون
مثال: إذا تم استدعاء |
getTableRowIndex(viewRowIndex) |
الرقم |
لعرض الفهرس في الجدول الأساسي (أو العرض) لصف معين محدّد بالفهرس في
طريقة العرض هذه. يجب أن يكون
مثال: إذا تم استدعاء |
getViewColumnIndex(tableColumnIndex)
|
الرقم |
لعرض الفهرس في طريقة العرض هذه التي تم تعيينها إلى عمود معين محدد بواسطة الفهرس في الجدول الأساسي (أو العرض). إذا كان هناك أكثر من فهرس، يتم عرض أول (أصغر) فهرس. في حالة عدم وجود هذا الفهرس (العمود المحدد ليس في العرض)، يتم إرجاع -1.
يجب أن يكون
مثال: إذا تم استدعاء |
getViewColumns() |
مصفوفة الأرقام |
لعرض الأعمدة في هذا العرض بالترتيب. وهذا يعني أنه إذا تم استدعاء |
getViewRowIndex(tableRowIndex) |
الرقم |
لعرض الفهرس في طريقة العرض هذه التي تم تعيينها لصف معين محدد بواسطة الفهرس في الجدول الأساسي (أو العرض). إذا كان هناك أكثر من فهرس، يتم عرض أول (أصغر) فهرس. في حالة عدم وجود مثل هذا الفهرس (الصف المحدد ليس في العرض)، يتم إرجاع -1.
يجب أن يكون
مثال: إذا تم استدعاء |
getViewRows() |
مصفوفة الأرقام |
لعرض الصفوف في هذا العرض بالترتيب. وهذا يعني أنه إذا استدعيت |
hideColumns(columnIndexes) |
لا ينطبق |
لإخفاء الأعمدة المحددة من العرض الحالي.
مثال: إذا كان لديك جدول يحتوي على 10 أعمدة واستدعيت |
hideRows(min, max) |
لا ينطبق |
لإخفاء جميع الصفوف التي تتضمن فهارس تقع بين الحد الأدنى والحد الأقصى (شامل) من العرض الحالي.
هذه بنية ملاءمة لـ |
hideRows(rowIndexes) |
لا ينطبق |
لإخفاء الصفوف المحددة من العرض الحالي.
مثال: إذا كان لديك جدول يتكون من 10 صفوف، واستدعيت
|
setColumns(columnIndexes) |
لا ينطبق |
لتحديد الأعمدة التي تظهر في هذا العرض. وسيتم إخفاء أي أعمدة لم يتم تحديدها. هذه هي مجموعة من فهارس الأعمدة في الجدول/العرض الأساسي أو الأعمدة المحسوبة. في حال عدم استدعاء هذه الطريقة، يكون الوضع التلقائي هو عرض جميع الأعمدة. ويمكن أن تحتوي المصفوفة أيضًا على نُسخ مكررة، لعرض العمود نفسه عدة مرات. سيتم عرض الأعمدة بالترتيب المحدد.
أمثلة: // 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) |
لا ينطبق |
يضبط الصفوف المرئية في طريقة العرض هذه، استنادًا إلى أرقام الفهرس من الجدول/طريقة العرض الأساسية.
يجب أن يكون
مثال: لإنشاء طريقة عرض تحتوي على الصفَّين الثالث والصفر من جدول/طريقة عرض أساسية: |
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) |
لا ينطبق |
لرسم المخطط. يجب استدعاء هذه الطريقة بعد أي تغييرات تجريها على الرسم البياني أو البيانات لعرض التغييرات.
|
toJSON() |
سلسلة | لعرض إصدار سلسلة من تمثيل JSON للرسم البياني. |
clone() |
مغلّف الرسم البياني | لعرض نسخة عميقة من برنامج تضمين المخطط. |
getDataSourceUrl() |
سلسلة | إذا كان هذا الرسم البياني يحصل على بياناته من مصدر بيانات، سيعرض عنوان URL لمصدر البيانات هذا. وإلا، فسيتم إرجاع القيمة فارغة. |
getDataTable() |
google.Visualization.DataTable |
إذا حصل هذا الرسم البياني على بياناته من
وستظهر أي تغييرات تجريها على العنصر المعروض في الرسم البياني في المرة التالية التي يتم فيها استدعاء |
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) |
أي نوع |
لعرض قيمة خيار المخطط المحدد
|
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:
-
تحميل حزمة
charteditor
. فيgoogle.charts.load()
، حمِّل الحزمة "charteditor". لا تحتاج إلى تحميل الحزم لنوع الرسم البياني الذي تعرضه في المحرِّر، سيحمّل محرّر الرسم البياني أي حزمة لك عند الحاجة. -
أنشئ كائن
ChartWrapper
يحدّد الرسم البياني للمستخدم لتخصيصه. وسيتم عرض هذا الرسم البياني في مربّع الحوار، وسيستخدم المستخدم أداة التعديل لإعادة تصميم الرسم البياني أو تغيير أنواع الرسوم البيانية أو حتى تغيير بيانات المصدر. -
أنشِئ نسخة افتراضية جديدة من ChartEditor وسجِّل الفيديو للاستماع إلى الفعالية "حسنًا". يتم طرح هذه الفعالية عندما ينقر المستخدم على الزر "حسنًا" في مربّع الحوار. عند الاستلام، يجب الاتصال بالرقم
ChartEditor.getChartWrapper()
لاسترداد الرسم البياني الذي عدّله المستخدم. -
اتصل برقم
ChartEditor.openDialog()
، مع مرورChartWrapper
. سيؤدي هذا إلى فتح مربع الحوار. وتمكّن أزرار مربّع الحوار المستخدم من إغلاق أداة التعديل. يتوفّر المثيلChartEditor
طالما أنّه في النطاق، ولا يتم إتلافه تلقائيًا بعد إغلاق المستخدم لمربّع الحوار. - لتعديل الرسم البياني في الرمز، يمكنك الاتصال بالرقم
setChartWrapper()
.
الطُرق
الطريقة | قيمة الإرجاع | الوصف |
---|---|---|
openDialog(chartWrapper, opt_options) |
قيمة فارغة |
لفتح محرر المخطط كمربع حوار مضمن في الصفحة. تعود الدالة
على الفور، ولا تنتظر إغلاق مربّع الحوار. إذا لم تفقد نطاق المثيل، يمكنك استدعاء
|
getChartWrapper() |
ChartWrapper |
لعرض ChartWrapper الذي يمثل الرسم البياني، مع تعديلات المستخدم. |
setChartWrapper(chartWrapper) |
قيمة فارغة |
استخدِم هذه الطريقة لتعديل الرسم البياني المعروض على المحرِّر.
chartWrapper - كائن |
closeDialog() |
قيمة فارغة | لإغلاق مربع حوار محرر المخطط. |
الخيارات
يدعم محرر الرسم البياني الخيارات التالية:
الاسم | النوع | القيمة التلقائية | الوصف |
---|---|---|---|
dataSourceInput |
مقبض العنصر أو "urlbox" | قيمة فارغة |
استخدم هذا الخيار لتمكين المستخدم من تحديد مصدر بيانات للرسم البياني. يمكن أن تكون هذه الخاصية واحدة من قيمتَين:
|
الأحداث
يقدم محرر المخطط الأحداث التالية:
الاسم | الوصف | أماكن إقامة |
---|---|---|
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
المعبأ. - لكل عمود تريد إعادة تنسيقه:
- أنشئ كائنًا يحدد جميع خيارات أداة التنسيق. هذا كائن JavaScript أساسي يتضمّن مجموعة من الخصائص والقيم. راجِع مستندات أداة التنسيق لمعرفة الخصائص المتوافقة. (يمكنك اختياريًا تمرير كائن الترميز الحرفي للكائن لتحديد خياراتك).
- أنشئ أداة التنسيق، مع تمرير كائن الخيارات.
-
استدعِ
formatter
.format(table, colIndex)
، مع إدخال رقم العمودDataTable
و (بدون صفر) في البيانات المطلوب إعادة تنسيقها. تجدر الإشارة إلى أنه يمكنك تطبيق تنسيق واحد فقط على كل عمود، وسيؤدي تطبيق تنسيق ثانٍ إلى استبدال تأثيرات التنسيق الأول فقط.
ملاحظة مهمة: تتطلب العديد من أدوات التنسيق علامات HTML لعرض تنسيق خاص، وإذا كان التمثيل البصري يتيح خيارallowHtml
، يجب ضبطه على true.
يُنسَّق التنسيق الفعلي المطبَّق على البيانات من اللغة التي تم تحميل واجهة برمجة التطبيقات بها. لمزيد من التفاصيل، يمكنك الاطّلاع على تحميل الرسوم البيانية بلغة معيّنة .
ملاحظة مهمة: لا يمكن استخدام أدوات التنسيق إلا مع DataTable
، ولا يمكن استخدامها مع DataView
(عناصر DataView
للقراءة فقط).
في ما يلي الخطوات العامة لاستخدام منسق التنسيق:
في ما يلي مثال على تغيير قيم التاريخ المنسّقة لعمود التاريخ لاستخدام تنسيق تاريخ طويل ("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.
// 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) |
إعادة تنسيق البيانات في العمود المحدّد.
|
توفر واجهة برمجة تطبيقات الرسوم المرئية في 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.
|
addGradientRange(from, to, color, fromBgColor,
toBgColor)
|
لتحديد لون خلفية من نطاق، وفقًا لقيمة الخلية. ويتم تغيير حجم اللون
لمطابقة قيمة الخلية في نطاق يتراوح من لون الحد السفلي إلى لون
الحد العلوي. تجدر الإشارة إلى أن هذه الطريقة لا يمكنها مقارنة قيم السلسلة، حيث إن
|
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 كما هو موضح:
لا يمكنك تحديد كل من |
pattern |
نمط تنسيق مخصّص لتطبيقه على القيمة، يكون مشابهًا لتنسيق التاريخ والوقت في وحدة المعالجة المركزية (ICU).
على سبيل المثال:
لا يمكنك تحديد كل من |
timeZone |
المنطقة الزمنية التي سيتم عرض قيمة التاريخ فيها. هذه قيمة رقمية تشير إلى GMT +
هذا العدد من المناطق الزمنية (يمكن أن تكون سالبة). يتم إنشاء كائن التاريخ تلقائيًا باستخدام
المنطقة الزمنية المُفترضة لجهاز الكمبيوتر الذي يتم إنشاؤها عليه. ويُستخدم هذا الخيار لعرض
هذه القيمة في منطقة زمنية مختلفة. على سبيل المثال، إذا أنشأت كائن التاريخ في الساعة 5 مساءً على جهاز كمبيوتر في غرينتش، إنجلترا، وحددت المنطقة الزمنية لتكون -5 (options['timeZone'] = -5 ، أو توقيت شرق المحيط الهادئ في الولايات المتحدة)، ستكون القيمة المعروضة 12 ظهرًا.
|
الطُرق
DateFormat
يدعم الطرق التالية:
الطريقة | الوصف |
---|---|
google.visualization.DateFormat(options) |
المُنشئ. راجع قسم الخيارات أعلاه للحصول على مزيد من المعلومات. |
format(dataTable, columnIndex) |
تمثّل هذه السمة طريقة format() العادية لتطبيق التنسيق على العمود المحدّد. |
formatValue(value) |
لعرض القيمة المنسقة لقيمة معينة.
لا تتطلب هذه الطريقة |
نموذج التعليمات البرمجية
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 |
ذكر |
شهر في السنة. لشهر كانون الثاني (يناير):
|
"يوليو" "07" |
يوم | يوم في الشهر. ستضيف القيم الإضافية "d" أصفارًا بادئة. | 10 |
ساعة | ساعة بتنسيق 12 ساعة. ستضيف قيم 'h' الإضافية أصفارًا بادئة. | 12 |
مرتفع | ساعة بتنسيق 24 ساعة. ستضيف قيم Hk الإضافية الأصفار البادئة. | 0 |
m | دقيقة في الساعة. ستضيف قيم "M" الإضافية أصفارًا بادئة. | 30 |
s | ثانية في الدقيقة. ستضيف قيم 's' الإضافية أصفارًا بادئة. | 55 |
S | كسور ثانية. سيتم وضع قيم "S" الإضافية على اليسار بالأصفار. | 978 |
E |
يوم من الأسبوع. النتائج التالية ليوم "الثلاثاء":
|
"الثلاثاء" "الثلاثاء" |
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 |
سلسلة تنسيق. ويتم تجاهل جميع الخيارات الأخرى عند تقديمها، باستثناء
سلسلة التنسيق هي مجموعة فرعية من
مجموعة أنماط وحدة العناية المركزة
.
على سبيل المثال، سينتج عن القيم |
prefix |
بادئة سلسلة للقيمة، على سبيل المثال "$". |
suffix |
لاحقة سلسلة للقيمة، مثل "%" |
الطُرق
NumberFormat
يدعم الطرق التالية:
الطريقة | الوصف |
---|---|
google.visualization.NumberFormat(options) |
المُنشئ. راجع قسم الخيارات أعلاه للحصول على مزيد من المعلومات. |
format(dataTable, columnIndex) |
طريقة format() القياسية لتطبيق التنسيق على العمود المحدّد. |
formatValue(value) |
لعرض القيمة المنسقة لقيمة معينة. لا تتطلب هذه الطريقة |
نموذج التعليمات البرمجية
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. هذه سلسلة تصف قيم الأعمدة التي يجب وضعها في عمود الوجهة، إلى جانب أي نص عشوائي. يمكنك تضمين العناصر النائبة في السلسلة للإشارة إلى قيمة
من عمود آخر لتضمينها. العناصر النائبة هي
نموذج التعليمات البرمجيةيوضح المثال التالي دالة إنشاء لنمط ينشئ عنصر ارتساء، مع أول عنصر ثاني وثاني مأخوذ من طريقة var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>'); |
format(dataTable, srcColumnIndices,
opt_dstColumnIndex)
|
استدعاء التنسيق القياسي، مع بعض المعلمات الإضافية:
اطّلع على أمثلة التنسيق بعد الجدول. |
في ما يلي بعض الأمثلة على الإدخالات والإخراجات لجدول مكوّن من أربعة أعمدة.
Row before formatting (4 columns, last is blank): John | Paul | Jones | [empty] var formatter = new google.visualization.PatternFormat("{0} {1} {2}"); formatter.format(data, [0,1,2], 3); Output: John | Paul | Jones | John Paul Jones var formatter = new google.visualization.PatternFormat("{1}, {0}"); formatter.format(data, [0,2], 3); Output: John | Paul | Jones | Jones, John
نموذج التعليمات البرمجية
يوضح المثال التالي كيفية دمج البيانات من عمودين لإنشاء عنوان بريد إلكتروني. وتستخدم هذه العلامة كائن DataView لإخفاء أعمدة المصدر الأصلية:
var data = new google.visualization.DataTable(); data.addColumn('string', 'Name'); data.addColumn('string', 'Email'); data.addRows([ ['John Lennon', 'john@beatles.co.uk'], ['Paul McCartney', 'paul@beatles.co.uk'], ['George Harrison', 'george@beatles.co.uk'], ['Ringo Starr', 'ringo@beatles.co.uk'] ]); var table = new google.visualization.Table(document.getElementById('patternformat_div')); var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>'); // Apply formatter and set the formatted value of the first column. formatter.format(data, [0, 1]); var view = new google.visualization.DataView(data); view.setColumns([0]); // Create a view with the first column only. table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});
أداة المساعدة
فئة مساعدة لتبسيط كتابة الأدوات التي تستخدم واجهة برمجة التطبيقات للتمثيل البصري في Google.
الشركة المصنِّعة
google.visualization.GadgetHelper()
الطُرق
الطريقة | قيمة الإرجاع | الوصف |
---|---|---|
createQueryFromPrefs(prefs) |
google.Visualization.Query |
ثابتة. أنشئ مثيلاً جديدًا من google.visualization.Query وعيّن خصائصه وفقًا للقيم من تفضيلات الأداة. نوع المَعلمة prefs هو _IG_Prefs
|
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'.
-
sendMethod - [اختيارية، سلسلة] تحدّد الطريقة المطلوب استخدامها لإرسال طلب البحث. اختَر إحدى قيم السلسلة التالية:
الطُرق
الطريقة | قيمة الإرجاع | الوصف |
---|---|---|
abort() |
لا ينطبق |
لإيقاف إرسال طلب البحث المبرمج الذي بدأ باستخدام setRefreshInterval() .
|
setRefreshInterval(seconds)
|
لا ينطبق |
يضبط طلب البحث لاستدعاء الطريقة إذا كنت تستخدم هذه الطريقة، يجب الاتصال بها قبل استدعاء طريقة
ويمكنك إلغاء هذه الطريقة من خلال إعادة الاتصال بصفر (الإعداد التلقائي) أو الاتصال بـ |
setTimeout(seconds) |
لا ينطبق |
لتحديد عدد الثواني التي يتم خلالها انتظار استجابة مصدر البيانات قبل ظهور خطأ انتهاء المهلة. seconds رقم أكبر من صفر. المهلة التلقائية هي 30 ثانية. ويجب استخدام هذه الطريقة في حال استخدامها قبل طلب طريقة send .
|
setQuery(string) |
لا ينطبق |
لتعيين سلسلة طلب البحث. يجب أن تكون قيمة المَعلمة string طلب بحث
صالحًا. إذا تم استخدام هذه الطريقة، يجب طلبها قبل طلب طريقة send .
مزيد من المعلومات حول لغة طلب البحث.
|
send(callback) |
لا ينطبق |
لإرسال الاستعلام إلى مصدر البيانات. يجب أن تكون callback دالة سيتم استدعاءها عندما يستجيب مصدر البيانات. ستتلقى دالة رد الاتصال معلمة واحدة من النوع google.visibleization.QueryResponse.
|
طلب استجابة
يمثل استجابة لتنفيذ طلب البحث كما تم استلامها من مصدر البيانات. يتم تمرير مثال على هذه الفئة كوسيطة لدالة معاودة الاتصال التي تم ضبطها عند استدعاء Query.send.
الطُرق
الطريقة | قيمة الإرجاع | الوصف |
---|---|---|
getDataTable() |
جدول البيانات |
لعرض جدول البيانات كما يعرضه مصدر البيانات. لعرض null إذا تعذّر تنفيذ طلب البحث ولم يتم عرض أي بيانات.
|
getDetailedMessage() |
سلسلة | لعرض رسالة خطأ تفصيلية لطلبات البحث التي أخفقت. إذا تم تنفيذ طلب البحث بنجاح، تعرض هذه الطريقة سلسلة فارغة. الرسالة المعروضة هي رسالة مخصصة لمطوري البرامج، وقد تحتوي على معلومات فنية، على سبيل المثال "العمود {salary} غير موجود". |
getMessage() |
سلسلة | لعرض رسالة خطأ قصيرة لطلبات البحث التي أخفقت. إذا تم تنفيذ طلب البحث بنجاح، ستعرض هذه الطريقة سلسلة فارغة. الرسالة المعروضة هي رسالة قصيرة تستهدف المستخدمين النهائيين، على سبيل المثال "طلب بحث غير صالح" أو "تم رفض الدخول". |
getReasons() |
مصفوفة من السلاسل |
لعرض صفيف من صفر من الإدخالات الإضافية. كل إدخال عبارة عن سلسلة قصيرة يظهر فيها خطأ أو رمز تحذير تم طرحه أثناء تنفيذ طلب البحث. الرموز المحتملة:
|
hasWarning() |
منطقي | لعرض true إذا كان تنفيذ طلب البحث يحتوي على أي رسائل تحذير. |
isError() |
منطقي |
لعرض true إذا تعذّر تنفيذ طلب البحث، ولا تحتوي الاستجابة على أي جدول بيانات. لعرض <false> في حال نجاح تنفيذ طلب البحث وكانت الاستجابة تحتوي على جدول بيانات.
|
عرض الخطأ
توفر واجهة برمجة التطبيقات العديد من الوظائف لمساعدتك على عرض رسائل خطأ مخصصة للمستخدمين. لاستخدام
هذه الدوال، يجب توفير عنصر حاوية على الصفحة (عادةً
<div>
)، بحيث ترسم واجهة برمجة التطبيقات رسالة خطأ منسقة فيها. ويمكن أن تكون هذه الحاوية
عنصر حاوية التمثيل البصري أو حاوية للأخطاء فقط. إذا حدّدت
عنصر التمثيل البصري للاحتواء، ستظهر رسالة الخطأ أعلى التمثيل البصري.
بعد ذلك يمكنك استدعاء الوظيفة المناسبة أدناه لعرض رسالة الخطأ أو إزالتها.
جميع الدوال هي وظائف ثابتة في مساحة الاسم google.visualization.errors
.
يمكن أن تعرض العديد من التمثيلات البصرية حدث خطأ، ويمكنك الاطّلاع على حدث الخطأ أدناه لمعرفة المزيد من المعلومات حول ذلك.
يمكنك الاطّلاع على مثال لخطأ مخصّص في مثال التفاف طلب البحث.
الوظيفة | قيمة الإرجاع | الوصف |
---|---|---|
addError(container, message, opt_detailedMessage,
opt_options)
|
قيمة رقم تعريف السلسلة التي تحدد كائن الخطأ الذي تم إنشاؤه. وهذه القيمة فريدة في الصفحة، ويمكن استخدامها لإزالة الخطأ أو العثور على عنصره المضمّن. |
لإضافة قالب عرض الخطأ إلى عنصر الصفحة المحدد، مع تحديد النص والتنسيق.
|
addErrorFromQueryResponse(container, response) |
قيمة رقم تعريف السلسلة التي تحدّد كائن الخطأ الذي تم إنشاؤه، أو تكون خالية إذا لم توجِه الاستجابة إلى حدوث خطأ. هذه قيمة فريدة على الصفحة، ويمكن استخدامها لإزالة الخطأ أو العثور على عنصره المضمّن. |
تمرير الاستجابة لطلب البحث وعاء رسالة الخطأ إلى هذه الطريقة: إذا كانت استجابة طلب البحث تشير إلى وجود خطأ في طلب البحث، فسيتم عرض رسالة خطأ في عنصر الصفحة المحدد. وإذا كانت استجابة طلب البحث فارغة، ستعرض الطريقة خطأ JavaScript. مرِّر
QueryResponse الذي تم استلامه في معالج طلب البحث إلى هذه الرسالة
لعرض رسالة خطأ. وسيؤدي أيضًا إلى ضبط نمط العرض المناسب للنوع (خطأ أو تحذير، على غرار
|
removeError(id) |
قيمة منطقية: true إذا تمت إزالة الخطأ، أو على "false" في الحالات الأخرى. |
يزيل الخطأ المحدد برقم التعريف من الصفحة.
|
removeAll(container) |
لا ينطبق |
يزيل جميع أجزاء الأخطاء من حاوية محددة. وفي حال عدم توفّر الحاوية المحدّدة، سيؤدي ذلك إلى حدوث خطأ.
|
getContainer(errorId) |
تعامل مع عنصر DOM الذي يحتوي على الخطأ المحدد أو فارغًا إذا تعذر العثور عليه. |
لاسترداد مقبض لعنصر الحاوية الذي يحمل الخطأ المحدد بواسطة errorID.
|
الأحداث
وتؤدي معظم التمثيلات البصرية إلى تنشيط الأحداث للإشارة إلى حدوث شيء ما. بصفتك مستخدمًا للرسم البياني، غالبًا ما تريد الاستماع إلى هذه الفعاليات. في حال ترميز التمثيل البصري الخاص بك، قد تحتاج أيضًا إلى تشغيل هذه الأحداث بنفسك.
تتيح الطرق التالية لمطوّري البرامج إمكانية الاستماع إلى الأحداث أو إزالة معالجات الأحداث الحالية أو تشغيل الأحداث من داخل التمثيل البصري.
- 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()
هذه دالة إنشاء لعنصر شريط الأدوات الذي يمكن إرفاقه بالعديد من التمثيلات البصرية. يمكّن شريط الأدوات هذا المستخدم من تصدير بيانات التمثيل البصري إلى تنسيقات مختلفة، أو توفير نسخة قابلة للتضمين من التمثيل البصري للاستخدام في أماكن مختلفة. يمكنك الاطّلاع على صفحة شريط الأدوات للحصول على مزيد من المعلومات ومثال على الرمز.