chrome.bookmarks

Essa permissão aciona um aviso.

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.

Permissões

bookmarks

Clicar na estrela adiciona um favorito

Manifesto

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

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

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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