1. El proyecto MDN
  2. Pautas de redacción
  3. Estructuras de página
  4. Tipos de página
  5. Plantilla de subpágina de método de API

Esta página ha sido traducida del inglés por la comunidad. Aprende más y únete a la comunidad de MDN Web Docs.

View in English Always switch to English

Plantilla de subpágina de método de API

Nota: Elimina toda esta nota explicativa antes de publicar.

Front matter de la página:

El front matter en la parte superior de la página se usa para definir los "metadatos de la página". Actualiza los valores de forma adecuada para el método en cuestión.

md
---
title: NameOfTheParentInterface.NameOfTheMethod()
slug: Web/API/NameOfTheParentInterface/NameOfTheMethod
page-type: web-api-instance-method OR web-api-static-method
status:
  - deprecated
  - experimental
  - non-standard
browser-compat: path.to.feature.NameOfTheMethod
---
title

El título que se muestra en la parte superior de la página. Debe tener el formato "NameOfTheParentInterface: NameOfTheMethod() method". Por ejemplo, el método count() de la interfaz IDBIndex tiene como title IDBIndex: count() method.

slug

El final de la ruta URL después de https://developer.mozilla.org/es/docs/. Tendrá un formato como Web/API/NameOfTheParentInterface/NameOfTheMethod.

Si el método es estático, el slug debe llevar el sufijo _static, por ejemplo: Web/API/NameOfTheParentInterface/NameOfTheMethod_static. Esto nos permite admitir métodos de instancia y estáticos que tengan el mismo nombre.

Ten en cuenta que el nombre del método en el slug omite los paréntesis (termina en NameOfTheMethod, no en NameOfTheMethod()).

page-type

La clave page-type para métodos de Web/API es web-api-instance-method (para métodos de instancia) o web-api-static-method (para métodos estáticos).

status

Indicadores que describen el estado de esta característica. Un array que puede contener uno o más de los siguientes valores: experimental, deprecated, non-standard. Esta clave no debe establecerse manualmente: se establece automáticamente en función de los valores de los datos de compatibilidad del navegador para dicha característica. Consulta "Cómo se añaden o actualizan los estados de las características".

browser-compat

Reemplaza el marcador de posición path.to.feature.NameOfTheMethod con la cadena de consulta del método en el Repositorio de datos de compatibilidad del navegador. La cadena de herramientas usa automáticamente esta clave para completar las secciones de compatibilidad y especificaciones (sustituyendo las macros {{Compat}} y {{Specifications}}).

Ten en cuenta que primero puede que debas crear o actualizar una entrada para el método de la API en nuestro Repositorio de datos de compatibilidad del navegador, y la entrada para la API deberá incluir información de especificación. Consulta nuestra guía sobre cómo hacerlo.

Macros de la parte superior de la página

Varias llamadas a macros aparecen en la parte superior de la sección de contenido (justo debajo del front matter de la página).

La cadena de herramientas añade estas macros automáticamente (no es necesario añadirlas ni eliminarlas):

  • {{SeeCompatTable}}: genera un aviso de Esta es una tecnología experimental que indica que la tecnología es experimental. Si es experimental y la tecnología está oculta tras una preferencia (pref) en Firefox, también debes completar una entrada para ella en la página Funciones experimentales en Firefox.
  • {{Deprecated_Header}}: genera un aviso de Obsoleto que indica que se desaconseja el uso de la tecnología.
  • {{Non-standard_Header}}: genera un aviso de No estándar que indica que la característica no forma parte de ninguna especificación.

Actualiza o eliminar las siguientes macros según las indicaciones a continuación:

  • {{SecureContext_Header}}: genera un aviso de Contexto seguro que indica que la tecnología solo está disponible en un contexto seguro. Si no es así, puedes eliminar la llamada a la macro. Si es así, también debes completar una entrada para ella en la página Características restringidas a contextos seguros.
  • {{AvailableInWorkers}}: genera una nota de Disponible en workers que indica que la tecnología está disponible en un contexto de worker. Si solo está disponible en el contexto de ventana (window), puedes eliminar la llamada a la macro. Si también está disponible, o solo está disponible en el contexto de worker, es posible que también debas pasarle un parámetro debido a su disponibilidad (consulta el código fuente de la macro {{AvailableInWorkers}} para ver todos los valores disponibles); también es posible que debas completar una entrada para ella en la página Web API disponibles en workers.
  • {{APIRef("GroupDataName")}}: esto genera la barra lateral de referencia a la izquierda que muestra enlaces de referencia rápida relacionados con la página actual. Por ejemplo, todas las páginas de la WebVR API tienen la misma barra lateral, que apunta a las demás páginas de la API. Para generar la barra lateral correcta para tu API, debes añadir una entrada GroupData a nuestro repositorio de GitHub e incluir el nombre de esa entrada dentro de la llamada a la macro en lugar de GroupDataName. Consulta nuestra guía Barras laterales de referencia de API para obtener información sobre cómo hacerlo.

No añadas manualmente las macros de encabezado de estado. Consulta la sección "Cómo se añaden o actualizan los estados de las características" para añadir estos estados a la página.

Justo después de este bloque de nota se muestran ejemplos de los avisos de Contexto seguro, Disponible en workers, Experimental, Obsoleto y No estándar.

Recuerda eliminar toda esta nota explicativa antes de publicar.

Contexto seguro: Esta función está disponible solo en contextos seguros (HTTPS), en algunos o todos los navegadores que lo soportan.

Nota: Esta característica está disponible en Web Workers.

Experimental: Esta es una tecnología experimental
Comprueba la Tabla de compabilidad de navegadores cuidadosamente antes de usarla en producción.

Obsoleto: Esta característica ya no se recomienda. Aunque es posible que algunos navegadores aún lo admitan, probablemente ya se ha eliminado de los estándares web relevantes, está en proceso de eliminación o solo se conserva por motivos de compatibilidad. Evite usarlo y actualice el código existente si es posible; consulte la tabla de compatibilidad en la parte inferior de esta página para orientar su decisión. Tenga en cuenta que esta característica puede dejar de funcionar en cualquier momento.

No estándar: Esta función no está estandarizada. No recomendamos usar funciones no estándar en producción, ya que tienen un soporte limitado en los navegadores y pueden cambiar o eliminarse. Sin embargo, pueden ser una alternativa adecuada en casos específicos donde no exista una opción estándar.

Comienza el contenido de la página con un párrafo introductorio: empieza nombrando el método, indicando a qué interfaz pertenece y explicando qué hace. Lo ideal es que sean una o dos frases breves. Puedes copiar la mayor parte de este texto del resumen del método en la página de referencia de la API correspondiente.

Sintaxis

Completa un cuadro de sintaxis según las indicaciones de nuestro artículo sobre secciones de sintaxis.

Parámetros

parameter1 Opcional

Incluye aquí una breve descripción del parámetro y de lo que hace. Incluye un término y una definición para cada parámetro. Si el parámetro no es opcional, elimina la llamada a la macro {{optional_inline}}.

parameter2

etc.

Nota: Esta sección es obligatoria. Si no hay parámetros, escribe Ninguno. en lugar de la lista de definiciones.

Valor de retorno

Incluye una descripción del valor de retorno del método, incluyendo el tipo de dato y qué representa.

Si el método no devuelve nada, simplemente escribe "Ninguno (undefined)".

Excepciones

Incluye una lista de todas las excepciones que el método puede generar. Incluye un término y una definición para cada excepción.

Exception1

Incluye una descripción de cómo se genera la excepción.

Exception2

Incluye una descripción de cómo se genera la excepción.

Ten en cuenta que hay dos tipos de excepciones: objetos DOMException y excepciones normales de JavaScript, como TypeError y RangeError. Un desarrollador web necesita saber:

  • qué objeto se lanza
  • para las excepciones que son objetos DOMException, el name de la excepción.

Aquí hay un ejemplo donde un método puede generar una DOMException con el nombre IndexSizeError, una segunda DOMException con el nombre InvalidNodeTypeError y una excepción de JavaScript de tipo TypeError:

IndexSizeError DOMException

Lanzada…

InvalidNodeTypeError DOMException

Lanzada…

TypeError

Lanzada…

Descripción

Descripción detallada de cómo se comporta el método Sección omitida si un párrafo introductorio (o dos) en la parte superior de la página es suficiente.

Ejemplos

Ten en cuenta que usamos el plural "Ejemplos" aunque la página contenga un único ejemplo.

Un encabezado descriptivo

Cada ejemplo debe tener un encabezado H3 que lo identifique. El encabezado debe describir qué hace el ejemplo. Por ejemplo, "Un ejemplo sencillo" no dice nada sobre el ejemplo y, por lo tanto, no es un buen encabezado. El encabezado debe ser conciso. Para una descripción más larga, usa el párrafo que sigue al encabezado.

Consulta nuestra guía sobre cómo añadir ejemplos de código para más información.

Nota: A veces querrás enlazar a ejemplos que están en otra página.

Escenario 1: Si tienes algunos ejemplos en esta página y otros más en otra página:

Incluye un encabezado H3 (###) para cada ejemplo de esta página y, al final, un último encabezado H3 (###) con el texto "Más ejemplos", bajo el cual puedes enlazar a los ejemplos de otras páginas. Por ejemplo:

md
## Examples

### Using the fetch API

Example of Fetch

### More examples

Links to more examples on other pages

Escenario 2: Si solo tienes ejemplos en otra página y ninguno en esta:

No añadas ningún encabezado H3; simplemente añade los enlaces directamente debajo del encabezado H2 "Examples". Por ejemplo:

md
## Examples

For examples of this API, see [the page on fetch()](https://example.org/).

Especificaciones

{{Specifications}}

Para usar esta macro, elimina las comillas invertidas y la barra invertida del archivo Markdown.

Compatibilidad con navegadores

{{Compat}}

Para usar esta macro, elimina las comillas invertidas y la barra invertida del archivo Markdown.

Véase también

Incluye enlaces a páginas de referencia y guías relacionadas con la API actual. Para más pautas, consulta la sección Véase también en la Guía de estilo de redacción.

  • enlace1
  • enlace2
  • enlace_externo (año)

Help improve MDN

Learn how to contribute

This page was last modified on by MDN contributors.

View this page on GitHub • Report a problem with this content