شروع کردن

برنامه های افزودنی از اجزای مختلف، اما منسجم ساخته شده اند. مؤلفه ها می توانند شامل اسکریپت های پس زمینه ، اسکریپت های محتوا ، صفحه گزینه ها ، عناصر رابط کاربری و فایل های منطقی مختلف باشند. اجزای برنامه افزودنی با فناوری های توسعه وب ایجاد می شوند: HTML، CSS و جاوا اسکریپت. اجزای یک برنامه افزودنی به عملکرد آن بستگی دارد و ممکن است به هر گزینه ای نیاز نداشته باشد.

این آموزش افزونه ای ایجاد می کند که به کاربر امکان می دهد رنگ پس زمینه هر صفحه را در developer.chrome.com تغییر دهد. از بسیاری از مؤلفه‌های اصلی برای نمایش مقدماتی روابط آنها استفاده می‌کند.

برای شروع، یک دایرکتوری جدید برای نگهداری فایل های برنامه افزودنی ایجاد کنید.

پسوند تکمیل شده را می توانید در اینجا پیدا کنید.

مانیفست را ایجاد کنید

برنامه های افزودنی با مانیفست خود شروع می شوند. یک فایل به نام manifest.json ایجاد کنید و کد زیر را وارد کنید.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "manifest_version": 2
}

دایرکتوری حاوی فایل مانیفست می تواند به عنوان یک پسوند در حالت توسعه دهنده در وضعیت فعلی خود اضافه شود.

  1. صفحه مدیریت برنامه افزودنی را با پیمایش به chrome://extensions باز کنید.
    • صفحه مدیریت برنامه افزودنی را نیز می توان با کلیک بر روی منوی کروم، نگه داشتن ماوس روی More Tools و انتخاب Extensions باز کرد.
  2. با کلیک کردن روی سوئیچ کنار حالت برنامه‌نویس، حالت برنامه‌نویس را فعال کنید.
  3. روی دکمه LOAD UNPACKED کلیک کنید و فهرست برنامه افزودنی را انتخاب کنید.

بارگذاری پسوند

تا-دا! برنامه افزودنی با موفقیت نصب شد. از آنجایی که هیچ نمادی در مانیفست گنجانده نشده است، یک نماد نوار ابزار عمومی برای برنامه افزودنی ایجاد خواهد شد.

دستور اضافه کنید

اگرچه افزونه نصب شده است، اما هیچ دستورالعملی ندارد. با ایجاد فایلی با عنوان background.js و قرار دادن آن در فهرست برنامه افزودنی، یک اسکریپت پس زمینه را معرفی کنید.

اسکریپت های پس زمینه و بسیاری از اجزای مهم دیگر باید در مانیفست ثبت شوند. ثبت یک اسکریپت پس‌زمینه در مانیفست به پسوند می‌گوید به کدام فایل ارجاع دهد و آن فایل چگونه باید رفتار کند.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

برنامه افزودنی اکنون می‌داند که شامل یک اسکریپت پس‌زمینه غیر دائمی است و فایل ثبت‌شده را برای رویدادهای مهمی که نیاز به گوش دادن دارد اسکن می‌کند.

این برنامه افزودنی به محض نصب به اطلاعات یک متغیر دائمی نیاز دارد. با گنجاندن یک رویداد شنیداری برای runtime.onInstalled در اسکریپت پس‌زمینه شروع کنید. در داخل شنونده onInstalled ، برنامه افزودنی با استفاده از API ذخیره سازی مقداری را تنظیم می کند. این به چندین مؤلفه برنامه افزودنی اجازه می دهد تا به آن مقدار دسترسی داشته باشند و آن را به روز کنند.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log("The color is green.");
  });
});

اکثر APIها، از جمله API ذخیره سازی ، باید در قسمت "permissions" در مانیفست ثبت شوند تا برنامه افزودنی بتواند از آنها استفاده کند.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

به صفحه مدیریت برنامه افزودنی برگردید و روی پیوند بارگذاری مجدد کلیک کنید. یک فیلد جدید، Inspect views ، با پیوند آبی، صفحه پس‌زمینه در دسترس قرار می‌گیرد.

نماها را بررسی کنید

برای مشاهده گزارش کنسول اسکریپت پس زمینه، " The color is green.

یک رابط کاربری معرفی کنید

برنامه های افزودنی می توانند اشکال مختلفی از رابط کاربری داشته باشند، اما این یکی از یک پنجره بازشو استفاده می کند. فایلی با عنوان popup.html ایجاد و به فهرست اضافه کنید. این افزونه از یک دکمه برای تغییر رنگ پس زمینه استفاده می کند.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
      }
    </style>
  </head>
  <body>
    <button id="changeColor"></button>
  </body>
</html>

مانند اسکریپت پس‌زمینه، این فایل باید به عنوان یک پنجره بازشو در مانیفست تحت page_action تعیین شود.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html"
  },
  "manifest_version": 2
}

تعیین نمادهای نوار ابزار نیز در page_action در قسمت default_icons گنجانده شده است. پوشه تصاویر را از اینجا دانلود کنید، آن را از حالت فشرده خارج کنید و در فهرست برنامه افزودنی قرار دهید. مانیفست را به‌روزرسانی کنید تا برنامه افزودنی بداند چگونه از تصاویر استفاده کند.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "manifest_version": 2
}

برنامه های افزودنی همچنین تصاویر را در صفحه مدیریت برنامه افزودنی، هشدار مجوزها و فاویکون نمایش می دهند. این تصاویر در مانیفست در زیر icons مشخص شده اند.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "icons": {
    "16": "images/get_started16.png",
    "32": "images/get_started32.png",
    "48": "images/get_started48.png",
    "128": "images/get_started128.png"
  },
  "manifest_version": 2
}

اگر برنامه افزودنی در این مرحله بارگیری مجدد شود، دارای یک نماد در مقیاس خاکستری است، اما هیچ تفاوتی در عملکرد نخواهد داشت. از آنجایی که page_action در مانیفست اعلان شده است، این به برنامه افزودنی بستگی دارد که به مرورگر بگوید چه زمانی کاربر می‌تواند با popup.html تعامل داشته باشد.

قوانین اعلام شده را به اسکریپت پس زمینه با declarativeContent API در رویداد شنونده runtime.onInstalled اضافه کنید.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log('The color is green.');
  });
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([{
      conditions: [new chrome.declarativeContent.PageStateMatcher({
        pageUrl: {hostEquals: 'developer.chrome.com'},
      })
      ],
          actions: [new chrome.declarativeContent.ShowPageAction()]
    }]);
  });
});

برنامه افزودنی برای دسترسی به declarativeContent API در مانیفست خود به مجوز نیاز دارد.

{
  "name": "Getting Started Example",
...
  "permissions": ["declarativeContent", "storage"],
...
}

پنجره بازشو

وقتی کاربران به URL حاوی "developer.chrome.com" می روند، مرورگر اکنون یک نماد عملکرد صفحه تمام رنگی را در نوار ابزار مرورگر نشان می دهد. وقتی نماد تمام رنگی است، کاربران می توانند روی آن کلیک کنند تا popup.html را مشاهده کنند.

آخرین مرحله برای رابط کاربری بازشو، افزودن رنگ به دکمه است. فایلی به نام popup.js با کد زیر ایجاد کرده و به پوشه افزونه اضافه کنید.

let changeColor = document.getElementById('changeColor');

chrome.storage.sync.get('color', function(data) {
  changeColor.style.backgroundColor = data.color;
  changeColor.setAttribute('value', data.color);
});

این کد دکمه را از popup.html می گیرد و مقدار رنگ را از حافظه درخواست می کند. سپس رنگ را به عنوان پس زمینه دکمه اعمال می کند. یک تگ اسکریپت به popup.js در popup.html اضافه کنید.

<!DOCTYPE html>
<html>
...
  <body>
    <button id="changeColor"></button>
    <script src="popup.js"></script>
  </body>
</html>

برای مشاهده دکمه سبز، افزونه را دوباره بارگیری کنید.

منطق لایه

برنامه افزودنی اکنون می داند که پنجره بازشو باید در دسترس کاربران در developer.chrome.com باشد و یک دکمه رنگی را نمایش می دهد، اما برای تعامل بیشتر با کاربر به منطق نیاز دارد. popup.js را برای گنجاندن کد زیر به روز کنید.

let changeColor = document.getElementById('changeColor');
...
changeColor.onclick = function(element) {
  let color = element.target.value;
  chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
    chrome.tabs.executeScript(
        tabs[0].id,
        {code: 'document.body.style.backgroundColor = "' + color + '";'});
  });
};

کد به روز شده یک رویداد onclick را روی دکمه اضافه می کند، که یک اسکریپت محتوای تزریق شده با برنامه را راه اندازی می کند. با این کار رنگ پس‌زمینه صفحه به همان رنگ دکمه تبدیل می‌شود. استفاده از تزریق برنامه‌ریزی به جای درج خودکار کدهای ناخواسته در صفحات وب، به اسکریپت‌های محتوای فراخوانی شده توسط کاربر اجازه می‌دهد.

مانیفست به مجوز activeTab نیاز دارد تا به برنامه افزودنی اجازه دسترسی موقت به tabs API بدهد. این افزونه را قادر می سازد تا tabs.executeScript را فراخوانی کند.

{
  "name": "Getting Started Example",
...
  "permissions": ["activeTab", "declarativeContent", "storage"],
...
}

افزونه اکنون کاملاً کاربردی است! برنامه افزودنی را دوباره بارگیری کنید، این صفحه را بازخوانی کنید، پنجره بازشو را باز کنید و روی دکمه کلیک کنید تا سبز شود! با این حال، برخی از کاربران ممکن است بخواهند پس زمینه را به رنگ دیگری تغییر دهند.

به کاربران گزینه هایی بدهید

افزونه در حال حاضر فقط به کاربران اجازه می دهد پس زمینه را به سبز تغییر دهند. گنجاندن صفحه گزینه ها به کاربران کنترل بیشتری بر عملکرد برنامه افزودنی می دهد و تجربه مرور خود را بیشتر سفارشی می کند.

با ایجاد یک فایل در دایرکتوری به نام options.html شروع کنید و کد زیر را وارد کنید.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
        margin: 10px;
      }
    </style>
  </head>
  <body>
    <div id="buttonDiv">
    </div>
    <div>
      <p>Choose a different background color!</p>
    </div>
  </body>
  <script src="options.js"></script>
</html>

سپس صفحه گزینه ها را در مانیفست ثبت کنید،

{
  "name": "Getting Started Example",
  ...
  "options_page": "options.html",
  ...
  "manifest_version": 2
}

برنامه افزودنی را دوباره بارگیری کنید و روی DETAILS کلیک کنید.

نماها را بررسی کنید

صفحه جزئیات را به پایین اسکرول کنید و گزینه های برنامه افزودنی را برای مشاهده صفحه گزینه ها انتخاب کنید، اگرچه در حال حاضر خالی به نظر می رسد.

گزینه های پسوند

مرحله آخر اضافه کردن منطق گزینه ها است. با کد زیر یک فایل به نام options.js در فهرست افزونه ایجاد کنید.

let page = document.getElementById('buttonDiv');
const kButtonColors = ['#3aa757', '#e8453c', '#f9bb2d', '#4688f1'];
function constructOptions(kButtonColors) {
  for (let item of kButtonColors) {
    let button = document.createElement('button');
    button.style.backgroundColor = item;
    button.addEventListener('click', function() {
      chrome.storage.sync.set({color: item}, function() {
        console.log('color is ' + item);
      })
    });
    page.appendChild(button);
  }
}
constructOptions(kButtonColors);

چهار گزینه رنگ ارائه می شود و سپس به عنوان دکمه در صفحه گزینه ها با شنوندگان رویداد onclick ایجاد می شود. وقتی کاربر روی دکمه ای کلیک می کند، مقدار رنگ را در حافظه جهانی برنامه افزودنی به روز می کند. از آنجایی که همه فایل‌های برنامه افزودنی اطلاعات رنگ را از حافظه جهانی بیرون می‌کشند، نیازی به به‌روزرسانی مقادیر دیگری نیست.

قدم بعدی را بردارید

تبریک می گویم! دایرکتوری اکنون دارای یک برنامه افزودنی کروم کاملاً کاربردی و البته ساده است.

بعدش چی؟

  • نمای کلی برنامه افزودنی کروم کمی پشتیبان‌گیری می‌کند و جزئیات زیادی را در مورد معماری برنامه‌های افزودنی به طور کلی و برخی از مفاهیم خاص که توسعه‌دهندگان می‌خواهند با آن‌ها آشنا شوند را پر می‌کند.
  • با گزینه های موجود برای اشکال زدایی برنامه های افزودنی در آموزش اشکال زدایی آشنا شوید.
  • برنامه‌های افزودنی Chrome به APIهای قدرتمند بالاتر و فراتر از آنچه در وب باز موجود است دسترسی دارند. chrome.* اسناد APIها از طریق هر API ارائه می شود.
  • راهنمای توسعه‌دهنده ده‌ها پیوند اضافی به بخش‌هایی از اسناد مربوط به ایجاد برنامه‌های افزودنی پیشرفته دارد.