browser.bookmarks

Descripción

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

Si haces clic en la estrella, se agrega un favorito.

Permisos

bookmarks

Debes declarar el permiso "bookmarks" en el manifiesto de la extensión para usar la API de favoritos. 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, se denomina grupo). Cada nodo del árbol se representa con un objeto bookmarks.BookmarkTreeNode.

Las propiedades de BookmarkTreeNode se usan en toda la API de browser.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.

Nota: No puedes usar esta API para agregar o quitar entradas en la carpeta raíz. Tampoco puedes cambiar el nombre, mover ni quitar las carpetas especiales "Barra de favoritos" y "Otros favoritos".

Ejemplos

El siguiente código crea una carpeta con el título "Marcadores de 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 que se cree la carpeta.

browser.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 apunta a la documentación para desarrolladores de extensiones. Como no ocurrirá nada malo si falla la creación del marcador, este código no se molesta en definir una función de devolución de llamada.

browser.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

  number opcional

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

• dateGroupModified

  number opcional

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

• dateLastUsed

  number opcional

  Chrome 114 y versiones posteriores browser.* desde Chrome 148

  Indica cuándo se abrió este nodo por última vez, en milisegundos desde la época. No se establece para las carpetas.

• folderType

  FolderType opcional

  Chrome 134 y versiones posteriores browser.* desde Chrome 148

  Si está presente, se trata de una carpeta que agrega el navegador y que el usuario o la extensión no pueden modificar. Los nodos secundarios se pueden modificar si este nodo no tiene establecida la propiedad unmodifiable. Se omite si el usuario y la extensión pueden modificar el nodo (predeterminado).

  Puede haber cero, uno o varios nodos de cada tipo de carpeta. El navegador puede agregar o quitar una carpeta, pero no a través de la API de extensiones.

• 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

  number opcional

  Es la posición basada en 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.

• sincronizando

  booleano

  Chrome 134 y versiones posteriores browser.* desde Chrome 148

  Indica si el navegador sincroniza este nodo con el almacenamiento de la cuenta remota del usuario. Esto se puede usar para distinguir entre las versiones de la cuenta y las versiones solo locales del mismo FolderType. El valor de esta propiedad puede cambiar para un nodo existente, por ejemplo, como resultado de una acción del usuario.

  Nota: Esto refleja si el nodo se guarda en el proveedor de cuentas integrado del navegador. Es posible que un nodo se sincronice a través de un tercero, incluso si este valor es falso.

  Para los nodos administrados (nodos en los que unmodifiable se establece en true), esta propiedad siempre será false.

• título

  string

  Es el texto que se muestra para el nodo.

• no modificable

  "managed"
   opcional

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

• url

  string 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 browser.* desde Chrome 148

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

"managed"

CreateDetails

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

Propiedades

• índice

  number opcional

• parentId

  string opcional

  La opción predeterminada es la carpeta Otros favoritos.

• título

  string opcional

• url

  string opcional

FolderType

Chrome 134 y versiones posteriores browser.* desde Chrome 148

Indica el tipo de carpeta.

Enum

"bookmarks-bar"
La carpeta cuyo contenido se muestra en la parte superior de la ventana del navegador.

"other"
Favoritos que se muestran en la lista completa de favoritos en todas las plataformas.

"mobile"
Favoritos que suelen estar disponibles en los dispositivos móviles del usuario, pero que se pueden modificar por extensión o en el administrador de favoritos.

"managed"
Es una carpeta de nivel superior que puede estar presente si el administrador del sistema o el tutor de un usuario supervisado configuraron favoritos.

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

ROOT_NODE_ID

Chrome 145 y versiones posteriores browser.* desde Chrome 148

Es el id asociado con el nodo de nivel raíz.

Valor

"0"

Métodos

create()

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

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

Parámetros

• favorito

  CreateDetails

Muestra

• Promise<BookmarkTreeNode>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

get()

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

Recupera los BookmarkTreeNode especificados.

Parámetros

• idOrIdList

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

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

Muestra

• Promise<BookmarkTreeNode[]>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

getChildren()

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

Recupera los elementos secundarios del ID de BookmarkTreeNode especificado.

Parámetros

• id

  string

Muestra

• Promise<BookmarkTreeNode[]>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

getRecent()

browser.bookmarks.getRecent(
  numberOfItems: number,
): Promise<BookmarkTreeNode[]>

Recupera los favoritos agregados recientemente.

Parámetros

• numberOfItems

  número

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

Muestra

• Promise<BookmarkTreeNode[]>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

getSubTree()

browser.bookmarks.getSubTree(
  id: string,
): Promise<BookmarkTreeNode[]>

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á.

Muestra

• Promise<BookmarkTreeNode[]>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

getTree()

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

Recupera toda la jerarquía de favoritos.

Muestra

• Promise<BookmarkTreeNode[]>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

move()

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

Mueve el BookmarkTreeNode especificado a la ubicación proporcionada.

Parámetros

• id

  string

• destino

  objeto

  • índice

    number opcional

  • parentId

    string opcional

Muestra

• Promise<BookmarkTreeNode>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

remove()

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

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

Parámetros

• id

  string

Muestra

• Promise<void>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

removeTree()

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

Quita de forma recurrente una carpeta de favoritos.

Parámetros

• id

  string

Muestra

• Promise<void>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

search()

browser.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

Parámetros

• consulta

  string | object

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

  • consulta

    string 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

    string opcional

    Es el título del marcador; coincide de forma literal.

  • url

    string opcional

    Es la URL del favorito; coincide de forma literal. Ten en cuenta que las carpetas no tienen URL.

Muestra

• Promise<BookmarkTreeNode[]>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

update()

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

Actualiza las propiedades de un marcador o una carpeta. Especifica solo las propiedades que quieras cambiar; las propiedades no especificadas no se modificarán. Nota: Por el momento, solo se admiten "title" y "url".

Parámetros

• id

  string

• Cambios

  objeto

  • título

    string opcional

  • url

    string opcional

Muestra

• Promise<BookmarkTreeNode>

  Chrome 90 y versiones posteriores browser.* desde Chrome 148

Eventos

onChanged

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

Se activa cuando cambia un marcador o una carpeta. Nota: Actualmente, solo los cambios de título y URL activan esta funció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

      string opcional

onChildrenReordered

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

Se activa cuando los elementos secundarios de una carpeta cambiaron su orden debido a que se ordenaron 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

browser.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

  • id

    string

  • favorito

    BookmarkTreeNode

onImportBegan

browser.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 seguir gestionando otras notificaciones de inmediato.

Parámetros

• callback

  función

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

  () => void

onImportEnded

browser.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

browser.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

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

Se activa cuando se quita un marcador o una carpeta. Cuando se quita una carpeta de forma recurrente, 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

    • nodo

      BookmarkTreeNode

      Chrome 48 y versiones posteriores browser.* desde Chrome 148
    • parentId

      string