chrome.bookmarks

Descripción

Usa la API de chrome.bookmarks para crear, organizar y manipular favoritos. Consulta también Anulaciones de páginas, que puedes usar para crear una página personalizada del Administrador de favoritos.

Si haces clic en la estrella, se agregará un favorito.
Si haces clic en la estrella, se agregará un favorito.

Permisos

bookmarks

Para usar la API de favoritos, debes declarar el permiso "favoritos" en el manifiesto de la extensión. Por ejemplo:

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

Conceptos y uso

Objetos y propiedades

Los favoritos se organizan en un árbol, en el que cada nodo es un favorito o una carpeta (a veces llamada grupo). Cada nodo del árbol está representado por un objeto bookmarks.BookmarkTreeNode.

Las propiedades BookmarkTreeNode se usan en toda la API de chrome.bookmarks. Por ejemplo, cuando llamas a bookmarks.create, pasas el elemento superior del nodo nuevo (parentId) y, de manera opcional, las propiedades index, title y url del nodo. Consulta bookmarks.BookmarkTreeNode para obtener información sobre las propiedades que puede tener un nodo.

Ejemplos

Con el siguiente código, se crea una carpeta con el título "Favoritos de la extensión". El primer argumento de create() especifica las propiedades de la carpeta nueva. El segundo argumento define una función que se ejecutará después de crear la carpeta.

chrome.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

En el siguiente fragmento, se crea un favorito que dirige a la documentación para desarrolladores de extensiones. Como no sucederá nada malo si falla la creación del favorito, este código no se molesta en definir una función de devolución de llamada.

chrome.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

Para probar esta API, instala el ejemplo de la API de Bookmarks desde el repositorio chrome-extension-samples.

Tipos

BookmarkTreeNode

Un nodo (un favorito o una carpeta) en el árbol de favoritos. Los nodos secundarios se ordenan dentro de su carpeta superior.

Propiedades

  • niños

    BookmarkTreeNode[] opcional

    Es una lista ordenada de los elementos secundarios de este nodo.

  • dateAdded

    número opcional

    Indica cuándo se creó este nodo, en milisegundos desde la época (new Date(dateAdded)).

  • dateGroupModified

    número opcional

    Es la última vez que se modificó el contenido de esta carpeta, en milisegundos desde la época.

  • dateLastUsed

    número opcional

    Chrome 114 y versiones posteriores

    La última vez que se abrió este nodo, en milisegundos desde la época. No se configuró para las carpetas.

  • id

    string

    Es el identificador único del nodo. Los IDs son únicos dentro del perfil actual y siguen siendo válidos incluso después de reiniciar el navegador.

  • índice

    número opcional

    Es la posición basada en 0 de este nodo dentro de su carpeta superior.

  • parentId

    cadena opcional

    El id de la carpeta superior. Se omite para el nodo raíz.

  • título

    string

    Es el texto que se muestra para el nodo.

  • no se puede modificar

    "managed"
     opcional

    Indica el motivo por el que este nodo no se puede modificar. El valor managed indica que el administrador del sistema o el custodio de un usuario supervisado configuró este nodo. Se omite si el usuario y la extensión pueden modificar el nodo (predeterminado).

  • url

    cadena opcional

    Es la URL a la que se navega cuando un usuario hace clic en el favorito. Se omite para las carpetas.

BookmarkTreeNodeUnmodifiable

Chrome 44 y versiones posteriores

Indica el motivo por el que este nodo no se puede modificar. El valor managed indica que el administrador del sistema configuró este nodo. Se omite si el usuario y la extensión pueden modificar el nodo (predeterminado).

Valor

"administrado"

CreateDetails

Es el objeto que se pasa a la función create().

Propiedades

  • índice

    número opcional

  • parentId

    cadena opcional

    La opción predeterminada es la carpeta Otros favoritos.

  • título

    cadena opcional

  • url

    cadena opcional

Propiedades

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Obsoleto

Chrome ya no limita las operaciones de escritura de favoritos.

Valor

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsoleto

Chrome ya no limita las operaciones de escritura de favoritos.

Valor

1000000

Métodos

create()

Promesa 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

Crea un favorito o una carpeta con el parentId especificado. Si la URL es NULL o falta, será una carpeta.

Parámetros

Muestra

  • Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

get()

Promesa 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

Recupera los BookmarkTreeNode especificados.

Parámetros

  • idOrIdList

    cadena | [cadena, ...cadena[]]

    Un solo ID con valor de cadena o un array de IDs con valor de cadena

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (results: BookmarkTreeNode[]) => void

Muestra

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getChildren()

Promesa 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

Recupera los elementos secundarios del ID de BookmarkTreeNode especificado.

Parámetros

  • id

    string

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (results: BookmarkTreeNode[]) => void

Muestra

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getRecent()

Promesa 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

Recupera los favoritos agregados recientemente.

Parámetros

  • numberOfItems

    número

    La cantidad máxima de elementos que se mostrarán.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (results: BookmarkTreeNode[]) => void

Muestra

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getSubTree()

Promesa 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

Recupera parte de la jerarquía de favoritos, comenzando en el nodo especificado.

Parámetros

  • id

    string

    Es el ID de la raíz del subárbol que se recuperará.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (results: BookmarkTreeNode[]) => void

Muestra

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getTree()

Promesa 
chrome.bookmarks.getTree(
  callback?: function,
)

Recupera toda la jerarquía de favoritos.

Parámetros

Muestra

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

move()

Promesa 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

Mueve el BookmarkTreeNode especificado a la ubicación proporcionada.

Parámetros

  • id

    string

  • destino

    objeto

    • índice

      número opcional

    • parentId

      cadena opcional

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: BookmarkTreeNode) => void

Muestra

  • Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

remove()

Promesa 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

Quita un favorito o una carpeta de favoritos vacía.

Parámetros

  • id

    string

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

removeTree()

Promesa 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

Quita de forma recursiva una carpeta de favoritos.

Parámetros

  • id

    string

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Promesa 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

Busca BookmarkTreeNodes que coincidan con la consulta determinada. Las consultas especificadas con un objeto producen BookmarkTreeNodes que coinciden con todas las propiedades especificadas.

Parámetros

  • consulta

    cadena | objeto

    Es una cadena de palabras y frases entrecomilladas que coinciden con las URLs y los títulos de los favoritos, o un objeto. Si es un objeto, se pueden especificar las propiedades query, url y title, y se generarán favoritos que coincidan con todas las propiedades especificadas.

    • consulta

      cadena opcional

      Es una cadena de palabras y frases entre comillas que se comparan con las URLs y los títulos de los favoritos.

    • título

      cadena opcional

      Es el título del favorito. Se hace una búsqueda exacta.

    • url

      cadena opcional

      Es la URL del favorito. Debe coincidir exactamente. Ten en cuenta que las carpetas no tienen URL.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (results: BookmarkTreeNode[]) => void

Muestra

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

update()

Promesa 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

Actualiza las propiedades de un favorito o una carpeta. Especifica solo las propiedades que deseas cambiar. Las propiedades no especificadas no se modificarán. Nota: Actualmente, solo se admiten "title" y "url".

Parámetros

  • id

    string

  • Cambios

    objeto

    • título

      cadena opcional

    • url

      cadena opcional

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: BookmarkTreeNode) => void

Muestra

  • Chrome 90 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onChanged

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

Se activa cuando cambia un favorito o una carpeta. Nota: Actualmente, solo los cambios en el título y la URL activan esta acción.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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

    • id

      string

    • changeInfo

      objeto

      • título

        string

      • url

        cadena opcional

onChildrenReordered

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

Se activa cuando los elementos secundarios de una carpeta cambian de orden debido a que se ordenan en la IU. No se llama como resultado de un move().

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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

    • id

      string

    • reorderInfo

      objeto

      • childIds

        string[]

onCreated

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

Se activa cuando se crea un favorito o una carpeta.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (id: string, bookmark: BookmarkTreeNode) => void

onImportBegan

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

Se activa cuando se inicia una sesión de importación de favoritos. Los observadores costosos deben ignorar las actualizaciones de onCreated hasta que se active onImportEnded. Los observadores deben controlar otras notificaciones de inmediato.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void

onImportEnded

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

Se activa cuando finaliza una sesión de importación de favoritos.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void

onMoved

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

Se activa cuando se mueve un favorito o una carpeta a una carpeta superior diferente.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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

    • id

      string

    • moveInfo

      objeto

      • índice

        número

      • oldIndex

        número

      • oldParentId

        string

      • parentId

        string

onRemoved

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

Se activa cuando se quita un favorito o una carpeta. Cuando se quita una carpeta de forma recursiva, se activa una sola notificación para la carpeta y ninguna para su contenido.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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

    • id

      string

    • removeInfo

      objeto

      • índice

        número

      • Chrome 48 y versiones posteriores
      • parentId

        string