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

تستخدم أداة 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-component تحويلَين مصمَّمَين لتوجيهك مباشرةً إلى تنسيقات البيانات هذه.

تم توثيق عملية التحويلَين في 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});