Коротка відповідь
Контентний скрипт читає або змінює DOM вебсторінки, за замовчуванням виконуючись у середовищі, ізольованому від JavaScript сайту. DOM спільний, а змінні JavaScript — ні. Можна дослідити обчислений стиль елемента без доступу до приватного сховища застосунку сайту.
Вибирайте статичні content_scripts, коли функція має автоматично працювати за відомими URL-шаблонами. Вибирайте scripting.executeScript, коли користувач викликає інструмент сторінки. Динамічна реєстрація корисна для змінного набору автоматичних сайтів. Ці стратегії керують впровадженням, але не усувають потреби обробляти навігацію, фрейми, повторне підключення та ворожі дані сторінки.
Практичні кроки реалізації
Визначте межі документа
Скрипт верхнього фрейму не може автоматично дослідити iframe з іншим джерелом. all_frames — свідомий вибір, а кожен фрейм має відповідати правилам доступу. Shadow roots також потребують явної обробки; закриті корені не є звичайними нащадками document. Повідомте ці межі у продукті замість удаваного повного результату.
Зробіть повторне підключення безпечним
Користувач може двічі викликати скрипт. Без захисту кожен виклик додасть ще одного слухача чи накладку. Зберігайте специфічний для розширення маркер в ізольованому світі та надайте очищення встановлених ресурсів. Скасування динамічної реєстрації припиняє майбутнє впровадження, але не прибирає код і стилі вже відкритого документа.
Пропорційно реагуйте на зміни сторінки
SPA може замінити область без перезавантаження документа. Делегування подій часто достатнє для дослідження натискань, бо не зберігає кожного елемента. Для сканування використовуйте обмежений observer і групуйте зміни із затримкою замість повного обходу DOM після кожної мутації. Відключайте observers при вимкненні функції.
Вважайте дані сторінки недовіреними
Повертайте компактні прості записи. Не просіть привілейований воркер завантажувати довільний URL сторінки. Показуйте отриманий текст текстовими API. Якщо змінюєте вміст, збережіть власні зміни й відновлюйте лише там, де сайт не редагував їх самостійно. LocaleStress явно описує light DOM верхнього фрейму й конфлікти відновлення — корисний приклад чесних меж замість універсального покриття.
Приклад реалізації
Статичний скрипт може відповідати на вузько визначений запит виділеного тексту. Глобальний маркер належить ізольованому світу цього розширення, тому однойменна змінна JavaScript сайту не є спільною.
if (!globalThis.__selectionReaderInstalled) {
globalThis.__selectionReaderInstalled = true;
chrome.runtime.onMessage.addListener((message, _sender, respond) => {
if (message?.type !== "selection/read") return;
respond({ text: String(window.getSelection() ?? "").slice(0, 2000) });
});
}
Сторінка розширення може викликати скрипт через chrome.tabs.sendMessage(tabId, { type: "selection/read" }). Обробіть відмову, якщо у вкладці немає отримувача, вона перейшла на інший документ або недоступна. Межа 2000 символів — приклад обмеження застосунку, а не API браузера. Повідомлення, що змінюють сторінку або відкривають конфіденційний стан, також потребують перевірки під час виконання.
Для більшого скрипту явного запуску використовуйте файл, щоб свідомо пакувати імпорти й допоміжні функції. Якщо впроваджуєте функцію, вона не може захоплювати змінні контексту виклику; передавайте серіалізовані аргументи.
Компроміси та альтернативи
Скрипт ізольованого світу — безпечніший типовий вибір для дослідження DOM. Виконання MAIN-world доречне лише для конкретної інтеграції з JavaScript сайту; сайт може спостерігати цей код або втручатися. Збережіть міст мінімальним і вважайте відповіді недовіреними.
Автоматичні скрипти обмінюють зручність на ширший постійний доступ. Явний виклик зменшує його, але потребує чіткого стану непідтримуваної сторінки. Інструмент може підтримувати лише зразок верхнього фрейму; це корисно за точного опису меж у звіті.
Поширені помилки
- Вважати, що ізольований світ захищає DOM від змін сайту.
- Повертати живі DOM-вузли через повідомлення.
- Повторно впроваджувати без прибирання дубльованих observers і слухачів.
- Звітувати про перевірку iframe чи закритого shadow root, якщо їх пропущено.
- Відновлювати старий текст поверх пізнішого редагування застосунку.
Контрольний список випуску
- Шаблони охоплюють потрібні сайти без зайвих джерел.
- Повторний виклик створює одну активну функцію.
- Для SPA-змін, навігації й перезавантаження є відновлення.
- Вимкнені функції прибирають слухачі, observers і власний UI.
- Отримані дані обмежені й показуються як текст.
- Звіти чесно визначають покриття фреймів та shadow DOM.
Поширені запитання
Чи доступні контентному скрипту всі API розширення?
Ні. Набір API відрізняється від сторінок розширення. Використовуйте вузьке повідомлення воркеру, коли справді потрібна привілейована операція.
Чи document_idle чекає на всі SPA-компоненти?
Ні. Це час початкового впровадження, а не завершення майбутнього відображення застосунку. Спостерігайте або запитуйте конкретну динамічну область.
Що має підтримувати перша реалізація?
Одні явні межі документа й одну безпечну повторну операцію. Додавайте фрейми, shadow roots та автоматичне спостереження, коли можете пояснити доступ, очищення й значення результатів.
Первинні джерела
Пов’язані посібники та приклади
Потрібно реалізувати це у вашому продукті?
Перегляньте відповідні приклади продуктів або поділіться контекстом розробки вебзастосунку, розширення Chrome, API чи SaaS.