Sambungan Chrome - persediaan persekitaran

Saya mahukan beberapa fungsi bodoh dalam penyemak imbas saya. Mungkin saya boleh menambahnya dengan sambungan mudah? Ia tidak wujud, tetapi menulisnya sendiri sepatutnya mudah, bukan?

Itu yang saya fikirkan beberapa hari lalu. Walaupun saya tidak sepenuhnya salah, beberapa bahagian proses pembangunan agak memakan masa lebih lama daripada yang saya jangkakan. Saya tidak akan mengatakan sukar, tetapi agak sukar untuk mengetahui menggunakan dokumentasi yang tersedia. Walaupun dokumentasi API, konsep teras, dsb. diterangkan dengan agak baik pada developer.chrome.com, saya mahukan pengalaman pembangun yang khusus:

• Skrip Jenis dengan penaip ruang nama krom yang betul
• Memisahkan kod kepada berbilang fail dan import/eksport apa yang perlu
• Menyahpepijat kod saya dengan console.log dan/atau debugger ringkas
• Autolengkap dalam manifes.json saya
• Persediaan mudah, tanpa sebarang pengikat dan separuh daripada Internet dalam node_modules saya
• Cara mudah untuk mengemas kini dan menguji sambungan dalam penyemak imbas

Dengan cara yang lebih baik atau lebih teruk, saya berjaya menetapkan perkara seperti yang saya mahu. Dalam siaran ini, saya akan menerangkan secara ringkas konsep sambungan am dan menunjukkan kepada anda cara saya telah menyediakan persekitaran pembangunan saya. Dalam satu atau dua siaran seterusnya, saya akan menumpukan pada butiran pelaksanaan sambungan audio halaman mudah saya.

TLDR:
Jika anda hanya mahukan kodnya, inilah repo boilerplate:

Voodu / chromium-extension-boilerplate

Plat dandang sambungan kromium

Repositori ini bertujuan untuk menjadi titik permulaan untuk membangunkan sambungan kromium.

Ia seminimalis mungkin, tetapi disertakan dengan prakonfigurasi:

• autolengkap untuk manifest.json
• Terjemahan TypeScript daripada folder ts ke direktori dist
• jenis untuk ruang nama krom
• mengeksport dan mengimport yang berfungsi dengan betul (dengan tetapan ruang kerja Kod VS untuk format import automatik yang betul)
• contoh manifes.json

Selamat pengekodan!

Lihat di GitHub

ℹ️ Saya menggunakan Windows 11, MS Edge, VS Code dan npm di mana-mana di bawah ℹ️

---

Pengenalan ringkas kepada sambungan

Mari kita mulakan dengan kursus ranap tentang konsep sambungan am.

Setiap sambungan mempunyai fail manifest.json yang mentakrifkan nama, versi, kebenaran yang diperlukan dan fail yang digunakan. Sambungan boleh menyediakan kefungsian dalam beberapa cara berbeza:

• melalui pop timbul - pop timbul sambungan ialah tetingkap kecil ini yang dibuka apabila anda mengklik ikon sambungan dalam bar sambungan,
• melalui skrip kandungan - skrip yang disuntik terus ke tapak web dan mempunyai akses DOM,
• melalui skrip latar belakang (pekerja perkhidmatan) - skrip dijalankan dalam konteks yang berasingan, bebas daripada tapak web yang dibuka

Ada cara lain, tetapi saya akan berpegang pada ketiga-tiga ini dalam panduan ini.

Satu lagi konsep penting ialah mesej. Biasanya, kita perlu menggabungkan kaedah di atas, kerana kesemuanya mempunyai batasan yang berbeza. Sebagai contoh, skrip latar belakang tidak bergantung pada tab yang dibuka dan boleh menjadi lebih berguna untuk keadaan berterusan, tetapi tidak boleh mengakses DOM mana-mana tapak web. Oleh itu, kami mungkin perlu mendapatkan beberapa data lebar sambungan daripada skrip latar belakang, menghantarnya menggunakan mesej kepada skrip kandungan dan mengubah suai tapak web dari sana.

Ia juga berguna untuk memahami beberapa asas tentang kebenaran. Ringkasnya, sesetengah API tidak akan berfungsi seperti yang diharapkan jika manifest.json tidak menyatakan kebenaran yang betul. Contohnya, jika kami tidak menentukan kebenaran "tab", objek yang dikembalikan daripada API tab tidak akan mempunyai medan url. Sebaliknya, kita tidak seharusnya meminta terlalu banyak kebenaran - jika sambungan akan didedahkan kepada umum, pengguna mungkin bimbang tentang memberikan akses kepada terlalu banyak perkara.

---

Mencipta sambungan mudah

Diinspirasikan oleh https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world

Mari mulakan dengan memahami konsep teras aliran kerja pembangunan kami menggunakan sambungan yang sangat mudah yang hanya memaparkan beberapa teks dalam pop timbul.

Fail

Pertama sekali, kami memerlukan fail manifest.json:

// manifest.json
{
  "name": "Hello World",
  "description": "Shows Hello World text",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "icon.png"
  }
}

nama, perihalan, versi dan versi_manifes mungkin menjelaskan sendiri. action.default_popup ialah laluan ke fail HTML yang akan dipaparkan apabila mengklik ikon sambungan. default_icon ialah laluan ke ikon sambungan. Kedua-dua laluan adalah relatif kepada lokasi manifest.json.

Sekarang, tambahkan icon.png (contohnya, yang ini) dan fail hello.html dalam direktori yang sama seperti manifest.json.
hello.html boleh kelihatan seperti itu:

<!-- hello.html -->
<p>Hello world</p>

Dan keseluruhan direktori anda sepatutnya kelihatan seperti itu:

// manifest.json
{
  "name": "Hello World",
  "description": "Shows Hello World text",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "icon.png"
  }
}

Mengaktifkan sambungan

Untuk mengaktifkan sambungan anda:

1. Pergi ke edge://extensions/
2. Di bar sisi kiri, dayakan "Mod pembangun"
   • "Benarkan sambungan daripada kedai lain" mungkin juga diperlukan
3. Di atas senarai sambungan klik "Muat dibongkar"
4. Pilih folder dengan fail sambungan anda
5. Pelanjutan anda sepatutnya muncul pada senarai dan ikonnya dalam bar alat sambungan ?

Kini, selepas mengklik ikon, ia akan memaparkan pop timbul kecil dengan teks "Hello world".

Itu merangkumi asas yang paling penting. Mari beralih kepada sesuatu yang lebih menarik.

---

Persediaan persekitaran sambungan Page-Audio

Autolengkap dalam manifest.json

Kami akan mulakan semula dengan manifest.json dan direktori kosong.

Adalah mengagumkan untuk mempunyai autolengkap semasa menulis fail manifest.json, bukan? Nasib baik, ia adalah standard yang jelas dan mempunyai skema JSON di https://json.schemastore.org/chrome-manifest. Kami hanya memerlukannya di bawah kekunci "$schema" pada permulaan manifest.json:

<!-- hello.html -->
<p>Hello world</p>

dan Kod VS serta-merta mula membantu kami dengan mencadangkan nama medan dan menunjukkan amaran jika medan wajib tiada. Hebat!?

Untuk mendapatkan sesuatu yang berfungsi untuk menguji persediaan kami, gunakan manifest.json melihat cara ini:

.
├── hello.html
├── icon.png
└── manifest.json

• ikon - ini hanyalah cara berbeza untuk menentukan ikon sambungan
• bahagian latar belakang - menentukan laluan dengan fail JS pekerja perkhidmatan dan jenisnya; ia adalah modul kerana kod tersebut akan menggunakan eksport dan import kemudian hari

TypeScript

Menggunakan TypeScript... well, memerlukan TypeScript. Jika anda belum memasangnya, mulakan dengan

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest"
}

Konfigurasi asas

Untuk mengatur perkara, tetapi tidak terlalu rumit, saya akan menyimpan fail sumber .ts dalam direktori ts. Ia akan diambil dari sana oleh transpiler dan dimasukkan ke dalam direktori dist sebagai fail .js.

Ini diterangkan oleh .tsconfig berikut:

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest",
    "name": "Page Audio",
    "version": "0.0.0.1",
    "manifest_version": 3,
    "icons": {
        "16": "icons/logo16x16.png",
        "32": "icons/logo32x32.png",
        "48": "icons/logo48x48.png",
        "128": "icons/logo128x128.png"
    },
    "background": {
        "service_worker": "dist/background.js",
        "type": "module"
    }
}

Bit yang paling penting ialah compiler.rootDir dan compiler.outDir. Medan lain boleh mempunyai nilai yang berbeza atau dialih keluar sepenuhnya (sekurang-kurangnya sebahagian daripadanya).

Itulah konfigurasi asas - meletakkan beberapa fail dalam direktori ts dan menjalankan tsc dalam direktori root akan mencipta fail .js yang sepadan dalam dist. Walau bagaimanapun, kami kehilangan satu bahagian penting - jenis untuk ruang nama krom yang akan kami gunakan. Penyelesaian paling mudah ialah menambahkannya melalui npm.

Menambah jenis krom

Buat pakej kosong.json, hanya dengan kurungan:

// manifest.json
{
  "name": "Hello World",
  "description": "Shows Hello World text",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "icon.png"
  }
}

dan dalam baris arahan jalankan:

<!-- hello.html -->
<p>Hello world</p>

Anda juga boleh menambah skrip untuk menjalankan binaan tsc dan dalam mod jam tangan. Package.json akhir sepatutnya kelihatan seperti ini:

.
├── hello.html
├── icon.png
└── manifest.json

ℹ️ versi jenis krom mungkin lebih tinggi dalam kes anda. ℹ️

Selepas menambah jenis, kami perlu memberitahu TypeScript mengetahuinya. Untuk melakukan ini, hanya kemas kini .tsconfig.json:

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest"
}

Untuk menguji sama ada persediaan kami berfungsi dengan betul:

1. Dalam folder ts, cipta fail background.ts dengan kandungan berikut
   

   // manifest.json
   {
       "$schema": "https://json.schemastore.org/chrome-manifest",
       "name": "Page Audio",
       "version": "0.0.0.1",
       "manifest_version": 3,
       "icons": {
           "16": "icons/logo16x16.png",
           "32": "icons/logo32x32.png",
           "48": "icons/logo48x48.png",
           "128": "icons/logo128x128.png"
       },
       "background": {
           "service_worker": "dist/background.js",
           "type": "module"
       }
   }
   
   

2. Dalam baris arahan, jalankan
   

   npm install -g typescript
   

3. Sahkan jika direktori dist telah dibuat dan fail background.js muncul di sana

4. Tukar sesuatu dalam rentetan console.log dalam fail ts/background.ts dan simpannya

5. Semak sama ada ia dikemas kini secara automatik dist/background.js.

Jika itu berkesan, hebat! Kami telah menyediakan hampir semua perkara ?

Anda juga boleh mengesahkan sama ada struktur direktori anda kelihatan serupa dengan itu:

// .tsconfig
{
    "compilerOptions": {
        "target": "ES6",
        "module": "ES6",
        "outDir": "./dist",
        "rootDir": "./ts",
        "strict": true,
    }
}

import dan eksport

Seperti yang telah saya nyatakan, saya ingin membahagikan kod tersebut kepada fail yang lebih kecil. Untuk melakukan ini, mengeksport dan mengimport mesti berfungsi dengan betul.

Satu langkah ke arah itu ialah menentukan service_worker kami dalam manifest.json sebagai "type": "module". Walau bagaimanapun, terdapat satu perbezaan antara TypeScript dan JavaScript apabila bekerja dengan modul - manakala TypeScript tidak memerlukan sambungan fail semasa mengimport, JavaScript memerlukannya. Jadi, sebagai contoh, import ini:

// package.json
{
}

akan berfungsi dalam TS, tetapi JS memerlukan

npm i -D chrome-types

Perlu juga untuk memahami, transpiler TS itu tidak melakukan apa-apa kepada laluan import. Dan ia cukup "pintar" untuk memahami bahawa apabila mengimport daripada file.js ia juga harus mencari file.ts.

Menggabungkan semua itu, TS juga akan gembira dengan import gaya JS dan akan menggunakan fail TS yang sepadan apabila mengimport daripada file.js. Apa yang kita perlu lakukan ialah memastikan semua import dalam fail TS mempunyai sambungan .js. Untuk mengautomasikannya dalam Kod VS:

1. Tekan CTRL , untuk membuka tetapan
2. Tukar kepada tab "Ruang Kerja"
3. Cari typescript.preferences.importModuleSpecifierEnding
4. Tetapkannya kepada pilihan ".js / .ts"

Kini, apabila anda mengimport automatik menggunakan Kod VS, ia akan menambah .js pada nama fail ?

Untuk menguji sama ada perkara berfungsi dengan betul:

1. Buat fail ts/hello.ts dengan kandungan berikut
   

   // package.json
   {
       "scripts": {
           "build": "tsc",
           "watch": "tsc -w"
       },
       "devDependencies": {
           "chrome-types": "^0.1.327"
       }
   }
   

2. Dalam ts/background.ts alih keluar baris console.log semasa dan mula menaip "hello"

3. Kod VS harus melengkapkannya secara automatik dan menambah import yang betul selepas anda menerima cadangan dengan Tab

4. Pada akhirnya, fail sepatutnya kelihatan seperti ini:
   

   // manifest.json
   {
     "name": "Hello World",
     "description": "Shows Hello World text",
     "version": "1.0",
     "manifest_version": 3,
     "action": {
       "default_popup": "hello.html",
       "default_icon": "icon.png"
     }
   }
   

Perhatikan bahawa import berakhir dengan sambungan .js. Jika anda menyemak dist/background.js sambungan itu juga ada dan itulah yang menjadikan semuanya berfungsi dengan betul.

Untuk memastikan kami berada pada peringkat yang sama, anda boleh membandingkan struktur direktori:

<!-- hello.html -->
<p>Hello world</p>

Alat Pembangun untuk pekerja perkhidmatan

Baiklah, kami mempunyai pengalaman pembangunan yang baik. Kami juga telah menambahkan beberapa panggilan console.log... tetapi di mana hendak mencarinya sekarang?

Jika anda menambah console.log di dalam skrip kandungan, anda hanya boleh membuka Alat Dev dan ia akan berada di sana, kerana skrip kandungan berfungsi dalam konteks yang sama seperti halaman yang disuntik ke dalamnya. Walau bagaimanapun, console.logs daripada skrip latar belakang tersembunyi sedikit lagi.

1. Buka edge://extensions/ dan muatkan sambungan anda jika anda belum melakukannya lagi
2. Cari sambungan anda dalam senarai

3. Klik pautan "pekerja perkhidmatan" dalam baris "Periksa paparan":

   

4. Tetingkap Dev Tools baharu akan dibuka dan anda akan melihat log daripada pekerja perkhidmatan di sana

   • jika anda tidak melihat log, klik "Muat Semula" di bawah "Periksa paparan"

Tiga pautan di bahagian bawah jubin juga sangat penting

• "Muat Semula" - menyegarkan keseluruhan sambungan, termasuk perubahan pada manifest.json; semak jadual ini untuk memahami masa muat semula mungkin diperlukan
• "Alih Keluar" - memadamkan sambungan
• "Butiran" - menunjukkan lebih banyak maklumat tentang sambungan, contohnya, kebenarannya
• (pilihan) "Ralat" - jika terdapat ralat semasa memasang pekerja perkhidmatan, pautan ini akan muncul dan membawa anda ke senarai ralat

Fuh. Itu mengambil sedikit masa, tetapi, akhirnya, persekitaran kita telah disediakan dengan baik. Mulai sekarang, kita hanya perlu

1. Jalankan npm run watch (jika anda menghentikannya)
2. Tulis kod kami dalam direktori ts
3. (Sebagai pilihan) Muat semula sambungan daripada tab sambungan

Dan sambungan kami akan dikemas kini secara automatik! ⚙️

Jika anda mempunyai idea bagaimana untuk "Muat Semula" secara automatik (tanpa penggodaman yang terperinci), beritahu saya dalam ulasan

Ringkasan

Kami menyediakan persekitaran kami!

• Autolengkap berfungsi dalam manifest.json, jadi kita tidak perlu meneka apakah nilai yang betul
• TypeScript membantu kami menggunakan API chrome dengan betul
• Kod boleh dibahagikan kepada fail logik yang lebih kecil
• Kod yang kami tulis dalam folder ts dikemas kini secara automatik
• Kami tahu di mana untuk mencari Alat Pembangun untuk pekerja perkhidmatan dan skrip kandungan

Dalam bahagian seterusnya, saya akan menerangkan butiran pelaksanaan sambungan "Audio halaman" kecil saya.

Terima kasih kerana membaca!

Atas ialah kandungan terperinci Sambungan Chrome - persediaan persekitaran. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!