chrome.bookmarks

Descrição

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

Clicar na estrela adiciona um favorito
Clique na estrela para adicionar um favorito.

Permissões

bookmarks

É necessário declarar a permissão "bookmarks" no manifesto da extensão para usar a API de favoritos. 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 chamada de grupo. Cada nó na á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 saber mais sobre as propriedades que um nó pode ter.

Exemplos

O código a seguir cria uma pasta com o título "Favoritos da 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 snippet a seguir cria um marcador que aponta para a documentação do desenvolvedor para extensões. Como nada de ruim vai acontecer se a criação da marcação não funcionar, 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 Bookmarks do 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 na pasta mãe.

Propriedades

  • crianças

    BookmarkTreeNode[] opcional

    Uma lista ordenada de filhos desse nó.

  • dateAdded

    número opcional

    Quando o nó foi criado, em milissegundos desde a época (new Date(dateAdded)).

  • dateGroupModified

    número opcional

    Quando o conteúdo dessa pasta foi modificado pela última vez, em milissegundos desde a época.

  • dateLastUsed

    número opcional

    Chrome 114 e versões mais recentes

    Quando esse nó foi aberto pela última vez, em milissegundos desde a época. 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.

  • index

    número opcional

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

  • parentId

    string opcional

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

  • título

    string

    O texto exibido para o nó.

  • não modificável

    "managed"
     optional

    Indica por que esse nó não pode ser modificado. O valor managed indica que esse nó foi configurado pelo administrador do sistema ou pelo responsável por 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 para o qual é feita a navegação quando um usuário clica no marcador de página. Omitido para pastas.

BookmarkTreeNodeUnmodifiable

Chrome 44 e versões mais recentes

Indica por que 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

"gerenciado"

CreateDetails

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

Propriedades

  • index

    número opcional

  • parentId

    string opcional

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

  • título

    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

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Descontinuado

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

Valor

1000000

Métodos

create()

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

Cria um favorito ou uma pasta no ID pai especificado. Se o URL estiver nulo ou ausente, será uma pasta.

Parâmetros

Retorna

  • Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

get()

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

Recupera os BookmarkTreeNodes especificados.

Parâmetros

  • idOrIdList

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

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getChildren()

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

Recupera os filhos do ID do BookmarkTreeNode especificado.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido 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 opcional

    O parâmetro callback tem este formato: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getSubTree()

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

Recupera parte da hierarquia de favoritos, começando no nó especificado.

Parâmetros

  • id

    string

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getTree()

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

Recupera toda a hierarquia de favoritos.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

move()

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

Move o BookmarkTreeNode especificado para o local fornecido.

Parâmetros

  • id

    string

  • destino

    objeto

    • index

      número opcional

    • parentId

      string opcional

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (result: BookmarkTreeNode) => void

Retorna

  • Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido 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 opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido 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 opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

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

Procura BookmarkTreeNodes que correspondem à consulta especificada. As consultas especificadas com um objeto produzem BookmarkTreeNodes que correspondem a todas as propriedades especificadas.

Parâmetros

  • consulta

    string | object

    Uma string de palavras e frases entre aspas que são correspondidas aos URLs e títulos de favoritos ou um objeto. Se for um objeto, as propriedades query, url e title podem ser especificadas, e os marcadores de páginas correspondentes a todas as propriedades especificadas serão produzidos.

    • consulta

      string opcional

      Uma string de palavras e frases entre aspas que são comparadas com URLs e títulos de favoritos.

    • título

      string opcional

      O título da marcação de página; corresponde exatamente.

    • url

      string opcional

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

update()

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

Atualiza as propriedades de um favorito ou pasta. Especifique apenas as propriedades que você quer mudar. As propriedades não especificadas vão permanecer inalteradas. Observação:no momento, apenas "title" e "url" são aceitos.

Parâmetros

  • id

    string

  • muda

    objeto

    • título

      string opcional

    • url

      string opcional

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (result: BookmarkTreeNode) => void

Retorna

  • Chrome 90 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

Eventos

onChanged

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

Acionado quando uma favorita ou pasta muda. Observação:no momento, apenas mudanças no título e no URL acionam isso.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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

    • id

      string

    • changeInfo

      objeto

      • título

        string

      • url

        string opcional

onChildrenReordered

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

É acionado quando os filhos de uma pasta mudam de ordem devido à ordenação na interface. Isso não é chamado como resultado de um move().

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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

    • id

      string

    • reorderInfo

      objeto

      • childIds

        string[]

onCreated

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

Acionado quando uma favorita ou pasta é criada.

Parâmetros

onImportBegan

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    () => 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 este formato: 

    () => void

onMoved

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

É acionado quando um favorito ou uma pasta é movido para uma pasta mãe diferente.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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

    • id

      string

    • moveInfo

      objeto

      • index

        number

      • oldIndex

        number

      • oldParentId

        string

      • parentId

        string

onRemoved

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

Acionado quando uma marcação ou pasta é removida. Quando uma pasta é removida de forma recursiva, uma única notificação é disparada para a pasta, e nenhuma para o conteúdo dela.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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

    • id

      string

    • removeInfo

      objeto

      • index

        number

      • Chrome 48 e versões mais recentes
      • parentId

        string