chrome.readingList

Descrição

Use a API chrome.readingList para ler e modificar os itens da Lista de leitura.

Permissões

readingList

Para usar a API Reading List, adicione a permissão "readingList" ao arquivo de manifesto da extensão:

manifest.json:

{
  "name": "My reading list extension",
  ...
  "permissions": [
    "readingList"
  ]
}

Disponibilidade

Chrome 120+ MV3+

O Chrome apresenta uma Lista de leitura localizada no painel lateral. Ele permite que os usuários salvem páginas da Web para ler depois ou quando estiverem off-line. Use a API Reading List para recuperar e adicionar ou remover itens da lista.

Lista de leitura com vários artigos
Lista de leitura com vários artigos

Conceitos e uso

Ordenação de itens

Os itens da lista de leitura não estão em uma ordem garantida.

Exclusividade do item

Os itens são codificados por URL. Isso inclui o hash e a string de consulta.

Casos de uso

As seções abaixo demonstram alguns casos de uso comuns da API Reading List. Consulte Exemplos de extensão para ver exemplos completos.

Adicionar um item

Para adicionar um item à Lista de leitura, use chrome.readingList.addEntry():

chrome.readingList.addEntry({
  title: "New to the web platform in September | web.dev",
  url: "https://developer.chrome.com/",
  hasBeenRead: false
});

Mostrar itens

Para mostrar itens da lista de leitura, use o método chrome.readingList.query() para recuperá-los. 

const items = await chrome.readingList.query({});

for (const item of items) {
  // Do something do display the item
}

Marcar um item como lido

Você pode usar chrome.readingList.updateEntry() para atualizar o título, o URL e o status de leitura. O código a seguir marca um item como lido:

chrome.readingList.updateEntry({
  url: "https://developer.chrome.com/",
  hasBeenRead: true
});

Remover um item

Para remover um item, use chrome.readingList.removeEntry():

chrome.readingList.removeEntry({
  url: "https://developer.chrome.com/"
});

Exemplos de extensão

Para ver mais demonstrações de extensões da API Reading List, consulte o exemplo da API Reading List.

Tipos

AddEntryOptions

Propriedades

  • hasBeenRead

    boolean

    Será true se a entrada tiver sido lida.

  • título

    string

    O título da entrada.

  • url

    string

    O URL da entrada.

QueryInfo

Propriedades

  • hasBeenRead

    booleano opcional

    Indica se você quer pesquisar itens lidos (true) ou não lidos (false).

  • título

    string opcional

    Um título a ser pesquisado.

  • url

    string opcional

    Um URL a ser pesquisado.

ReadingListEntry

Propriedades

  • creationTime

    number

    Hora em que a entrada foi criada. Gravado em milissegundos desde 1o de janeiro de 1970.

  • hasBeenRead

    boolean

    Será true se a entrada tiver sido lida.

  • lastUpdateTime

    number

    A última vez em que a entrada foi atualizada. Esse valor está em milissegundos desde 1o de janeiro de 1970.

  • título

    string

    O título da entrada.

  • url

    string

    O URL da entrada.

RemoveOptions

Propriedades

  • url

    string

    O URL a ser removido.

UpdateEntryOptions

Propriedades

  • hasBeenRead

    booleano opcional

    O status de leitura atualizado. Se um valor não for fornecido, o status atual será mantido.

  • título

    string opcional

    O novo título. Se um valor não for fornecido, o bloco existente será mantido.

  • url

    string

    O URL que será atualizado.

Métodos

addEntry()

Promessa 
chrome.readingList.addEntry(
  entry: AddEntryOptions,
  callback?: function,
)

Adiciona uma entrada à Lista de leitura, se ela não existir.

Parâmetros

  • A entrada a ser adicionada à Lista de leitura.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

query()

Promessa 
chrome.readingList.query(
  info: QueryInfo,
  callback?: function,
)

Recupera todas as entradas que correspondem às propriedades QueryInfo. As propriedades não informadas não serão correspondidas.

Parâmetros

Retorna

  • Promise<ReadingListEntry[]>

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

removeEntry()

Promessa 
chrome.readingList.removeEntry(
  info: RemoveOptions,
  callback?: function,
)

Remove uma entrada da lista de leitura, se ela existir.

Parâmetros

  • informações

    RemoveOptions

    A entrada a ser removida da Lista de leitura.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

updateEntry()

Promessa 
chrome.readingList.updateEntry(
  info: UpdateEntryOptions,
  callback?: function,
)

Atualiza uma entrada da lista de leitura, se houver.

Parâmetros

  • informações

    UpdateEntryOptions

    A entrada a ser atualizada.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onEntryAdded

chrome.readingList.onEntryAdded.addListener(
  callback: function,
)

Acionado quando um ReadingListEntry é adicionado à lista de leitura.

Parâmetros

onEntryRemoved

chrome.readingList.onEntryRemoved.addListener(
  callback: function,
)

Acionado quando um ReadingListEntry é removido da lista de leitura.

Parâmetros

onEntryUpdated

chrome.readingList.onEntryUpdated.addListener(
  callback: function,
)

Acionado quando um ReadingListEntry é atualizado na lista de leitura.

Parâmetros