-
Notifications
You must be signed in to change notification settings - Fork 8k
/
index.md
280 lines (211 loc) · 10.4 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
---
title: find.find()
slug: Mozilla/Add-ons/WebExtensions/API/find/find
---
{{AddonSidebar}}
Recherche du texte dans un onglet.
Vous pouvez utiliser cette fonction pour rechercher des pages Web HTTP(S) normales. Il recherche un seul onglet : vous pouvez spécifier l'ID d'un onglet particulier à rechercher, ou il recherchera l'onglet actif par défaut. Il recherche toutes les images de l'onglet..
Vous pouvez rendre la recherche sensible à la casse et la faire correspondre uniquement à des mots entiers.
Par défaut, la fonction renvoie juste le nombre de correspondances trouvées. En transmettant les options `includeRangeData` et `includeRectData`, vous pouvez obtenir plus d'informations sur l'emplacement des correspondances dans l'onglet cible.
Cette fonction stocke les résultats en interne, donc la prochaine fois qu'une extension appelle {{WebExtAPIRef("find.highlightResults()")}}, alors les résultats de cet appel _find_ seront mis en surbrillance, jusqu'à ce que quelqu'un appelle `find()`.
C'est une fonction asynchrone qui renvoie une [`Promise`](/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise).
## Syntaxe
```js
browser.find.find(
queryphrase, // string
options, // optional object
);
```
### Paramètres
- `queryphrase`
- : `string`. Le texte à rechercher
- `options`{{optional_inline}}
- : `object`. Un objet spécifiant des options supplémentaires. Il peut prendre l'une des propriétés suivantes, toutes facultatives :
- `tabId`
- : `integer`. ID de l'onglet à rechercher. Par défaut à l'onglet actif
- `caseSensitive`
- : `boolean`. Si true, la recherche est sensible à la casse. Par défault à `false`.
- `entireWord`
- : `boolean`. Comparaison seulement entre les mots entiers : ainsi "Tok" ne sera pas comparé dans "Tokyo". Par défaut à `false`.
- `includeRangeData`
- : `boolean`. Inclure les groupes de données dans la réponse, which describe where in the page DOM the match was found. Defaults to `false`.
- `includeRectData`
- : `boolean`. Inclure les données de rectangle dans la réponse, qui décrit où la correspondance a été trouvée dans la page de rendu. Par défaut à `false`.
### Valeur retournée
Une [`Promise`](/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise) qui sera remplie avec un objet contenant jusqu'à trois propriétés :
- `count`
- : `integer`. Le nombre de résultat trouvés.
- `rangeData`{{optional_inline}}
- : `array`. Si `includeRangeData` a été donné dans le paramètre `options`, cette propriété sera incluse. Il est fourni sous la forme d'un tableau d'objets `RangeData`, un pour chaque correspondance. Chaque objet `RangeData` décrit où la correspondance a été trouvée dans l'arborescence DOM. Cela permettrait, par exemple, une extension pour obtenir le texte entourant chaque correspondance, afin d'afficher le contexte pour les correspondances.
Les élements correspondent aux éléments données dans `rectData`, donc `rangeData[i]` décrit la même correspondance que `rectData[i]`.
Chaque `RangeData` contient les propriétés suivantes :
- `framePos`
- : L'index de l'image contenant la correspondance. 0 correspond à une fenêtre parente. Notez que l'ordre des objets dans un tableau `rangeData` s'alignera séquentiellement avec l'ordre des index d'images : par exemple, `framePos` pour la première séquence d'objets `rangeData` sera 0, `framePos` pour la séquence suivante sera 1, et ainsi de suite.
- `startTextNodePos`
- : La position ordinale du noeud de texte dans lequel la correspondance a démarrée.
- `endTextNodePos`
- : La position ordinale du noeud de texte dans lequel la correspondance s'est terminée.
- `startOffset`
- : La position de la chaîne de caractères ordinale du début du mot correspondant dans le noeud texte de début.
- `endOffset`
- : La position de la chaîne de caractères ordinale de la fin du mot trouvé dans le nœud de texte final.
- `rectData`{{optional_inline}}
- : `array`. Si `includeRectData` a été donné dans les paramètres des `options`, cette propriété sera incluse. C'est un tableau d'objets `RectData` . Il contient des rectangles clients pour tout le texte correspondant à la recherche, par rapport à la partie supérieure gauche de la fenêtre. Les extensions peuvent l'utiliser pour fournir une mise en évidence personnalisée les résultats..
Chaque objet `RectData` contient des données rectangle pour une seule correspondance. Il a deux propriétés :
- `rectsAndTexts`
- : Un objet contenant deux propriétés, les deux tableaux :
- `rectList`: un tableau d'objets ayant chacun quatre propriétés entières : `top`, `left`, `bottom`, `right`. Ceux-ci décrivent un rectangle par rapport à la partie supérieure gauche de la fenêtre.
- `textList`: un tableau de chaînes, correspondant au tableau `rectList`. L'entrée de `textList[i]` contient la partie du match délimitée par le rectangle de `rectList[i]`.
Par exemple, considérons une partie d'une page Web qui ressemble à ceci :
![](rects-1.png)Si vous recherchez "You may", la comparaison doit être décrit par deux rectangles :
![](rects-2.png)Dans le cas, dans le `RectData` qui décrit cette correspondance, `rectsAndTexts.rectList` et `rectsAndTexts.textList` auront chacun 2 éléments.
- `textList[0]` contiendra "You ", et `rectList[0]` contiendra son rectangle de délimitation.
- `textList[1]` contiendra "may", et `rectList[1]` contiendra son rectangle de délimitation.
- `text`
- : Le texte complet de comparaison, "You may" dans l'exemple ci-dessus.
## Compatibilité des navigateurs
{{Compat}}
## Exemples
### Exemples basics
Recherchez "banana" dans l'onglet actif, log le nombre de correspondances et mettez-les en surbrillance :
```js
function found(results) {
console.log(`There were: ${results.count} matches.`);
if (results.count > 0) {
browser.find.highlightResults();
}
}
browser.find.find("banana").then(found);
```
Rechercher "banana" dans tous les onglets (notez que cela nécessite la [permission](/fr/Add-ons/WebExtensions/manifest.json/permissions) "tabs", car il accède à `tab.url`):
```js
async function findInAllTabs(allTabs) {
for (let tab of allTabs) {
let results = await browser.find.find("banana", { tabId: tab.id });
console.log(`In page "${tab.url}": ${results.count} matches.`);
}
}
browser.tabs.query({}).then(findInAllTabs);
```
### Utilisation de rangeData
Dans cet exemple, l'extension utilise `rangeData` pour obtenir le contexte dans lequel la correspondance a été trouvée. Le contexte est le `textContent` complet du noeud dans lequel la correspondance a été trouvée. Si la correspondance s'étend sur des noeuds, le contexte est la concaténation du `textContent` de tous les noeuds étendus.
Notez que pour des raisons de simplicité, cet exemple ne gère pas les pages contenant des cadres. Pour cela, vous devez divisez `rangeData` en groupes, un par frame, et executer le script dans chaque image.
Le script d'arrière plan :
```js
// background.js
async function getContexts(matches) {
// get the active tab ID
let activeTabArray = await browser.tabs.query({
active: true,
currentWindow: true,
});
let tabId = activeTabArray[0].id;
// execute the content script in the active tab
await browser.tabs.executeScript(tabId, { file: "get-context.js" });
// ask the content script to get the contexts for us
let contexts = await browser.tabs.sendMessage(tabId, {
ranges: matches.rangeData,
});
for (let context of contexts) {
console.log(context);
}
}
browser.browserAction.onClicked.addListener((tab) => {
browser.find.find("example", { includeRangeData: true }).then(getContexts);
});
```
Le script de contenu :
```js
/**
* Get all the text nodes into a single array
*/
function getNodes() {
let walker = document.createTreeWalker(
document,
window.NodeFilter.SHOW_TEXT,
null,
false,
);
let nodes = [];
while ((node = walker.nextNode())) {
nodes.push(node);
}
return nodes;
}
/**
* Gets all text nodes in the document, then for each match, return the
* complete text content of nodes that contained the match.
* If a match spanned more than one node, concatenate the textContent
* of each node.
*/
function getContexts(ranges) {
let contexts = [];
let nodes = getNodes();
for (let range of ranges) {
let context = nodes[range.startTextNodePos].textContent;
let pos = range.startTextNodePos;
while (pos < range.endTextNodePos) {
pos++;
context += nodes[pos].textContent;
}
contexts.push(context);
}
return contexts;
}
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
sendResponse(getContexts(message.ranges));
});
```
### Utiliser rectData
Dans cet exemple, l'extensions utilise `rectData` pour comparer "redact", en ajoutant des DIVs noires au dessus de leurs rectangles de délimitation :
![](redacted.png)Notez qu'il y a plusieurs façons, c'est une mauvaise façon d'atteindre les pages.
Le script d'arrière-plan :
```js
// background.js
async function redact(matches) {
// get the active tab ID
let activeTabArray = await browser.tabs.query({
active: true,
currentWindow: true,
});
let tabId = activeTabArray[0].id;
// execute the content script in the active tab
await browser.tabs.executeScript(tabId, { file: "redact.js" });
// ask the content script to redact matches for us
await browser.tabs.sendMessage(tabId, { rects: matches.rectData });
}
browser.browserAction.onClicked.addListener((tab) => {
browser.find.find("banana", { includeRectData: true }).then(redact);
});
```
Le script de contenu :
```js
// redact.js
/**
* Add a black DIV where the rect is.
*/
function redactRect(rect) {
var redaction = document.createElement("div");
redaction.style.backgroundColor = "black";
redaction.style.position = "absolute";
redaction.style.top = `${rect.top}px`;
redaction.style.left = `${rect.left}px`;
redaction.style.width = `${rect.right - rect.left}px`;
redaction.style.height = `${rect.bottom - rect.top}px`;
document.body.appendChild(redaction);
}
/**
* Go through every rect, redacting them.
*/
function redactAll(rectData) {
for (match of rectData) {
for (rect of match.rectsAndTexts.rectList) {
redactRect(rect);
}
}
}
browser.runtime.onMessage.addListener((message) => {
redactAll(message.rects);
});
```
{{WebExtExamples}}