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
É necessário declarar a permissão "bookmarks" no manifesto de extensões 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 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 recenteQuando 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
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
As operações de gravação de favoritos não são mais limitadas pelo Chrome.
Valor
1000.000
MAX_WRITE_OPERATIONS_PER_HOUR
As operações de gravação de favoritos não são mais limitadas pelo Chrome.
Valor
1000.000
Métodos
create()
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
-
favorito
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: BookmarkTreeNode) => void
-
resultado
-
Retorna
-
Promise<BookmarkTreeNode>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
get()
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
-
resultados
-
Retorna
-
Promise<BookmarkTreeNode[]>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getChildren()
chrome.bookmarks.getChildren(
id: string,
callback?: function,
)
Recupera os filhos do ID FavoriteTreeNode especificado.
Parâmetros
-
id
string
-
callback
função optional
O parâmetro
callback
tem esta aparência:(results: BookmarkTreeNode[]) => void
-
resultados
-
Retorna
-
Promise<BookmarkTreeNode[]>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getRecent()
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
-
resultados
-
Retorna
-
Promise<BookmarkTreeNode[]>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getSubTree()
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
-
resultados
-
Retorna
-
Promise<BookmarkTreeNode[]>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getTree()
chrome.bookmarks.getTree(
callback?: function,
)
Recupera toda a hierarquia dos Favoritos.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(results: BookmarkTreeNode[]) => void
-
resultados
-
Retorna
-
Promise<BookmarkTreeNode[]>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
move()
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
-
resultado
-
Retorna
-
Promise<BookmarkTreeNode>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
remove()
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 recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
removeTree()
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 recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
search()
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
etitle
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
-
resultados
-
Retorna
-
Promise<BookmarkTreeNode[]>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
update()
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
-
resultado
-
Retorna
-
Promise<BookmarkTreeNode>
Chrome 90 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
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
-
callback
função
O parâmetro
callback
tem esta aparência:(id: string, bookmark: BookmarkTreeNode) => void
-
id
string
-
favorito
-
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
-
índice
number
-
Chrome 48 ou mais recente
-
parentId
string
-
-