thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: improve custom query handler docs (#8235)

Browse Source
This commit is contained in:
Andreas Opferkuch 2022-04-19 14:48:22 +02:00 committed by GitHub
parent b6504d7186
commit 0c8174b987
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 7 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/api.md
View File

@ -721,7 +721,7 @@ The product is set by the `PUPPETEER_PRODUCT` environment variable or the `produ
- `name` <[string]> The name that the custom query handler will be registered under. - `name` <[string]> The name that the custom query handler will be registered under.
- `queryHandler` <[CustomQueryHandler]> The [custom query handler](#interface-customqueryhandler) to register. - `queryHandler` <[CustomQueryHandler]> The [custom query handler](#interface-customqueryhandler) to register.
Registers a [custom query handler](#interface-customqueryhandler). After registration, the handler can be used everywhere where a selector is expected by prepending the selection string with `<name>/`. The name is only allowed to consist of lower and upper case Latin letters. Registers a [custom query handler](#interface-customqueryhandler).
Example: Example:
@ -5525,7 +5525,11 @@ This method is identical to `off` and maintained for compatibility with Node's E
### interface: CustomQueryHandler ### interface: CustomQueryHandler
Contains two functions `queryOne` and `queryAll` that can be [registered](#puppeteerregistercustomqueryhandlername-queryhandler) as alternative querying strategies. The functions `queryOne` and `queryAll` are executed in the page context. `queryOne` should take an `Element` and a selector string as argument and return a single `Element` or `null` if no element is found. `queryAll` takes the same arguments but should instead return a `NodeList<Element>` or `Array<Element>` with all the elements that match the given query selector. After [registration](#puppeteerregistercustomqueryhandlername-queryhandler), the handler can be used everywhere where a selector is expected by prepending the selection string with `<name>/`. The name is only allowed to consist of lower and upper case Latin letters.
Contains two functions `queryOne` and `queryAll` that are executed in the page context. `queryOne` should take an `Element` and a selector string as argument and return a single `Element` or `null` if no element is found. `queryAll` takes the same arguments but should instead return a `NodeList<Element>` or `Array<Element>` with all the elements that match the given query selector.
**NOTE:** Because the function code needs to be serialized, it is **not possible** to access anything outside its scope or use imports. See e.g. [the pierce handler](https://github.com/puppeteer/puppeteer/blob/v13.5.2/src/common/QueryHandler.ts#L115) which has redundancies because of this limitation.
### interface: Selector ### interface: Selector
@ -5534,7 +5538,7 @@ The default behavior is to regard the string as a [CSS selector] and query using
If a selector string contains a forward slash `/` the selector is instead regarded as custom selector where everything before the slash is the [custom handler](#puppeteerregistercustomqueryhandlername-queryhandler) name and everything after is the selector: `<handler>/<selector>`. If a selector string contains a forward slash `/` the selector is instead regarded as custom selector where everything before the slash is the [custom handler](#puppeteerregistercustomqueryhandlername-queryhandler) name and everything after is the selector: `<handler>/<selector>`.
Puppeteer ships with two such custom handlers pre-registered: Puppeteer ships with two such custom handlers pre-registered:
- `aria/`: Queries the accessibilty tree for computed accessibility properties. - `aria`: Queries the accessibilty tree for computed accessibility properties.
The selectors consist of an accessible name to query for and optionally The selectors consist of an accessible name to query for and optionally
further aria attributes on the form `[<attribute>=<value>]`. further aria attributes on the form `[<attribute>=<value>]`.
Currently, we only support the `name` and `role` attribute. Currently, we only support the `name` and `role` attribute.