chrome.bookmarks

Este permiso activa una advertencia.

Descripción

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

Permisos

bookmarks

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

Manifiesto

Debes declarar los "favoritos" permiso en el manifiesto de extensión para usar la API de favoritos. Por ejemplo:

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

Objetos y propiedades

Los favoritos están organizados en un árbol, donde cada nodo del árbol es un favorito o una carpeta. (a veces llamado grupo). Cada nodo del árbol está representado por una bookmarks.BookmarkTreeNode.

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

Ejemplos

El siguiente código crea una carpeta con el título "Favoritos de la extensión". El primer argumento para create() especifica las propiedades de la carpeta nueva. El segundo argumento define una función ejecutarse una vez creada 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 sobre las extensiones. Desde no pasará nada malo si falla la creación del marcador, este código no se molesta en definir un 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 Favoritos de chrome-extension-samples en un repositorio de confianza.

Tipos

BookmarkTreeNode

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

Propiedades

  • niños

    BookmarkTreeNode[] opcional

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

  • dateAdded

    número opcional

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

  • dateGroupModified

    número opcional

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

  • dateLastUsed

    número opcional

    Chrome 114 y versiones posteriores

    Cuándo se abrió este nodo por última vez, en milisegundos desde el ciclo de entrenamiento. No está configurado para 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.

  • index

    número opcional

    La posición con base 0 de este nodo dentro de su carpeta superior.

  • parentId

    string 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 modificable

    “administrado”
     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 (configuración predeterminada).

  • url

    string opcional

    Es 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 (configuración predeterminada).

Valor

“administrado”

CreateDetails

Objeto pasado a la función create().

Propiedades

  • index

    número opcional

  • parentId

    string opcional

    La configuración predeterminada es la carpeta Otros favoritos.

  • título

    string opcional

  • url

    string opcional

Propiedades

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

Obsoleto

Chrome ya no limita las operaciones de escritura de los favoritos.

Valor

1,000,000

MAX_WRITE_OPERATIONS_PER_HOUR

Obsoleto

Chrome ya no limita las operaciones de escritura de los favoritos.

Valor

1,000,000

Métodos

create()

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

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

Parámetros

Muestra

  • Promise<BookmarkTreeNode>

    Chrome 90 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

get()

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

Recupera los bookmarkTreeNode especificados.

Parámetros

  • idOrIdList

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

    Un solo ID con valor de cadena 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

Muestra

  • Promise<BookmarkTreeNode[]>

    Chrome 90 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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 solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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 solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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

    string

    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 solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones 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 solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

move()

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

Mueve el MarkerTreeNode especificado a la ubicación proporcionada.

Parámetros

  • id

    string

  • destino

    objeto

    • index

      número opcional

    • parentId

      string opcional

  • callback

    función opcional

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

    (result: BookmarkTreeNode) => void

Muestra

  • Promise<BookmarkTreeNode>

    Chrome 90 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

remove()

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

Elimina un marcador o una carpeta de marcadores vacía.

Parámetros

  • id

    string

  • callback

    función opcional

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

    () => void

Muestra

  • Promesa<void>

    Chrome 90 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

removeTree()

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

Elimina una carpeta de favoritos de forma recurrente.

Parámetros

  • id

    string

  • callback

    función opcional

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

    () => void

Muestra

  • Promesa<void>

    Chrome 90 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

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

Busca FavoriteTreeNodes que coincidan con la consulta dada. Las consultas especificadas con un objeto producirán bookmarkTreeNodes que coincidan con todas las propiedades especificadas.

Parámetros

  • consulta

    string | objeto

    Una cadena de palabras y frases entrecomilladas que se comparan con las URL y los títulos de los favoritos, o bien un objeto. Si se trata de un objeto, se pueden especificar las propiedades query, url y title, y se generarán favoritos que coincidan con todas las propiedades especificadas.

    • consulta

      string opcional

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

    • título

      string opcional

      el título del marcador. coincide literalmente.

    • url

      string opcional

      La URL del marcador coincide literalmente. 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&lt;BookmarkTreeNode[]&gt;

    Chrome 90 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

update()

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

Actualiza las propiedades de un favorito o de una carpeta. Especifica solo las propiedades que quieres cambiar. las propiedades no especificadas no se modificarán. Nota: Actualmente, solo se admite el término "título". y "url" compatibles.

Parámetros

  • id

    string

  • Cambios

    objeto

    • título

      string opcional

    • url

      string opcional

  • callback

    función opcional

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

    (result: BookmarkTreeNode) => void

Muestra

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

Eventos

onChanged

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

Se activa cuando cambia un favorito o una carpeta. Nota: Por el momento, solo se activan los cambios en el título y la URL.

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

        string opcional

onChildrenReordered

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

Se activa cuando los elementos secundarios de una carpeta cambian su orden debido a que se está ordenando en la IU. No se llama a este método como resultado de 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 comienza una sesión de importación de favoritos. Los observadores costosos deben ignorar las actualizaciones onCreated hasta que se active onImportEnded. De todos modos, los observadores deben manejar 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 un favorito o una carpeta se mueve 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

      • index

        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 una carpeta se quita de manera recursiva, se activa una sola notificación para ella, pero 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

      • index

        número

      • Chrome 48 y versiones posteriores
      • parentId

        string