chrome.bookmarks

Descrição

Use a API chrome.bookmarks para criar, organizar e manipular favoritos. Consulte também Substituir páginas, que você pode usar 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 os "favoritos" permissão no manifesto de 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, na qual cada nó da árvore é um favorito ou uma pasta (às vezes chamado de grupo). Cada nó da árvore é representado objeto bookmarks.BookmarkTreeNode.

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

Exemplos

O código a seguir cria uma pasta com o título "Extensão de favoritos". O primeiro argumento para create() especifica propriedades para a nova pasta. O segundo argumento define uma função a ser executado 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 acontecerá se a criação do favorito falhar, esse código não se preocupa em definir um 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 Favorites do chrome-extension-samples repositório de dados.

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 o nó foi criado, em milissegundos desde o período (new Date(dateAdded)).

  • dateGroupModified

    número opcional

    Quando o conteúdo desta pasta foi alterado pela última vez, em milissegundos, a partir do 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.

  • index

    número opcional

    A posição baseada em 0 deste nó dentro de sua pasta pai.

  • parentId

    string opcional

    O id da pasta principal. Omitido para o nó raiz.

  • título

    string

    O texto exibido para o nó.

  • não modificável

    "managed"
     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 para onde o usuário clicou no favorito. Omitido para pastas.

BookmarkTreeNodeUnmodifiable

Chrome 44 ou superior

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

"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

1.000.000

MAX_WRITE_OPERATIONS_PER_HOUR

Descontinuado

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

Valor

1.000.000

Métodos

create()

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

Cria um favorito ou uma pasta sob o parentId especificado. Se o URL estiver ausente ou NULO, será uma pasta.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

get()

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

Recupera os FavoriteTreeNode(s) especificados.

Parâmetros

  • idOrIdList

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

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getChildren()

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

Recupera os filhos do ID FavoriteTreeNode especificado.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 esta aparência: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 da subárvore a ser recuperada.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getTree()

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

Recupera toda a hierarquia de favoritos.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

move()

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

Move o FavoriteTreeNode 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 esta aparência: 

    (result: BookmarkTreeNode) => void

Retorna

  • Promise<BookmarkTreeNode>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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

Pesquisa por FavoriteTreeNodes que correspondam à consulta especificada. As consultas especificadas com um objeto produzem FavoriteTreeNodes que correspondem 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 a um objeto. Se um objeto for um objeto, as propriedades query, url e title poderão ser especificadas, e favoritos correspondentes a todas as propriedades especificadas serão gerados.

    • consulta

      string opcional

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

    • título

      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 opcional

    O parâmetro callback tem esta aparência: 

    (results: BookmarkTreeNode[]) => void

Retorna

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

update()

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

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

Parâmetros

  • id

    string

  • muda

    objeto

    • título

      string opcional

    • url

      string opcional

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (result: BookmarkTreeNode) => void

Retorna

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onChanged

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

Disparado quando um favorito ou uma pasta é alterado. Observação:no momento, isso é acionado apenas por 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

      • título

        string

      • url

        string opcional

onChildrenReordered

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

Disparado quando os filhos de uma pasta mudaram de ordem devido à ordem de classificação na interface. Isso 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 caros precisam ignorar as atualizações onCreated até que onImportEnded seja acionado. Observadores ainda precisam 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

      • index

        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 é acionada para a pasta e nenhuma para o conteúdo.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • id

      string

    • removeInfo

      objeto