NDEFReader: write() メソッド

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

write()NDEFReader インターフェイスのプロパティで、タグに NDEF メッセージを書き込むことを試みます。 Promise を返し、これはタグにメッセージが書き込まれると解決し、ハードウェアや権限のエラーが発生すると拒否されます。このメソッドは、 "nfc" の権限が事前に許可されていない場合は、許可を問い合わせるプロンプトを起動します。

構文

js
write(message)
write(message, options)

引数

message

書き込まれるメッセージで、文字列のオブジェクトまたはリテラル、ArrayBufferTypedArrayDataView、レコードの配列のいずれかです。レコードには以下のメンバーがあります。

data 省略可

通信されるデータで、文字列のオブジェクトまたはリテラル、ArrayBufferTypedArrayDataView、ネストされたレコードの配列のいずれかです。

encoding 省略可

文字列で、このレコードのエンコーディングを指定します。

id 省略可

このレコードの開発者が定義した識別子です。

lang 省略可

RFC 5646: Tags for Identifying Languages (または BCP 47)による有効な言語タグです。

mediaType 省略可

有効な MIME タイプです。

recordType

文字列で、 data に格納されたデータの型を示します。以下の値の何れかになります。

"absolute-url"

データへの絶対 URL です。

"empty"

空の NDEFRecord です。

"mime"

有効な MIME タイプです。

"smart-poster"

NDEF-SMARTPOSTER 仕様書で定義されているスマートポスターです。

"text"

NDEF-TEXT 仕様書で定義されているテキストです。

"unknown"

レコード型が不明です。

"URL"

NDEF-URI 仕様書で定義されている URL です。

options 省略可

以下のプロパティを持つオブジェクトです。

overwrite

既存のレコードが存在した場合、上書きするかどうかを指定する論理値です。

signal 省略可

オプションの AbortSignal で、現在の書き込み操作をキャンセルすることができます。

返値

Promise で、メッセージがタグに書き込まれたら解決し、ハードウェアまたは権限のエラーが発生した場合は拒否されます。

例外

このメソッドからは例外は発生しません。代わりに返されるプロミスが拒否され、 DOMExceptionname を何れかの一つとして渡されます。

AbortError

options 引数で渡された AbortSignal によってスキャン操作が中止された。

NotAllowedError

この操作の権限が拒否されたか、 overwritefalse であり、既にタグにそのレコードがあった。

NotSupportedError

ウェブ NFC と互換性のある NFC アダプターがない、または利用可能な NFC アダプターがプッシュメッセージに対応していない、または接続が確立できなかった。

NotReadableError

UA が接続されている NFC アラプターにアクセスできなかった(例えば、ユーザー設定のため)。

NetworkError

開始された後で転送に失敗した(例えば、タグがリーダーから取り外された)。

テキスト文字列の書き込み

以下の例では、文字列を NFC タグへ書き込み、発生するエラーを処理する方法を示します。

js
const ndef = new NDEFReader();
ndef
  .write("Hello World")
  .then(() => {
    console.log("Message written.");
  })
  .catch((error) => {
    console.log(`Write failed :-( try again: ${error}.`);
  });

URL の書き込み

次の例は、 NFC タグにレコードオブジェクト(上記)を書き込み、発生したエラーを処理する方法を示しています。

js
const ndef = new NDEFReader();
try {
  await ndef.write({
    records: [{ recordType: "url", data: "http://example.com/" }],
  });
} catch {
  console.log("Write failed :-( try again.");
}

タイムアウトで書き込みをスケジューリング

書き込み操作に時間制限を設けると便利な場合があります。例えば、ユーザーにタグをタッチするように要求し、一定時間内にタグが見つからなかったら、タイムアウトするようにします。

js
const ndef = new NDEFReader();
ndef.onreading = (event) => console.log("We read a tag!");

function write(data, { timeout } = {}) {
  return new Promise((resolve, reject) => {
    const ctlr = new AbortController();
    ctlr.signal.onabort = () => reject("Time is up, bailing out!");
    setTimeout(() => ctlr.abort(), timeout);

    ndef.addEventListener(
      "reading",
      (event) => {
        ndef.write(data, { signal: ctlr.signal }).then(resolve, reject);
      },
      { once: true },
    );
  });
}

await ndef.scan();
try {
  // Let's wait for 5 seconds only.
  await write("Hello World", { timeout: 5_000 });
} catch (err) {
  console.error("Something went wrong", err);
} finally {
  console.log("We wrote to a tag!");
}

仕様書

Specification
Web NFC API
# dom-ndefreader-write

ブラウザーの互換性

BCD tables only load in the browser