הרחבת כלי הפיתוח

תוספים לכלי הפיתוח מוסיפים תכונות לכלי הפיתוח ל-Chrome באמצעות גישה ספציפית לכלי פיתוח ממשקי API של תוספים דרך דף של כלי פיתוח שמתווספים לתוסף.

תרשים ארכיטקטורה שמציג את הדף של כלי הפיתוח שמנהל את התקשורת עם
         את החלון לדוגמה ואת ה-Service Worker. קובץ השירות (service worker) מוצג
         תקשורת עם סקריפטים של תוכן וגישה לממשקי API של תוספים.
         בדף 'כלי פיתוח' יש גישה לממשקי ה-API של כלי הפיתוח. לדוגמה, אפשר ליצור לוחות.
ארכיטקטורת התוספים של כלי הפיתוח.

ממשקי ה-API של התוספים שספציפיים לכלי הפיתוח כוללים את אלה:

בדף של כלי הפיתוח

כשחלון של כלי פיתוח נפתח, תוסף של כלי פיתוח יוצר מופע של דף כלי הפיתוח שלו. קיים כל עוד החלון פתוח. הדף הזה כולל גישה לממשקי ה-API של כלי הפיתוח ולממשקי ה-API של התוספים, והוא יכול לבצע את הפעולות הבאות:

בדף 'כלי פיתוח' יש גישה ישירה לממשקי API של תוספים. זה כולל את היכולת כדי לתקשר עם Service Worker באמצעות העברת הודעות.

יצירת תוסף של כלי פיתוח

כדי ליצור דף של כלי פיתוח לתוסף, צריך להוסיף את השדה devtools_page לתוסף מניפסט:

{
  "name": ...
  "version": "1.0",
  "devtools_page": "devtools.html",
  ...
}

השדה devtools_page חייב להפנות לדף HTML. כי כלי הפיתוח חייב להיות מקומי בתוסף, מומלץ לציין אותו באמצעות כתובת URL יחסית.

החברים ב-API של chrome.devtools זמינים רק לדפים שנטענים בכלי הפיתוח כשהחלון פתוח. לסקריפטים של תוכן ולדפי תוספים אחרים אין גישה לממשקי ה-API האלה.

רכיבי ממשק המשתמש של כלי הפיתוח: חלוניות וחלוניות של סרגל הצד

בנוסף לרכיבים הרגילים בממשק המשתמש של התוסף, כמו פעולות דפדפן, תפריטי הקשר וחלונות קופצים, התוסף של כלי הפיתוח יכול להוסיף רכיבים של ממשק המשתמש לחלון של כלי הפיתוח:

  • חלונית היא כרטיסייה ברמה העליונה, כמו החלוניות 'רכיבים', 'מקורות' ו'רשת'.
  • חלונית צדדית מציגה ממשק משתמש נוסף שקשור ללוח. הסגנונות, הסגנונות המחושבים החלוניות של Event Listeners בחלונית Elements הן דוגמאות לחלוניות של סרגלי צד. בהתאם לתרחיש לדוגמה גרסת Chrome הנוכחית שלך והמיקום של חלון כלי הפיתוח בעגינה, עשויות להיות חלוניות של סרגל הצד כמו התמונה הבאה:
חלון של כלי הפיתוח שבו מוצגת חלונית הרכיבים וחלונית סרגל הצד 'סגנונות'.
חלון של כלי פיתוח שבו מוצגות חלונית הרכיבים וחלונית סרגל הצד 'סגנונות'.

כל לוח הוא קובץ HTML משלו, שיכול לכלול משאבים אחרים (JavaScript, CSS, תמונות וכן הלאה מופעל). כדי ליצור לוח בסיסי, משתמשים בקוד הבא:

chrome.devtools.panels.create("My Panel",
    "MyPanelIcon.png",
    "Panel.html",
    function(panel) {
      // code invoked on panel creation
    }
);

ל-JavaScript שמופעל בחלונית או בחלונית של סרגל הצד יש גישה לאותם ממשקי API כמו לדף 'כלי פיתוח'.

כדי ליצור חלונית בסיסית של סרגל הצד, משתמשים בקוד הבא:

chrome.devtools.panels.elements.createSidebarPane("My Sidebar",
    function(sidebar) {
        // sidebar initialization code here
        sidebar.setObject({ some_data: "Some data to show" });
});

יש כמה דרכים להציג תוכן בחלונית של סרגל הצד:

  • תוכן HTML: קוראים לפונקציה setPage() כדי לציין דף HTML שיוצג בחלונית.
  • נתוני JSON: מעבירים אובייקט JSON אל setObject().
  • ביטוי JavaScript: מעבירים ביטוי אל setExpression(). DevTools בודקת את הביטוי בהקשר של הדף שנבדק, ואז מציגה את הערך המוחזר.

גם עבור setObject() וגם עבור setExpression(), החלונית תציג את הערך כפי שהוא יופיע מסוף כלי הפיתוח. עם זאת, setExpression() מאפשר להציג רכיבי DOM ו-JavaScript שרירותי אובייקטים, ואילו setObject() תומך רק באובייקטים של JSON.

תקשורת בין רכיבי התוסף

בקטעים הבאים מתוארות כמה דרכים שימושיות שמאפשרות לרכיבים של תוסף כלי הפיתוח לתקשר זה עם זה.

החדרת סקריפט של תוכן

כדי להחדיר סקריפט תוכן, משתמשים ב-scripting.executeScript():

// DevTools page -- devtools.js
chrome.scripting.executeScript({
  target: {
    tabId: chrome.devtools.inspectedWindow.tabId
  },
  files: ["content_script.js"]
});

אפשר לאחזר את מזהה הכרטיסייה של החלון שנבדק באמצעות inspectedWindow.tabId.

אם כבר הוחדר סקריפט תוכן, תוכלו להשתמש בממשקי API להעברת הודעות כדי לתקשר איתו.

הערכת JavaScript בחלון הנבדק

אפשר להשתמש בשיטה inspectedWindow.eval() כדי להריץ JavaScript בהקשר של הדף שנבדק. אפשר להפעיל את השיטה eval() מדף של כלי פיתוח, בחלונית או בחלונית של סרגל הצד.

כברירת מחדל, הביטוי מוערך בהקשר של המסגרת הראשית של הדף. inspectedWindow.eval() משתמש באותו הקשר ובאפשרויות של הפעלת הסקריפט כמו בקוד הוזן במסוף כלי הפיתוח, ומאפשר גישה לכלי הפיתוח כלים לתחזוקת המסוף תכונות API כשמשתמשים ב-eval(). לדוגמה, הפונקציה SOAK משתמשת בו כדי לבדוק רכיב:

chrome.devtools.inspectedWindow.eval(
  "inspect($$('head script[data-soak=main]')[0])",
  function(result, isException) { }
);

אפשר גם להגדיר את useContentScriptContext לערך true כשקוראים לפונקציה inspectedWindow.eval() להעריך את הביטוי באותו הקשר שבו נמצאים הסקריפטים של התוכן. כדי להשתמש באפשרות הזו, צריך להשתמש בהצהרה לגבי סקריפט תוכן סטטי לפני הקריאה ל-eval(), באמצעות קריאה ל-executeScript() או על ידי ציון תוכן בקובץ manifest.json. אחרי שההקשר של סקריפט ההקשר נטען, אפשר להשתמש באפשרות הזו גם כדי להחדיר סקריפטים נוספים של תוכן.

העברת הרכיב שנבחר לסקריפט תוכן

לסקריפט התוכן אין גישה ישירה לרכיב הנוכחי שנבחר. עם זאת, כל קוד לבצע באמצעות inspectedWindow.eval() גישה לכלי הפיתוח ממשקי API של המסוף ושל Console Utilities. לדוגמה, בקוד שנבדק אפשר להשתמש ב-$0 כדי לגשת אל נבחר רכיב.

כדי להעביר את הרכיב שנבחר לסקריפט תוכן:

  1. יצירת שיטה בסקריפט התוכן שלוקחת את הרכיב שנבחר כארגומנט.

    function setSelectedElement(el) {
        // do something with the selected element
    }
    
  2. קוראים ל-method מהדף 'כלי פיתוח' באמצעות inspectedWindow.eval() עם האפשרות useContentScriptContext: true.

    chrome.devtools.inspectedWindow.eval("setSelectedElement($0)",
        { useContentScriptContext: true });
    

האפשרות useContentScriptContext: true מציינת שצריך להעריך את הביטוי בפונקציה את אותו ההקשר כמו בסקריפטים של התוכן, כדי שהוא יוכל לגשת לשיטת setSelectedElement.

אחזור window של חלונית עזר

כדי לקרוא ל-postMessage() מחלונית devtools, צריך הפניה לאובייקט window שלו. לקבלת חלון ה-iframe של הלוח מה-handler של האירועים panel.onShown:

extensionPanel.onShown.addListener(function (extPanelWindow) {
    extPanelWindow instanceof Window; // true
    extPanelWindow.postMessage( // …
});

שליחת הודעות מסקריפטים שהוחדרו לדף של כלי הפיתוח

קוד שהוזן ישירות לדף ללא סקריפט תוכן, כולל על ידי הוספת <script> או מתקשר אל inspectedWindow.eval(), אין אפשרות לשלוח הודעות אל הדף 'כלי פיתוח' באמצעות runtime.sendMessage(). במקום זאת, מומלץ של שילוב התסריט שהוחדר עם סקריפט תוכן שיכול לשמש כמתווך, ושימוש השיטה window.postMessage(). הדוגמה הבאה משתמשת בסקריפט הרקע מהקטע הקודם:

// injected-script.js

window.postMessage({
  greeting: 'hello there!',
  source: 'my-devtools-extension'
}, '*');
// content-script.js

window.addEventListener('message', function(event) {
  // Only accept messages from the same frame
  if (event.source !== window) {
    return;
  }

  var message = event.data;

  // Only accept messages that we know are ours. Note that this is not foolproof
  // and the page can easily spoof messages if it wants to.
  if (typeof message !== 'object' || message === null ||
      message.source !== 'my-devtools-extension') {
    return;
  }

  chrome.runtime.sendMessage(message);
});

אפשר למצוא שיטות חלופיות נוספות להעברת הודעות ב-GitHub.

זיהוי מתי כלי פיתוח נפתחים וסוגרים

כדי לבדוק אם חלון כלי הפיתוח פתוח, צריך להוסיף אוזן onConnect ל-Service Worker ולהפעיל את connect() מהדף של כלי הפיתוח. כי בכל כרטיסייה אפשר לפתוח חלון נפרד של כלי פיתוח. ייתכן שיתקבלו מספר אירועי התחברות. כדי לבדוק אם חלון של כלי פיתוח פתוח, צריך לספור את אירועי ההתחברות והניתוק כמו שמוצג בדוגמה הבאה:

// background.js
var openCount = 0;
chrome.runtime.onConnect.addListener(function (port) {
    if (port.name == "devtools-page") {
      if (openCount == 0) {
        alert("DevTools window opening.");
      }
      openCount++;

      port.onDisconnect.addListener(function(port) {
          openCount--;
          if (openCount == 0) {
            alert("Last DevTools window closing.");
          }
      });
    }
});

הדף של כלי הפיתוח יוצר חיבור כזה:

// devtools.js

// Create a connection to the service worker
const serviceWorkerConnection = chrome.runtime.connect({
    name: "devtools-page"
});

// Send a periodic heartbeat to keep the port open.
setInterval(() => {
  port.postMessage("heartbeat");
}, 15000);

דוגמאות לתוספים של כלי פיתוח

הדוגמאות בדף הזה מגיעות מהדפים הבאים:

  • תוסף Polymer Devtools – משתמש במשתמשים רבים שרצים בדף המארח כדי לבצע שאילתה מצב DOM/JS כדי לשלוח חזרה לחלונית המותאמת אישית.
  • תוסף React DevTools – שימוש במודול משנה של כלי הרינדור לצורך שימוש חוזר בממשק המשתמש של כלי הפיתוח רכיבים.
  • Ember Inspector – ליבת תוסף משותף עם מתאמים ל-Chrome ול-Firefox.
  • Coquette-inspect – תוסף נקי שמבוסס על תגובה, עם החדרת סוכן לניפוי באגים בדף המארח.
  • לתוספים לדוגמה יש תוספים משתלמים יותר להתקין, לנסות וללמוד מ.

מידע נוסף

מידע נוסף על ממשקי ה-API הרגילים שבהם אפשר להשתמש בתוספים זמין בכתובת chrome.* ממשקי API ואתרים ממשקי API.

נשמח לקבל ממך משוב! ההערות וההצעות שלכם יעזרו לנו לשפר את ממשקי ה-API.

דוגמאות

בקטע טעימות תוכלו למצוא דוגמאות לשימוש בממשקי API של כלי פיתוח.