chrome.bookmarks

Descripción

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

Al hacer clic en la estrella, se agrega un favorito
Cuando se hace clic en la estrella, se agrega un favorito.

Permisos

bookmarks

Para usar la API de favoritos, debes declarar el permiso "favoritos" en el manifiesto de 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 del árbol 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 forma opcional, las propiedades index, title y url del nodo. Consulta bookmarks.BookmarkTreeNode para obtener información acerca de 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 en create() especifica propiedades para 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);
  },
);

El siguiente fragmento crea un favorito que apunta a la documentación para desarrolladores sobre las extensiones. Dado que no ocurrirá 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 marcadores del repositorio chrome-extension-samples.

Tipos

BookmarkTreeNode

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

Propiedades

  • children

    BookmarkTreeNode[] opcional

    Una lista ordenada de los elementos secundarios de este nodo.

  • dateAdded

    número opcional

    Indica cuándo se creó este nodo, en milisegundos desde el ciclo de entrenamiento (new Date(dateAdded)).

  • dateGroupModified

    número opcional

    Indica cuándo se modificó por última vez el contenido de esta carpeta, en milisegundos desde el ciclo de entrenamiento.

  • dateLastUsed

    número opcional

    Chrome 114 y versiones posteriores

    Indica cuándo se abrió este nodo por última vez, en milisegundos desde el ciclo de entrenamiento. No se definió para carpetas.

  • id

    cadena

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

  • index

    número opcional

    La posición con base 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.

  • title

    cadena

    Es el texto que se muestra para el nodo.

  • no modificable

     opcional

    Indica el motivo por el que no se puede modificar este nodo. 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

    La URL a la que se navegó 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 no se puede modificar este nodo. 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

CreateDetails

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

Propiedades

  • index

    número opcional

  • parentId

    cadena opcional

    El valor predeterminado es la carpeta Otros favoritos.

  • title

    cadena opcional

  • url

    cadena opcional

Propiedades

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Obsoleto

Las operaciones de escritura de favoritos ya no están limitadas por Chrome.

Valor

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsoleto

Las operaciones de escritura de favoritos ya no están limitadas por Chrome.

Valor

1000000

Métodos

create()

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

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

Parámetros

Devuelve

  • Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 FavoriteTreeNode(s) especificados.

Parámetros

  • idOrIdList

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

    Un ID con valor de string único o un array de IDs con valores de cadena

  • callback

    Función opcional

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

    (results: BookmarkTreeNode[])=>void

Devuelve

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 FavoriteTreeNode especificado.

Parámetros

Devuelve

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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

Devuelve

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 a partir del nodo especificado.

Parámetros

  • id

    cadena

    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

Devuelve

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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

Devuelve

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 FavoriteTreeNode especificado a la ubicación proporcionada.

Parámetros

  • id

    cadena

  • destino

    objeto

    • index

      número opcional

    • parentId

      cadena opcional

  • callback

    Función opcional

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

    (result: BookmarkTreeNode)=>void

Devuelve

  • Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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,
)

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

Parámetros

  • id

    cadena

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 recurrente una carpeta de favoritos.

Parámetros

  • id

    cadena

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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,
)

Búsquedas de FavoriteTreeNodes que coinciden con la consulta dada. Las consultas especificadas con un objeto producen FavoriteTreeNodes que coinciden con todas las propiedades especificadas.

Parámetros

  • búsqueda

    cadena|objeto

    Puede ser una cadena de palabras y frases entre comillas que coincidan con las URLs y los títulos de favoritos, o un objeto. Si se utiliza un objeto, se pueden especificar las propiedades query, url y title, y se generan los favoritos que coincidan con todas las propiedades especificadas.

    • búsqueda

      cadena opcional

      Una cadena de palabras y frases entrecomilladas que coinciden con los títulos y las URLs de favoritos.

    • title

      cadena opcional

      El título del favorito; coincide textualmente.

    • url

      cadena opcional

      La URL del favorito; coincide textualmente. Ten en cuenta que las carpetas no tienen una URL.

  • callback

    Función opcional

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

    (results: BookmarkTreeNode[])=>void

Devuelve

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 quieres cambiar. Las propiedades que no se especifiquen no se modificarán. Nota: Actualmente, solo se admiten los atributos "title" y "url".

Parámetros

  • id

    cadena

  • Cambios

    objeto

    • title

      cadena opcional

    • url

      cadena opcional

  • callback

    Función opcional

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

    (result: BookmarkTreeNode)=>void

Devuelve

  • Chrome 90 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 un favorito o una carpeta cambian. Nota: Actualmente, solo los cambios en el título y la URL activan esta acción.

Parámetros

  • callback

    la función

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

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

    • id

      cadena

    • changeInfo

      objeto

      • title

        cadena

      • url

        cadena opcional

onChildrenReordered

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

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

Parámetros

  • callback

    la función

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

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

    • id

      cadena

    • reorderInfo

      objeto

      • childIds

        string[]

onCreated

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

Se activa cuando se crea un favorito o una carpeta.

Parámetros

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 activa onImportEnded. Los observadores aún deben manejar otras notificaciones de inmediato.

Parámetros

  • callback

    la función

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

    ()=>void

onImportEnded

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

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

Parámetros

  • callback

    la función

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

    ()=>void

onMoved

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

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

Parámetros

  • callback

    la función

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

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

    • id

      cadena

    • moveInfo

      objeto

      • index

        número

      • oldIndex

        número

      • oldParentId

        cadena

      • parentId

        cadena

onRemoved

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

Se activa cuando se quita un favorito o una carpeta. Cuando se quita una carpeta de manera recursiva, se envía una única notificación para la carpeta, pero ninguna para su contenido.

Parámetros

  • callback

    la función

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

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

    • id

      cadena

    • removeInfo

      objeto

      • index

        número

      • Chrome 48 y versiones posteriores
      • parentId

        cadena