استخدام مكتبة المساعد

تستخدم أداة Looker Studio واجهة postMessage لتوفير بيانات وأنماط في إطار iframe الذي يحتوي على العرض المرئي للمنتدى. يقدّم هذا الدليل مزيدًا من التفاصيل حول استخدام مكتبة المساعدة.

بالنسبة إلى العروض المرئية للمنتديات، يؤدي ds-component إلى وظيفتَين.

1. الحصول على أبعاد iframe
2. إدارة التواصل باستخدام Looker Studio

الاشتراك في الفعاليات

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

تسجِّل dscc.subscribeToData معاودة اتصال سيتم استدعاءها لكل حدث postMessage من Looker Studio. يتم تمرير كائن data من رد الاتصال.

function drawViz(data){
  // obtain the height and width to scale your visualization appropriately
  var height = dscc.getHeight();
  var width = dscc.getWidth();
  // write your visualization code here
  console.log("I'm the callback and I was passed this data: " + JSON.stringify(data, null, '  '));
}

// call drawViz every time Looker Studio sends a new postMessage
dscc.subscribeToData(drawViz, {transform: dscc.objectTransform});

البيانات المعروضة

يؤدي كلا عملي تحويل البيانات إلى إرجاع كائن بخمسة مفاتيح.

المفتاح	الغرض
style	معلومات النمط التلقائي التي اختارها المستخدم
fields	معلومات الحقول التي اختارها المستخدم
interactions	التفاعلات التي اختارها المستخدِمون
theme	الإبلاغ عن معلومات المظهر
tables	صفوف البيانات
dateRanges	النطاقات الزمنية التلقائية والنطاقات الزمنية للمقارنة

تنسيق البيانات:

{
  fields: object(fieldsByConfigId),
  style: object(styleById),
  interactions: object(interactionsById),
  theme: object(themeStyle),
  tables: object(tablesById),
  dateRanges: object(dateRangesById),
}

تتطلب التصورات المختلفة تنسيقات بيانات مختلفة. هناك تنسيقان شائعان هما صفيف من الصفائف أو مصفوفة من الكائنات. توفِّر مكتبة مكوّنات DS، تحويلَين مصممَين لتصلك مباشرةً إلى تنسيقات البيانات هذه.

وتم توثيق عمليتَي التحويل في library-reference. وتؤدي هذه التغيُّرات إلى الربط بسهولة مع تنسيقات البيانات المتوقَّعة عادةً من مكتبات تصوير JavaScript. عمليتا التحويل المتوافقتان هما: objectTransform، الذي يعرض صفيفًا من الكائنات، وtableTransform الذي يعرض صفيفًا من المصفوفات.

dscc.objectTransform

تتوقع بعض التصورات البيانات كمجموعة من الكائنات.

مثال:

var data = [
  {'colA': 'hello', 'colB', 'world'},
  {'colA': 'hello', 'colB', 'world'}
];

يعرض الرمز التالي طريقة الوصول إلى مصفوفة من العناصر من خلال تنسيق dscc.objectTransform.

function drawViz(data){
  // what the object transform could look like
  // [
  //  {'configId1': ['hello'], 'configId2': [1] },
  //  {'configId1': ['world'], 'configId2': [2] }
  // ]
  var dsccObjectTransformData = data.tables.DEFAULT;

  // creating an array of objects
  var arrayOfObjects = dscc.ObjectTransformData.rows.map(function(d){
    return {
      'configId1': d.configId1[0],
      'configId2': d.configId2[0]
    };
  };

}

إذا تم تحديد أقسام البيانات بحيث يمكن للمستخدم إدخال حقول متعددة (على سبيل المثال، إذا كان هناك بُعدان محدّدان للرسم التخطيطي الدقيق)، سيعتمد التحويل على حالة الاستخدام، لأنّ تنسيق البيانات الذي تعرضه أداة Looker Studio سيبدو أكثر على النحو التالي:

var dsccObjectTransformData = [
{'configId1': ['hello', 'there'], 'configId2': [1] },
{'configId1': ['world', 'globe'], 'configId2': [2] }
]

ملاحظة: ستعتمد عمليات تحويل البيانات المطلوبة على إعدادات التمثيل المرئي للبيانات.

dscc.tableTransform

تتوقع بعض مكتبات العروض المرئية مجموعة من الصفائف.

مثال:

var data = [
  ['hello', 1],
  ['world', 2]
];

ويوضّح الرمز التالي كيفية الوصول إلى صف من الصفوف من تنسيق dscc.tableTransform.

function drawViz(data);
  // what the below object looks like
  // {
  //    headers: [{
  //      "id": "qt_ky8sltutsb",
  //      "name": "dimension",
  //      "type": "TEXT",
  //      "concept": "DIMENSION",
  //      "configId": "configId1"
  //    }, {
  //      "id": "qt_m9dtntutsb",
  //      "name": "metric",
  //      "type": "NUMBER",
  //      "concept": "METRIC",
  //      "configId": "configId2"
  //    }],
  //  rows: [
  //    ['hello', 1],
  //    ['world', 2]
  //  ];
  // }
  var dsccTableTransformObject = data.tables.DEFAULT;

  // accessing the row of rows
  var rowOfRows = dsccTableTransformObject.rows;

  // accessing the header row
  var headers = dsccTableTransformObject.headers;
}

dscc.subscribeToData(drawViz, {transform: tableTransform});