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 usada 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 "favoritos" no manifesto da extensão para usar a API de favoritos. 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 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, quando você chama 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 propriedades para a 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.

  • folderType

    FolderType opcional

    Pendente

    Se estiver presente, é uma pasta adicionada pelo navegador e que não pode ser modificada pelo usuário ou pela extensão. Os nós filhos podem ser modificados se esse nó não tiver a propriedade unmodifiable definida. Omitido se o nó puder ser modificado pelo usuário e pela extensão (padrão).

    Pode haver zero, um ou vários nós de cada tipo de pasta. Uma pasta pode ser adicionada ou removida pelo navegador, mas não pela API Extensions.

  • 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.

  • sincronizando

    booleano

    Pendente

    Indica se o navegador sincroniza esse nó com o armazenamento remoto da conta do usuário. Isso pode ser usado para distinguir entre as versões da conta e somente local do mesmo FolderType. O valor dessa propriedade pode mudar para um nó existente, por exemplo, como resultado de uma ação do usuário.

    Observação: isso reflete se o nó é salvo no provedor de conta integrado do navegador. É possível que um nó seja sincronizado por terceiros, mesmo que esse valor seja falso.

    Para nós gerenciados (nós em que unmodifiable está definido como true), essa propriedade sempre será false.

  • título

    string

    O texto exibido para o nó.

  • não modificável

    "gerenciado"
     opcional

    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

FolderType

Pendente

Indica o tipo de pasta.

Enumeração

"bookmarks-bar"
A pasta cujo conteúdo é exibido na parte de cima da janela do navegador.

"Outros"
Favoritos que aparecem na lista completa de favoritos em todas as plataformas.

"mobile"
Marcadores geralmente disponíveis nos dispositivos móveis do usuário, mas que podem ser modificados por extensão ou no gerenciador de favoritos.

"gerenciada"
Uma pasta de nível superior que pode estar presente se o administrador do sistema ou o responsável por um usuário supervisionado tiver configurado favoritos.

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 apenas para 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 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 apenas para 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 do BookmarkTreeNode especificado.

Parâmetros

Retorna

  • Promise<BookmarkTreeNode[]>

    Chrome 90 e versões mais recentes

    As promessas têm suporte apenas para 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

    número

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

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 apenas para 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 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 apenas para 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 opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 90 e versões mais recentes

    As promessas têm suporte apenas para 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 opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 90 e versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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

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

        número

      • oldIndex

        número

      • oldParentId

        string

      • parentId

        string

onRemoved

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

Acionado quando uma favorita 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

        número

      • Chrome 48 e versões mais recentes
      • parentId

        string