browser.bookmarks

Descrição

Use a API chrome.bookmarks para criar, organizar e manipular favoritos. Consulte também Páginas de substituição, que podem ser usadas para criar uma página personalizada do Gerenciador de favoritos.

Clique na estrela para adicionar 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 browser.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 mais informações 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.

browser.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 para desenvolvedores sobre extensões. Como nada de ruim vai acontecer se a criação do favorito falhar, esse código não se preocupa em definir uma função de callback.

browser.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 dentro da pasta mãe.

Propriedades

  • crianças

    BookmarkTreeNode[] opcional

    Uma lista ordenada de filhos desse nó.

  • dateAdded

    número optional

    Quando esse nó foi criado, em milissegundos desde o início (new Date(dateAdded)).

  • dateGroupModified

    número optional

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

  • dateLastUsed

    número optional

    Chrome 114+ browser.* desde o Chrome 148

    Quando este nó foi aberto pela última vez, em milissegundos desde o início. Não definido para pastas.

  • folderType

    FolderType opcional

    Chrome 134+ browser.* desde o Chrome 148

    Se estiver presente, essa é uma pasta adicionada pelo navegador que não pode ser modificada pelo usuário ou pela extensão. Os nós filhos poderão 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 de extensões.

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

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

  • parentId

    string opcional

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

  • sincronizando

    booleano

    Chrome 134+ browser.* desde o Chrome 148

    Se este nó é sincronizado com o armazenamento da conta remota do usuário pelo navegador. Isso pode ser usado para distinguir entre as versões da conta e as versões locais do mesmo FolderType. O valor dessa propriedade pode mudar para um nó atual, por exemplo, como resultado de uma ação do usuário.

    Observação: isso reflete se o nó foi salvo no provedor de contas 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

    "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 responsável 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+ browser.* desde o Chrome 148

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

"managed"

CreateDetails

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

Propriedades

  • índice

    número optional

  • parentId

    string opcional

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

  • título

    string opcional

  • url

    string opcional

FolderType

Chrome 134+ browser.* desde o Chrome 148

Indica o tipo de pasta.

Enumeração

"bookmarks-bar"
A pasta com o conteúdo que aparece na parte de cima da janela do navegador.

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

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

"managed"
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

ROOT_NODE_ID

Chrome 145+ browser.* desde o Chrome 148

O id associado ao nó de nível raiz.

Valor

"0"

Métodos

create()

browser.bookmarks.create(
  bookmark: CreateDetails,
): Promise<BookmarkTreeNode>

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

Parâmetros

Retorna

get()

browser.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
): Promise<BookmarkTreeNode[]>

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.

Retorna

getChildren()

browser.bookmarks.getChildren(
  id: string,
): Promise<BookmarkTreeNode[]>

Recupera os filhos do ID de BookmarkTreeNode especificado.

Parâmetros

  • ID

    string

Retorna

getRecent()

browser.bookmarks.getRecent(
  numberOfItems: number,
): Promise<BookmarkTreeNode[]>

Recupera os favoritos adicionados recentemente.

Parâmetros

  • numberOfItems

    número

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

Retorna

getSubTree()

browser.bookmarks.getSubTree(
  id: string,
): Promise<BookmarkTreeNode[]>

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.

Retorna

getTree()

browser.bookmarks.getTree(): Promise<BookmarkTreeNode[]>

Recupera toda a hierarquia de favoritos.

Retorna

move()

browser.bookmarks.move(
  id: string,
  destination: object,
): Promise<BookmarkTreeNode>

Move o BookmarkTreeNode especificado para o local fornecido.

Parâmetros

  • ID

    string

  • destino

    objeto

    • índice

      número optional

    • parentId

      string opcional

Retorna

remove()

browser.bookmarks.remove(
  id: string,
): Promise<void>

Remove um favorito ou uma pasta de favoritos vazia.

Parâmetros

  • ID

    string

Retorna

  • Promessa<void>

    Chrome 90+ browser.* desde o Chrome 148

removeTree()

browser.bookmarks.removeTree(
  id: string,
): Promise<void>

Remove recursivamente uma pasta de favoritos.

Parâmetros

  • ID

    string

Retorna

  • Promessa<void>

    Chrome 90+ browser.* desde o Chrome 148 
browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

Pesquisa BookmarkTreeNodes que correspondem à consulta fornecida. As consultas especificadas com um objeto produzem BookmarkTreeNodes 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 um objeto. Se for um objeto, as propriedades query, url e title poderão ser especificadas, e os favoritos que corresponderem 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.

    • título

      string opcional

      O título do favorito, que corresponde exatamente.

    • url

      string opcional

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

Retorna

update()

browser.bookmarks.update(
  id: string,
  changes: object,
): Promise<BookmarkTreeNode>

Atualiza as propriedades de um favorito ou de uma 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

Retorna

Eventos

onChanged

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

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

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

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

    • ID

      string

    • changeInfo

      objeto

      • título

        string

      • url

        string opcional

onChildrenReordered

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

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

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

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

    • ID

      string

    • reorderInfo

      objeto

      • childIds

        string[]

onCreated

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

Disparado quando um favorito ou uma pasta é criado.

Parâmetros

onImportBegan

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

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

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    () => void

onImportEnded

browser.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 é semelhante a: 

    () => void

onMoved

browser.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 é semelhante a: 

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

    • ID

      string

    • moveInfo

      objeto

      • índice

        número

      • oldIndex

        número

      • oldParentId

        string

      • parentId

        string

onRemoved

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

Disparado quando um favorito ou uma pasta é removido. 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 é semelhante a: 

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

    • ID

      string

    • removeInfo

      objeto

      • índice

        número

      • Chrome 48+ browser.* desde o Chrome 148
      • parentId

        string