chrome.bookmarks

Descrição

Use a API chrome.bookmarks para criar, organizar e manipular favoritos. Consulte também Substituir páginas, que pode ser usado para criar uma página personalizada do Gerenciador de favoritos.

Clicar na estrela adiciona um favorito
Clicar na estrela adiciona um favorito.

Permissões

bookmarks

É necessário declarar a permissão "bookmarks" no manifesto de extensões para usar a API bookmarks. Exemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "bookmarks"
  ],
  ...
}

Conceitos e uso

Objetos e propriedades

Os favoritos são organizados em uma árvore, em que cada nó é um favorito ou uma pasta (às vezes chamado de grupo). Cada nó da árvore é representado por um objeto bookmarks.BookmarkTreeNode.

As propriedades BookmarkTreeNode são usadas em toda a API chrome.bookmarks. Por exemplo, ao chamar bookmarks.create, você transmite o pai do novo nó (parentId) e, opcionalmente, as propriedades index, title e url do nó. Consulte bookmarks.BookmarkTreeNode para ver informações sobre as propriedades que um nó pode ter.

Exemplos

O código a seguir cria uma pasta com o título "Favoritos de extensão". O primeiro argumento para create() especifica as propriedades da nova pasta. O segundo argumento define uma função a ser executada após a criação da pasta.

chrome.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

O próximo snippet cria um favorito que aponta para a documentação do desenvolvedor para extensões. Como nada de ruim vai acontecer se a criação do favorito falhar, esse código não precisa definir uma função de callback.

chrome.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

Para testar essa API, instale o exemplo da API bookmark (em inglês) no repositório chrome-extension-samples.

Tipos

BookmarkTreeNode

Um nó (um favorito ou uma pasta) na árvore de favoritos. Os nós filhos são ordenados dentro de sua pasta pai.

Propriedades

  • crianças

    BookmarkTreeNode[] opcional

    Uma lista ordenada de filhos deste nó.

  • dateAdded

    número opcional

    Quando este nó foi criado, em milissegundos desde o período (new Date(dateAdded)).

  • dateGroupModified

    número opcional

    Quando o conteúdo dessa pasta foi alterado pela última vez, em milissegundos, desde o período.

  • dateLastUsed

    número opcional

    Chrome 114 ou mais recente

    Quando esse nó foi aberto pela última vez, em milissegundos, desde o período. Não definido para pastas.

  • id

    string

    O identificador exclusivo do nó. Os IDs são exclusivos no perfil atual e permanecem válidos mesmo após a reinicialização do navegador.

  • índice

    número opcional

    A posição baseada em 0 deste nó na pasta pai.

  • parentId

    string opcional

    O id da pasta mãe. Omitido para o nó raiz.

  • title

    string

    O texto exibido para o nó.

  • não modificável

     opcional

    Indica o motivo pelo qual esse nó não pode ser modificado. O valor managed indica que esse nó foi configurado pelo administrador do sistema ou pelo custodiante de um usuário supervisionado. Omitido se o nó puder ser modificado pelo usuário e pela extensão (padrão).

  • url

    string opcional

    É o URL acessado quando um usuário clica no favorito. Omitido para pastas.

BookmarkTreeNodeUnmodifiable

Chrome 44 ou mais recente

Indica o motivo pelo qual esse nó não pode ser modificado. O valor managed indica que esse nó foi configurado pelo administrador do sistema. Omitido se o nó puder ser modificado pelo usuário e pela extensão (padrão).

Valor

CreateDetails

Objeto transmitido para a função create().

Propriedades

  • índice

    número opcional

  • parentId

    string opcional

    O padrão é a pasta "Outros favoritos".

  • title

    string opcional

  • url

    string opcional

Propriedades

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Descontinuado

As operações de gravação de favoritos não são mais limitadas pelo Chrome.

Valor

1000.000

MAX_WRITE_OPERATIONS_PER_HOUR

Descontinuado

As operações de gravação de favoritos não são mais limitadas pelo Chrome.

Valor

1000.000

Métodos

create()

Promessa 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

Cria um favorito ou uma pasta no parentId especificado. Se o URL for NULL ou estiver ausente, será uma pasta.

Parâmetros

Retorna

  • Chrome 90 ou mais recente

    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.

get()

Promessa 
chrome.bookmarks.get(
  idOrIdList: string|[string,...string[]],
  callback?: function,
)

Recupera os FavoriteTreeNodes especificados.

Parâmetros

  • idOrIdList

    string|[string,...string[]]

    Um ID com valor de string único ou uma matriz de IDs com valores de string

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (results: BookmarkTreeNode[])=>void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou mais recente

    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.

getChildren()

Promessa 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

Recupera os filhos do ID FavoriteTreeNode especificado.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou mais recente

    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.

getRecent()

Promessa 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

Recupera os favoritos adicionados recentemente.

Parâmetros

  • numberOfItems

    number

    O número máximo de itens para retornar.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (results: BookmarkTreeNode[])=>void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou mais recente

    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.

getSubTree()

Promessa 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

Recupera parte da hierarquia dos Favoritos, começando no nó especificado.

Parâmetros

  • id

    string

    O ID da raiz da subárvore a ser recuperada.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (results: BookmarkTreeNode[])=>void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou mais recente

    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.

getTree()

Promessa 
chrome.bookmarks.getTree(
  callback?: function,
)

Recupera toda a hierarquia dos Favoritos.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou mais recente

    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.

move()

Promessa 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

Move o FavoriteTreeNode especificado para o local fornecido.

Parâmetros

  • id

    string

  • destination

    objeto

    • índice

      número opcional

    • parentId

      string opcional

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (result: BookmarkTreeNode)=>void

Retorna

  • Chrome 90 ou mais recente

    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.

remove()

Promessa 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

Remove um favorito ou uma pasta de favoritos vazia.

Parâmetros

  • id

    string

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 90 ou mais recente

    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.

removeTree()

Promessa 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

Remove recursivamente uma pasta de favoritos.

Parâmetros

  • id

    string

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 90 ou mais recente

    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.

Promessa 
chrome.bookmarks.search(
  query: string|object,
  callback?: function,
)

Procura FavoriteTreeNodes que correspondam à consulta especificada. As consultas especificadas com um objeto produzem FavoriteTreeNodes correspondentes a todas as propriedades especificadas.

Parâmetros

  • consulta

    string|objeto

    Uma string de palavras e frases entre aspas que correspondem a URLs e títulos de favoritos ou um objeto. Se um objeto, as propriedades query, url e title poderão ser especificadas, e os favoritos correspondentes a todas as propriedades especificadas serão produzidos.

    • consulta

      string opcional

      Uma string de palavras e frases entre aspas que correspondem a URLs e títulos de favoritos.

    • title

      string opcional

      O título do favorito. Corresponde literalmente.

    • url

      string opcional

      O URL do favorito; corresponde literalmente. As pastas não têm URL.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (results: BookmarkTreeNode[])=>void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou mais recente

    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.

update()

Promessa 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

Atualiza as propriedades de um favorito ou de uma pasta. Especifique apenas as propriedades que você quer mudar. As propriedades não especificadas não serão alteradas. Observação:no momento, somente "title" e "url" são compatíveis.

Parâmetros

  • id

    string

  • Mudanças

    objeto

    • title

      string opcional

    • url

      string opcional

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (result: BookmarkTreeNode)=>void

Retorna

  • Chrome 90 ou mais recente

    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

onChanged

chrome.bookmarks.onChanged.addListener(
  callback: function,
)

Disparado quando um favorito ou uma pasta é alterado. Observação:no momento, isso só acontece com mudanças de título e URL.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (id: string,changeInfo: object)=>void

    • id

      string

    • changeInfo

      objeto

      • title

        string

      • url

        string opcional

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(
  callback: function,
)

Disparado quando os filhos de uma pasta mudam a ordem devido à classificação na interface. Não é chamado como resultado de um move().

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (id: string,reorderInfo: object)=>void

    • id

      string

    • reorderInfo

      objeto

      • childIds

        string[]

onCreated

chrome.bookmarks.onCreated.addListener(
  callback: function,
)

Disparado quando um favorito ou uma pasta é criado.

Parâmetros

onImportBegan

chrome.bookmarks.onImportBegan.addListener(
  callback: function,
)

Disparado quando uma sessão de importação de favoritos é iniciada. Observadores pesados precisam ignorar as atualizações onCreated até que onImportEnded seja acionado. Os observadores ainda vão processar outras notificações imediatamente.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    ()=>void

onImportEnded

chrome.bookmarks.onImportEnded.addListener(
  callback: function,
)

Disparado quando uma sessão de importação de favoritos é encerrada.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    ()=>void

onMoved

chrome.bookmarks.onMoved.addListener(
  callback: function,
)

Disparado quando um favorito ou uma pasta é movido para uma pasta pai diferente.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (id: string,moveInfo: object)=>void

    • id

      string

    • moveInfo

      objeto

      • índice

        number

      • oldIndex

        number

      • oldParentId

        string

      • parentId

        string

onRemoved

chrome.bookmarks.onRemoved.addListener(
  callback: function,
)

Disparado quando um favorito ou uma pasta é removido. Quando uma pasta é removida recursivamente, uma única notificação é disparada para a pasta e nenhuma para seu conteúdo.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (id: string,removeInfo: object)=>void

    • id

      string

    • removeInfo

      objeto