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 marcador
Clicar na estrela adiciona um favorito.

Permissões

bookmarks

Você precisa declarar a permissão "bookmarks" no manifesto da extensão para usar a API Bookmarks. 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 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 de create() especifica propriedades para a nova pasta. O segundo argumento define uma função a ser executada depois que a pasta é criada.

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 de extensões. Como nada de ruim vai acontecer se a criação do marcador falhar, esse código não se preocupa em 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 no repositório chrome-extension-samples (link em inglês).

Tipos

BookmarkTreeNode

Um nó (um favorito ou uma pasta) na árvore de favoritos. Os nós filhos são ordenados na pasta principal.

Propriedades

  • crianças

    BookmarkTreeNode[] opcional

    Uma lista ordenada de filhos deste nó.

  • dateAdded

    number optional

    Quando este nó foi criado, em milissegundos desde o período (new Date(dateAdded)).

  • dateGroupModified

    number optional

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

  • dateLastUsed

    number optional

    Chrome 114 ou mais recente

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

  • folderType

    FolderType opcional

    Chrome 134 ou mais recente

    Se 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 o 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 depois que o navegador é reiniciado.

  • index

    number optional

    A posição baseada em zero deste nó na pasta mãe.

  • parentId

    string opcional

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

  • sincronizando

    booleano

    Chrome 134 ou mais recente

    Se este nó é sincronizado com o armazenamento remoto da conta do usuário pelo navegador. Isso pode ser usado para distinguir entre versões da conta e somente locais 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ó está salvo no provedor de contas integrado do navegador. É possível que um nó seja sincronizado por terceiros, mesmo que esse valor seja "false".

    Para nós gerenciados (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"
     optional

    Indica o motivo pelo qual este 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 para onde o usuário é direcionado quando clica no marcador. Omitido para pastas.

BookmarkTreeNodeUnmodifiable

Chrome 44 ou mais recente

Indica o motivo pelo qual este 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 à função create().

Propriedades

  • index

    number optional

  • parentId

    string opcional

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

  • título

    string opcional

  • url

    string opcional

FolderType

Chrome 134 ou mais recente

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 em todas as plataformas.

"mobile"
Os favoritos geralmente estão disponíveis nos dispositivos móveis do usuário, mas 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 os 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()

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

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

Parâmetros

Retorna

get()

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

Recupera os BookmarkTreeNode(s) 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()

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

Recupera os filhos do ID BookmarkTreeNode especificado.

Parâmetros

  • ID

    string

Retorna

getRecent()

chrome.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()

chrome.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()

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

Recupera toda a hierarquia de favoritos.

Retorna

move()

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

Move o BookmarkTreeNode especificado para o local fornecido.

Parâmetros

  • ID

    string

  • destino

    objeto

    • index

      number optional

    • parentId

      string opcional

Retorna

remove()

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

Remove um favorito ou uma pasta de favoritos vazia.

Parâmetros

  • ID

    string

Retorna

  • Promise<void>

    Chrome 90 ou mais recente

removeTree()

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

Remove recursivamente uma pasta de favoritos.

Parâmetros

  • ID

    string

Retorna

  • Promise<void>

    Chrome 90 ou mais recente 
chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

Pesquisa 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 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 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 do marcador, que precisa ser idêntico.

    • url

      string opcional

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

Retorna

update()

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

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

Parâmetros

  • ID

    string

  • muda

    objeto

    • título

      string opcional

    • url

      string opcional

Retorna

Eventos

onChanged

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

Acionado quando um favorito ou uma 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 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 a ordem dos filhos de uma pasta muda porque a ordem está sendo classificada 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,
)

Acionado quando um favorito ou uma pasta é criada.

Parâmetros

onImportBegan

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

Disparado quando uma sessão de importação de favoritos é iniciada. Observadores caros devem ignorar 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 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 outra pasta mãe.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

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

    • ID

      string

    • removeInfo

      objeto