From 1d80e530ffbd2b724423da659481716b3d08034c Mon Sep 17 00:00:00 2001 From: yyss Date: Sat, 12 Oct 2024 23:49:56 +0900 Subject: [PATCH 001/221] =?UTF-8?q?Oct=202,=202024=E3=81=AE=E8=8B=B1?= =?UTF-8?q?=E8=AA=9E=E7=89=88=E3=81=AB=E5=AF=BE=E5=BF=9C=20(#23915)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Firefox 131 for developersを翻訳 Oct 2, 2024の英語版に対応。 * Update index.md --------- Co-authored-by: Masahiro FUJIMOTO --- .../ja/mozilla/firefox/releases/131/index.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 files/ja/mozilla/firefox/releases/131/index.md diff --git a/files/ja/mozilla/firefox/releases/131/index.md b/files/ja/mozilla/firefox/releases/131/index.md new file mode 100644 index 00000000000000..7c99ef40e09472 --- /dev/null +++ b/files/ja/mozilla/firefox/releases/131/index.md @@ -0,0 +1,75 @@ +--- +title: Firefox 131 for developers +slug: Mozilla/Firefox/Releases/131 +l10n: + sourceCommit: d27be65a297aa82a1eceb024be325b1385a498e5 +--- + +{{FirefoxSidebar}} + +このページでは、開発者に影響する Firefox 131 の変更点をまとめています。Firefox 131 は、米国時間 [2024 年 10 月 1 日](https://whattrainisitnow.com/release/?version=129) にリリースされました。 + +## ウェブ開発者向けの変更点一覧 + +### CSS + +- [Anchor Positioning](/ja/docs/Web/CSS/CSS_anchor_positioning) のさらなる実装の準備として、`inset-area` CSS プロパティを {{CSSXRef("position-area")}} に改名しました。現在、このプロパティは値を解析するために内部で使用するのみです。Anchor Positioning の機能は、設定で制御した上で順次ロールアウトしています。詳しくは [Firefox における実験的機能: CSS Anchor Positioning](/ja/docs/Mozilla/Firefox/Experimental_features#css_anchor_positioning) をご覧ください ([Firefox bug 1909358](https://bugzil.la/1909358)、[Firefox bug 1838746](https://bugzil.la/1838746))。 + +### JavaScript + +- {{jsxref("Iterator.prototype.drop()")}}、{{jsxref("Iterator.prototype.every()")}}、{{jsxref("Iterator.prototype.filter()")}}、{{jsxref("Iterator.prototype.find()")}}、{{jsxref("Iterator.prototype.flatMap()")}}、{{jsxref("Iterator.prototype.forEach()")}}、{{jsxref("Iterator.prototype.map()")}}、{{jsxref("Iterator.prototype.reduce()")}}、{{jsxref("Iterator.prototype.some()")}}、{{jsxref("Iterator.prototype.take()")}} を含む、同期イテレーターヘルパーをサポートしました。これらのヘルパーは、中間的な `Array` オブジェクトを作成する必要なくイテレーターで `Array` のような操作を可能にします。また、中間的な `Array` を作成できない大量のデータセットでも使用できます。詳しくは `Iterator` インターフェイスの [Iterator helpers](/ja/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helpers) をご覧ください ([Firefox bug 1896390](https://bugzil.la/1896390))。 + +### HTTP + +- [`SameSite=None`](/ja/docs/Web/HTTP/Headers/Set-Cookie#none) の属性値を持つ {{httpheader("Set-Cookie")}} HTTP ヘッダーは、[`Secure`](/ja/docs/Web/HTTP/Headers/Set-Cookie#secure) 属性も持つことが必要になりました。これは、`SameSite=None` を設定した Cookie が HTTPS 接続だけで送信されることを保証します。また、Firefox は値が不特定な `SameSite` を `SameSite=None` とみなすため、`SameSite` を指定していない Cookie も同じ制約があります ([Firefox bug 1909673](https://bugzil.la/1909673))。 +- [Cookies Having Independent Partitioned State (CHIPS)](/ja/docs/Web/Privacy/Privacy_sandbox/Partitioned_cookies)、いわゆる "Partitioned Cookies" をサポートしました。 + この機能は開発者が {{HTTPHeader("Set-Cookie")}} HTTP ヘッダーの [`partitioned`](/ja/docs/Web/HTTP/Headers/Set-Cookie#partitioned) ディレクティブを使用して、Cookie を分割された記憶領域へ保存できるようにします。これを設定すると Cookie がトップレベルごとに分割された記憶領域に保存されて、同じトップレベルサイトかサブドメインに限り読み取れるようになります。これはクロスサイトトラッキングを防ぎながら、サイトのさまざまなサブドメインにわたって埋め込み地図やチャットウィジェットの状態を維持するなどの、適切なサードパーティ Cookie の利用を可能にします ([Firefox bug 1908160](https://bugzil.la/1908160))。 + +### API + +- {{domxref('PointerEvent')}} インターフェイスの {{domxref('PointerEvent.altitudeAngle','altitudeAngle')}} および {{domxref('PointerEvent.azimuthAngle','azimuthAngle')}} プロパティをサポートしました。- それぞれポインターやスタイラスと画面 (X 軸 -Y 軸の面) の角度、および画面上で X 軸に対するスタイラスの回転角を示します ([Firefox bug 1656377](https://bugzil.la/1656377))。 +- [テキストフラグメント](/ja/docs/Web/URI/Fragment/Text_fragments) をサポートしました。ユーザーがウェブページのテキストの一部分にリンクおよびハイライト表示することを可能にします。この機能は[URL フラグメント](/ja/docs/Web/URI/Fragment) で、表示されるテキストのパターンに基づいて対象を識別する特定の構文を使用します。 + 開発者は {{domxref("Document.fragmentDirective")}} プロパティ ({{domxref("FragmentDirective")}} インターフェイスのインスタンス) の存在によって、テキストフラグメントをサポートしているか確認できます。また、{{CSSxRef("::target-text")}} 擬似要素を使用して、テキストフラグメントリンクで指定されたテキストの選択およびスタイル設定が可能です ([Firefox bug 1914877](https://bugzil.la/1914877))。 +- {{domxref("Document")}} インターフェイスの {{domxref('Document/caretPositionFromPoint','caretPositionFromPoint()')}} メソッドを、キャレットの位置に対応するシャドウルートがメソッドに渡されていればシャドウ DOM におけるキャレット位置のテキストノードとオフセットを返すように更新しました。{{domxref("ShadowRoot")}} オブジェクトは、新たに追加された引数 `options` の `shadowRoots` プロパティを使用してメソッドに渡すことができます ([Firefox bug 1914596](https://bugzil.la/1914596))。 + +### WebAssembly + +- `exnref` の値を持つ新たな例外参照を、WebAssembly と JavaScript の間の双方向の [例外処理](/ja/docs/WebAssembly/JavaScript_interface/Exception) の支援に使用できるようになりました ([Firefox bug 1908375](https://bugzil.la/1908375))。 + +### WebDriver への適合 (WebDriver BiDi, Marionette) + +#### 一般 + +- WebDriver Classic および BiDi の双方で、`keyUp` および `keyDown` アクションが `value` で複数の文字を受け入れないようになりました ([Firefox bug 1910352](https://bugzil.la/1910352))。 + +#### WebDriver BiDi + +- `network.continueResponse` コマンドの残りの引数をサポートしました: + - 引数 cookies および headers ([Firefox bug 1853887](https://bugzil.la/1853887))。 + - 引数 `statusCode` (例: 200, 304) および `reasonPhrase` (例: "OK"、"Not modified") ([Firefox bug 1913737](https://bugzil.la/1913737))。 +- 引数 `wait` が `none` である場合に `browsingContext.navigate` コマンドが返り `beforeunload` プロンプトが発生するようになりました ([Firefox bug 1763134](https://bugzil.la/1763134))。 +- 仕様書の要求に従って、ナビゲーションが失敗したすべてのケースで `browsingContext.navigate` コマンドが `unknown error` を返すようになりました ([Firefox bug 1905083](https://bugzil.la/1905083))。 +- `session.new` コマンドは、クライアントが引数で指定していない場合に `unhandledPromptBehavior` 機能をレスポンスに含めないようになりました ([Firefox bug 1909455](https://bugzil.la/1909455))。 + +## アドオン開発者向けの変更点一覧 + +- Nightly 版のFirefox 131 で、{{WebExtAPIRef("storage.session")}} API で保存するデータに 10 MB の上限が強制されるようになりました。以前の Firefox は上限を実装していませんでした。この制限は Firefox 134 からリリース版にロールアウトします ([Firefox bug 1915688](https://bugzil.la/1915688))。これにより、以前の動作に依存する拡張機能が問題を修正できるようになります ([Firefox bug 1908925](https://bugzil.la/1908925))。 +- {{WebExtAPIRef("storage.session")}} が {{WebExtAPIRef("storage.StorageArea.getBytesInUse()")}} API および {{WebExtAPIRef("storage.session.QUOTA_BYTES")}} プロパティをサポートしました ([Firefox bug 1908925](https://bugzil.la/1908925))。 +- `tabs.update()` で `openerTabId` が変更されたときに {{WebExtAPIRef("tabs.onUpdated")}} が発生するようになりました ([Firefox bug 1409262](https://bugzil.la/1409262))。 +- `openerTabId` をクリアーするため、{{WebExtAPIRef("tabs.update")}} で `openerTabId` に `-1` を設定することが可能になりました ([Firefox bug 1409262](https://bugzil.la/1409262))。 + +## 実験的なウェブ機能 + +以下の機能は Firefox 131 で新たに導入しましたが、デフォルトで無効です。これらを実験するには、`about:config` ページで適切な設定項目を検索して `true` に設定してください。[実験的機能](/ja/docs/Mozilla/Firefox/Experimental_features) のページで、さらに多くの機能を確認できます。 + +- **正規表現の (?ims-ims:...) モディファイアー:** `javascript.options.experimental.regexp_modifiers`。 + + 正規表現の [(?ims-ims:...)](/ja/docs/Web/JavaScript/Reference/Regular_expressions/Modifier) モディファイアーは、正規表現パターンの特定の一部分に限って効果がある変更を行えます ([Firefox bug 1899813](https://bugzil.la/1899813))。 + +- **マイクとカメラの権限:** `permissions.media.query.enabled`。 + + マイクやカメラへのアクセスが許可されているか拒否されているか、またはユーザーの承諾が必要な状態かを確認するため、{{domxref("Permissions.query()")}} メソッドで `microphone` および `camera` の [権限](/ja/docs/Web/API/Permissions_API) が使用可能になりました ([Firefox bug 1609427](https://bugzil.la/1609427) および [Firefox bug 1915222](https://bugzil.la/1915222))。 + +## 過去のバージョン + +{{Firefox_for_developers}} From b93c74c107ed225ebbb0ad9c0994e7532c541a7d Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 9 Oct 2024 22:47:10 +0900 Subject: [PATCH 002/221] =?UTF-8?q?2024/10/07=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../reference/global_objects/promise/index.md | 58 ++++++++++--------- .../global_objects/promise/race/index.md | 4 +- 2 files changed, 32 insertions(+), 30 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/promise/index.md b/files/ja/web/javascript/reference/global_objects/promise/index.md index 2585e2c1bbf450..d0692a3e737077 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/index.md @@ -2,7 +2,7 @@ title: Promise slug: Web/JavaScript/Reference/Global_Objects/Promise l10n: - sourceCommit: 10b342385644e822d123694ad3bc8c2ca9abb2dc + sourceCommit: 1b4e6d1156e8471d38deeea1567c35ef412c5f42 --- {{JSRef}} @@ -13,7 +13,7 @@ l10n: ## 解説 -プロミス (**`Promise`**) は、作成された時点では分からなくてもよい値へのプロキシーです。非同期のアクションの成功値または失敗理由にハンドラーを結びつけることができます。これにより、非同期メソッドは結果の値を返す代わりに、未来のある時点で値を提供する*プロミス*を返すことで、同期メソッドと同じように値を返すことができるようになります。 +プロミス (`Promise`) は、作成された時点では分からなくてもよい値へのプロキシーです。非同期のアクションの成功値または失敗理由にハンドラーを結びつけることができます。これにより、非同期メソッドは結果の値を返す代わりに、未来のある時点で値を提供する*プロミス*を返すことで、同期メソッドと同じように値を返すことができるようになります。 `Promise` の状態は以下のいずれかとなります。 @@ -45,11 +45,11 @@ new Promise((resolveOuter) => { > [!NOTE] > Scheme など一部の言語では、遅延評価や計算を延期する機構を持っており、これらも「プロミス」と呼ばれます。 JavaScript におけるプロミスは、すでに起きつつある処理を表し、この処理はコールバック関数を使うことで連鎖させることができます。式を遅延評価する方法を探しているのであれば、引数なしの関数を使用するを検討してください。 `f = () => expression` で遅延評価される式が作成でき、 `f()` でその式を直ちに評価することができます。 -### プロミスの連鎖 +`Promise` 自体にはキャンセル用の第一級プロトコルはありませんが、通常は [`AbortController`](/ja/docs/Web/API/AbortController) を使用して、その基盤となる非同期操作を直接キャンセルできる場合があります。 -{{jsxref("Promise.prototype.then()")}}, {{jsxref("Promise.prototype.catch()")}}, {{jsxref("Promise.prototype.finally()")}} の各メソッドを使用して、決定したプロミスにさらなるアクションを結びつけることができます。 +### プロミスの連鎖 -`.then()` メソッドは、最大で 2 つの引数を取ります。1 番目の引数は、プロミスが履行された場合のコールバック関数で、 2 番目の引数は、拒否された場合のコールバック関数です。それぞれの `.then()` は新たに生成されたプロミスオブジェクトを返します。このオブジェクトは、オプションで連鎖に使用することができます。例えば、このようになります。 +{{jsxref("Promise/then", "then()")}}, {{jsxref("Promise/catch", "catch()")}}, {{jsxref("Promise/finally", "finally()")}} の各メソッドを使用して、決定したプロミスにさらなるアクションを結びつけることができます。`then()` メソッドは、最大で 2 つの引数を取ります。1 番目の引数は、プロミスが履行された場合のコールバック関数で、 2 番目の引数は、拒否された場合のコールバック関数です。`catch()` メソッドと `finally()` メソッドは内部で `then()` を呼び出し、エラー処理を簡潔にします。例えば、`catch()` は履行ハンドラーを渡さない `then()` メソッドと同じです。これらのメソッドはプロミスを返すため、連結することができます。例えば次のようになります。 ```js const myPromise = new Promise((resolve, reject) => { @@ -64,9 +64,21 @@ myPromise .then(handleFulfilledC, handleRejectedC); ``` -`.then()` にコールバック関数がない場合でも、連鎖の次のリンクへと処理が進みます。したがって、連鎖では最後の `.catch()` まで、すべての*拒否*のコールバック関数を省略しても安全です。 +ここでは、次の用語を使用します。「初期プロミス」とは、`then` が呼び出されるプロミスです。「新しいプロミス」とは、`then` が返すプロミスです。`then` に渡す 2 つのコールバックは、それぞれ「履行ハンドラー」と「拒否ハンドラー」と呼びます。 + +初期プロミスの決定状態によって、実行するハンドラーが決まります。 + +- 初期プロミスが履行された場合、履行ハンドラーが履行値とともに呼び出されます。 +- 初期プロミスが拒否された場合、拒否ハンドラーが拒否理由とともに呼び出されます。 + +ハンドラーの完了によって、新しいプロミスの決定状態が決まります。 + +- ハンドラーが [Thenable](#thenable) 値を返した場合、新しいプロミスは返値と同じ状態で決定されます。 +- ハンドラーが Thenable ではない値を返した場合、新しいプロミスは返値で履行されます。 +- ハンドラーがエラーを発生させた場合、新しいプロミスは発生したエラーで拒否されます。 +- 初期プロミスに該当するハンドラーが接続されていない場合、新しいプロミスは初期プロミスと同じ状態に決定されます。つまり、拒否ハンドラーがなければ、拒否されたプロミスは同じ理由で拒否されたままになります。 -それぞれの `.then()` で拒否されたプロミスを扱うと、プロミスの連鎖のさらに先に影響を及ぼします。エラーを直ちに処理しなければならないため、選択の余地がない場合もあります。このような場合には、連鎖的にエラー状態を維持するために、何らかの種類のエラーを発生させる必要があります。一方で、緊急の必要性がない場合は、最後の `.catch()` ステートメントまでエラー処理を行わない方がシンプルです。 `.catch()` は、実際には、単なる `.then()` からプロミスが履行されたときのためのコールバック関数のスロットを抜いたものです。 +例えば、上記のコードでは、`myPromise` が拒否された場合、`handleRejectedA` が呼び出され、`handleRejectedA` が正常に完了した場合（エラーが発生したり拒否されたプロミスを返したりしない限り）、最初の `then` で返されたプロミスは拒否されたままになるのではなく、履行されます。したがって、エラーをすぐに処理する必要があるものの、その後の処理でエラー状態を維持したい場合は、拒否ハンドラーで何らかの型のエラーを発生させる必要があります。一方、即座にエラー処理をする必要がない場合は、最終的な `catch()` ハンドラーまでエラー処理を省略する方が簡単です。 ```js myPromise @@ -95,21 +107,9 @@ myPromise > [!NOTE] > より高速に実行するためには、できればすべての同期アクションを 1 つのハンドラー内で行うようにしてください。そうしなければ、すべてのハンドラーを順番に実行するのに数カウントかかることになります。 -プロミスの終了条件は、その連鎖内の次のプロミスの「決定」状態を決定します。「履行」状態はプロミスの完了が成功したことを示し、「拒否」状態は成功しなかったことを示します。連鎖内で履行されたそれぞれのプロミスの返値は、次の `.then()` に渡され、拒否された理由は連鎖内の次の拒否ハンドラー関数に渡されます。 - -連鎖のプロミスは、他のものの中に入れ子になっていますが、スタックの一番上のように取り出されます。連鎖の最初のプロミスは最も深くネストされており、最初に取り出されます。 - -```plain -(プロミス D, (プロミス C, (プロミス B, (プロミス A) ) ) ) -``` - -`nextValue` がプロミスである場合、その効果は動的な置換です。 `return` によってプロミスが取り出されますが、 `nextValue` のプロミスはその場所に押し込まれます。上に示した入れ子では、"プロミス B" に関連付けられた `.then()` が "プロミス X" の `nextValue` を返すとします。 結果としての入れ子は以下のようになります。 - -```plain -(プロミス D, (プロミス C, (プロミス X) ) ) -``` +JavaScript は[ジョブキュー](/ja/docs/Web/JavaScript/Event_loop)を維持します。 JavaScript は毎回、キューからジョブを選択し、それを完全に実行します。毎回、JavaScript でキューからジョブが選択され、完全に実行されます。 ジョブは、`Promise()` コンストラクターの実行者、`then` に渡されたハンドラー、またはプロミスを返すプラットフォーム API によって定義されます。 連鎖するプロミスは、これらのジョブ間の依存関係を表します。 プロミスが確定すると、それに関連付けられた各ハンドラーがジョブキューの最後に追加されます。 -プロミスは複数の入れ子に参加することができます。以下のコードでは、 `プロミス A` が「決定」状態に移行すると、 `.then()` の両方のインスタンスが呼び出されます。 +プロミスは複数の連鎖に参加できます。次のコードにおいて、`promiseA` が履行されると、`handleFulfilled1` と `handleFulfilled2` の両方がジョブキューに追加されます。`handleFulfilled1` が最初に登録されているため、最初に呼び出されます。 ```js const promiseA = new Promise(myExecutorFunc); @@ -117,7 +117,7 @@ const promiseB = promiseA.then(handleFulfilled1, handleRejected1); const promiseC = promiseA.then(handleFulfilled2, handleRejected2); ``` -既に「決定」状態のプロミスにアクションを割り当てることができます。その場合、アクションは (適切であれば) 最初の非同期の機会に実行されます。プロミスは非同期であることが保証されていることに注意してください。したがって、既に「解決」状態のプロミスに対するアクションは、スタックがクリアされ、クロックティックが経過した後にのみ実行されます。この効果は `setTimeout(action, 0)` とよく似ています +すでに決定済みのプロミスにアクションを割り当てることができます。この場合、アクションはすぐにジョブキューの最後に追加され、既存のジョブがすべて完了すると実行されます。したがって、すでに「決定済み」のプロミスに対するアクションは、現在の同期コードが完了し、少なくとも1つのループティックが渡された後にのみ発生します。これにより、プロミスアクションが非同期であることが保証されます。 ```js const promiseA = new Promise((resolve, reject) => { @@ -142,7 +142,7 @@ JavaScript のエコシステムには、プロミスが言語の一部となる const aThenable = { then(onFulfilled, onRejected) { onFulfilled({ - // The thenable is fulfilled with another thenable + // Thenable は他の Thenable で履行される then(onFulfilled, onRejected) { onFulfilled(42); }, @@ -177,7 +177,7 @@ JavaScript はもともと[シングルスレッド](/ja/docs/Glossary/Thread) ## 静的プロパティ -- {{jsxref("Promise/@@species", "Promise[@@species]")}} +- [`Promise[Symbol.species]`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Symbol.species) - : プロミスのメソッドから返値を構築するために使用するコンストラクターを返します。 ## 静的メソッド @@ -194,6 +194,8 @@ JavaScript はもともと[シングルスレッド](/ja/docs/Glossary/Thread) - : 与えられた理由で拒否された新しい `Promise` オブジェクトを返します。 - {{jsxref("Promise.resolve()")}} - : 与えられた値で解決された `Promise` オブジェクトを返します。もし値が Thenable （つまり `then` メソッドを持っているオブジェクト）ならば、返されるプロミスはその Thenable をたどり、その結果を採用します。そうでなければ、返されるプロミスは与えられた値で履行されます。 +- {{jsxref("Promise.try()")}} {{experimental_inline}} + - : あらゆる種類のコールバック（復帰か例外か、同期的か非同期的にかかわらず）を取り、その結果を `Promise` でラップします。 - {{jsxref("Promise.withResolvers()")}} - : {{jsxref("Promise/Promise", "Promise()")}} コンストラクターの実行側に渡された 2 つの引数に対応する、新しい `Promise` オブジェクトとそれを解決または拒否する 2 つの関数を格納したオブジェクトを返します。 @@ -203,8 +205,8 @@ JavaScript はもともと[シングルスレッド](/ja/docs/Glossary/Thread) - {{jsxref("Object/constructor", "Promise.prototype.constructor")}} - : インスタンスオブジェクトを作成したコンストラクター関数。 `Promise` インスタンスの場合、初期値は {{jsxref("Promise/Promise", "Promise")}} コンストラクターです。 -- `Promise.prototype[@@toStringTag]` - - : [`@@toStringTag`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) プロパティの初期値は文字列 `"Promise"` です。このプロパティは {{jsxref("Object.prototype.toString()")}} で使用されます。 +- `Promise.prototype[Symbol.toStringTag]` + - : [`[Symbol.toStringTag]`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) プロパティの初期値は文字列 `"Promise"` です。このプロパティは {{jsxref("Object.prototype.toString()")}} で使用されます。 ## インスタンスメソッド @@ -305,7 +307,7 @@ new Promise(tetheredGetNumber) ### 高度な例 -以下の例は `Promise` の仕組みを示したものです。 `testPromise()` メソッドは {{HTMLElement("button")}} をクリックする度に呼び出されます。これは、{{domxref("setTimeout()")}} を用いて、 1 秒から 3 秒のランダムな時間の後、メソッドがこれまでに呼ばれた回数で履行されるプロミスを作成します。 `Promise()` コンストラクターを使用してプロミスを生成します。 +以下の例は `Promise` の仕組みを示したものです。 `testPromise()` メソッドは {{HTMLElement("button")}} をクリックする度に呼び出されます。これは、{{domxref("Window.setTimeout", "setTimeout()")}} を用いて、 1 秒から 3 秒のランダムな時間の後、メソッドがこれまでに呼ばれた回数で履行されるプロミスを作成します。 `Promise()` コンストラクターを使用してプロミスを生成します。 プロミスが履行されたことは、 {{jsxref("Promise/then", "p1.then()")}} で設定されたコールバックによって記録されます。この記録から、メソッドの同期処理部分が、プロミスによる非同期処理からどのように分離されているかがわかります。 @@ -457,4 +459,4 @@ btn.addEventListener("click", testPromise); - [プロミスの使用](/ja/docs/Web/JavaScript/Guide/Using_promises)ガイド - [Promises/A+ specification](https://promisesaplus.com/) - [JavaScript Promises: an introduction](https://web.dev/articles/promises) (web.dev, 2013) -- [Callbacks, Promises, and Coroutines: Asynchronous Programming Patterns in JavaScript](https://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript) Domenic Denicola によるスライドショー (2011) +- [Callbacks, Promises, and Coroutines: Asynchronous Programming Patterns in JavaScript](https://www.slideshare.net/slideshow/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript/9953720) (Domenic Denicola によるスライドショー, 2011) diff --git a/files/ja/web/javascript/reference/global_objects/promise/race/index.md b/files/ja/web/javascript/reference/global_objects/promise/race/index.md index 6250e679e961a0..bd7169d8ef379b 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/race/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/race/index.md @@ -2,7 +2,7 @@ title: Promise.race() slug: Web/JavaScript/Reference/Global_Objects/Promise/race l10n: - sourceCommit: 3f0cd840cd9575701c65b8c6a1e172a2b0c3bd62 + sourceCommit: 1b4e6d1156e8471d38deeea1567c35ef412c5f42 --- {{JSRef}} @@ -39,7 +39,7 @@ Promise.race(iterable) ### Promise.race() の使用 -この例では、 `Promise.race()` を使用して、 [`setTimeout()`](/ja/docs/Web/API/setTimeout) で実装された複数のタイマーを競わせることができることを示しています。最も時間の短いタイマーが常にレースに勝ち、結果のプロミスの状態となります。 +この例では、 `Promise.race()` を使用して、{{domxref("Window.setTimeout", "setTimeout()")}} で実装された複数のタイマーを競わせることができることを示しています。最も時間の短いタイマーが常にレースに勝ち、結果のプロミスの状態となります。 ```js function sleep(time, value, state) { From f2949059bc4568056059e625e02a79a6e4351ac4 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 9 Oct 2024 23:52:22 +0900 Subject: [PATCH 003/221] =?UTF-8?q?2024/10/05=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../global_objects/promise/promise/index.md | 207 ++++++++++++++---- 1 file changed, 163 insertions(+), 44 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/promise/promise/index.md b/files/ja/web/javascript/reference/global_objects/promise/promise/index.md index bc5dcaa8c17c56..64dbb0022ac88d 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/promise/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/promise/index.md @@ -1,6 +1,8 @@ --- title: Promise() コンストラクター slug: Web/JavaScript/Reference/Global_Objects/Promise/Promise +l10n: + sourceCommit: 1edfd3d5da5e1a559adb5d3a6a56beaed14845d6 --- {{JSRef}} @@ -11,76 +13,144 @@ slug: Web/JavaScript/Reference/Global_Objects/Promise/Promise ## 構文 -```js -new Promise(executor); +```js-nolint +new Promise(executor) ``` +> **メモ:** `Promise()` は [`new`](/ja/docs/Web/JavaScript/Reference/Operators/new) 付きでないと構築できません。`new` なしで呼び出そうとすると {{jsxref("TypeError")}} が発生します。 + ### 引数 - `executor` + - : コンストラクターが実行する関数 ({{jsxref("function")}}) です。これは、引数として `resolveFunc` と `rejectFunc` の 2 つの関数を受け取ります。`executor` で発生したエラーはすべてプロミスを拒否させ、返値は無視されます。`executor` の意味づけについては下記で詳しく説明します。 + +### 返値 - - : 新しい `Promise` オブジェクトを構築する過程でコンストラクターによって呼び出される関数 ({{jsxref("function")}}) です。 `executor` は結果をプロミスに結びつけるカスタムコードです。プログラマーが `executor` を書きます。この関数の形式は次のようなものであると期待されます。 +`new` で呼び出されると、`Promise` コンストラクターはプロミスオブジェクトを返します。このプロミスオブジェクトは、関数 `resolveFunc` または `rejectFunc` のいずれかが呼び出されると、「解決済み」になります。 `resolveFunc` を呼び出して別のプロミスオブジェクトを引数として渡すと、最初のプロミスは「解決済み」となりますが、まだ「確定済み」ではないことに注意してください。詳しくは[プロミスの解説](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#description)を参照してください。 - ```js - function(resolutionFunc, rejectionFunc){ - // 通常は非同期操作です。 - } - ``` +## 解説 - `resolutionFunc` と `rejectionFunc` も関数で、実際には好きな名前を付けることができます。呼び出し形式は単純で、単一の任意の型の引数を受け付けます。 +従来（プロミス以前）、非同期タスクはコールバックとして設計されていました。 - - ```js - resolutionFunc(value) // 解決した時に呼び出し - rejectionFunc(reason) // 拒否した時に呼び出し - ``` +```js +readFile("./data.txt", (error, result) => { + // このコールバックは、最終的な `error` または `result` を含む + // タスクが完了したときに呼び出されます。結果に依存する操作は、 + // このコールバック内で定義する必要があります。 +}); +// ここに書かれたコードは、`readFile` リクエストが発生すると +// すぐに実行されます。 コールバックが呼ばれるのを待たないため、 +// `readFile` は「非同期」となります。 +``` - `resolutionFunc` の `value` 引数は他のプロミスオブジェクトにすることもでき、そうするとそのプロミスは[プロミス連鎖](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#chained_promises)の中に動的に挿入されます。 +プロミスが提供するコードの読み取りやすさの向上と言語機能を活用するために、`Promise()` コンストラクターを使用すると、コールバックベースの API をプロミスベースの API に変換することができます。 - `executor` については、以下のことを理解することが重要です。 +> [!NOTE] +> タスクがすでにプロミスベースである場合、`Promise()` コンストラクターは不要でしょう。 - - `executor` の返値は無視されます。 - - `executor` の中でエラーが発生した場合、プロミスは拒否されます。 +`executor` は、コールバックの結果をプロミスに結びつけるカスタムコードです。プログラマーであるあなたが `executor` を書きます。そのシグネチャは次のようになります。 - つまり、 `executor` の中のコードが効果を発揮する仕組みは、次のようなものです。 +```js +function executor(resolveFunc, rejectFunc) { + // 通常、コールバックを受け入れる非同期操作、 + // 例えば上記の `readFile` 関数のようなもの +} +``` - - コンストラクターが新しい `Promise` オブジェクトを生成した時点で、対応する `resolutionFunc` と `rejectionFunc` の一対の関数も生成されます。これらは `Promise` オブジェクトに「結束」されます。 - - `executor` 内のコードは、何らかの操作を行う機会を得、その結果を（値が他の Promise オブジェクトでない場合）「解決済み」または「拒否済み」として反映し、それぞれ `resolutionFunc` または `rejectionFunc` を呼び出して終了します。 - - つまり、`executor` 内のコードは、 `resolutionFunc` や `rejectionFunc` による副次的影響を介して通信を行います。その副次的影響とは、 `Promise` オブジェクトが「解決済み」または「拒否済み」になることです。 +`resolveFunc` と `rejectFunc` も関数で、実際には好きな名前を付けることができます。呼び出し形式は単純で、単一の任意の型の引数を受け付けます。 - 以上のことを踏まえて、典型的な流れをまとめてみました。 +```js +resolveFunc(value); // 解決した時の呼び出し +rejectFunc(reason); // 拒否した時の呼び出し +``` - 1. `executor` の中の操作は非同期であり、コールバックを提供します。 - 2. コールバックは `executor` コードの中で定義されます。 - 3. コールバックは `resolutionFunc` を呼び出して終了します。 - 4. `resolutionFunc` の呼び出しには `value` 引数が含まれます。 - 5. `value` は繋がっている `Promise` オブジェクトに送り返されます。 - 6. `Promise` オブジェクトは（非同期に）関連付けられた `.then(handleResolved)` を呼び出します。 - 7. `.then(handleResolved)` から受け取った `value` は、 `handleResolved` の呼び出しで入力引数として渡されます（[プロミスの連鎖](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#chained_promises)を参照してください）。 +`resolveFunc` に渡す `value` 引数は、別のプロミスオブジェクトにすることができます。その場合、新たに構築されたプロミスの状態は、渡されたプロミスに「ロックイン」されます（[解決](#resolve_関数)プロミスの一部として）。`rejectFunc` は、[`throw`](/ja/docs/Web/JavaScript/Reference/Statements/throw) 文に近い意味を持ちます。そのため、`reason` は通常、[`Error`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Error) インスタンスです。`value` または `reason` のいずれかを省略すると、プロミスは `undefined` で履行/拒否されます。 -### 返値 +`executor` の完了状態は、プロミスの状態に制限された効果しか持ちません。 -`new` を通じて呼び出された場合、 `Promise` コンストラクターはプロミスオブジェクトを返します。このプロミスオブジェクトは、 `resolutionFunc` 関数または `rejectionFunc` 関数が呼び出されると「解決」になります。なお、 `resolutionFunc` または `rejectionFunc` を別な Promise オブジェクトを引数にして呼び出すと、これが「解決」であると言えますが、「満足」であるとは言えません。 +- `executor` の返値は無視されます。 `executor` 内の `return` 文は制御フローに影響を与えるだけで、関数の一部が実行されるかどうかを変更しますが、プロミスの履行値には影響を与えません。 `executor` が終了し、今後 `resolveFunc` または `rejectFunc` が呼び出されることが不可能な場合（例えば、非同期タスクがスケジュールされていない場合）、プロミスは永遠に待機状態のままとなります。 +- エラーが `executor` で発生した場合、`resolveFunc` または `rejectFunc` がすでに呼び出されていない限り、プロミスは拒否されます。 -## 例 +> [!NOTE] +> 待機中のプロミスの存在は、プログラムの終了を妨げることはありません。イベントループが空の場合、待機中のプロミスがあってもプログラムは終了します（必ず永遠に待機中であるため）。 -### 新しい Promise の作成 +以下に、典型的な流れの概要を示します。 -`Promise` オブジェクトは `new` キーワードとコンストラクターで作成されます。コンストラクターは「executor 関数」と呼ばれる引数を取ります。 これは 2 つの関数を引数として取ります。 1 つ目の関数 (`resolve`) は非同期タスクが成功して完了した場合に呼び出され、タスクの結果を値として返します。2 つ目の関数 (`reject`) はタスクが失敗した場合に呼び出され、失敗した理由（ふつうはエラーオブジェクト）を返します。 +1. コンストラクターが新しい `Promise` オブジェクトを生成する時点において、`resolveFunc` と `rejectFunc` に対応する関数ペアも生成されます。これらは `Promise` オブジェクトに「結び付け」られます。 +2. `executor` は通常、コールバックベースの API を指定された非同期操作をラップします。 コールバック（元のコールバックベースの API に渡すもの）は `executor` コード内で定義されるため、`resolveFunc` と `rejectFunc` にアクセスすることができます。 +3. `executor` は、`resolveFunc` および `rejectFunc` 関数を引数として、同期的に（`Promise` が構築されるとすぐに）呼び出されます。 +4. `executor` 内のコードには、何らかの操作を実行する機会があります。非同期タスクの最終的な完了は、`resolveFunc`または`rejectFunc`によって発生する付随する効果を通じて、プロミスインスタンスに通知されます。この付随する効果により、`Promise` オブジェクトが「解決済み」となります。 + - `resolveFunc` が最初に呼び出されると、渡された値が[解決](#resolve_関数)されます。プロミスは、待機状態のままになる場合（別の [thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenable) が渡された場合）、履行される場合（thenable ではない値が渡されたほとんどの場合）、または拒否される場合（不正な解決値の場合）があります。 + - `rejectFunc` が最初の呼び出された場合、プロミスは即座に拒否されます。 + - 解決関数（`resolveFunc` または `rejectFunc`）のいずれかが呼び出されると、プロミスは解決された状態になります。 `resolveFunc` または `rejectFunc` の最初の呼び出しのみがプロミスの最終的な状態に影響し、その後のいずれかの関数への呼び出しは、履行値/拒否理由を変更することも、最終的な状態を「履行済み」から「拒否済み」またはその反対に切り替えることもできません。 + - `executor` がエラーを発生して終了した場合、プロミスは拒否されます。ただし、解決関数のいずれかがすでに呼び出されている場合（プロミスがすでに解決されている場合）、そのエラーは無視されます。 + - プロミスを解決しても、必ずしもプロミスが履行されたり拒否されたり（決定）するわけではありません。プロミスは、別の thenable で解決されているため、まだ待機状態である可能性がありますが、最終的な状態は解決された thenable の状態と一致します。 +5. プロミスが確定すると、（非同期で） {{jsxref("Promise/then", "then()")}}, {{jsxref("Promise/catch", "catch()")}}, {{jsxref("Promise/finally", "finally()")}} を通じて関連付けられたハンドラーが呼び出されます。最終的な履行値または拒否理由は、履行および拒否ハンドラーの呼び出しに引数として渡されます（[プロミスの連鎖](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#プロミスの連鎖)を参照）。 + +例えば、上記のコールバックベースの `readFile` API は、プロミスベースの API に変換することができます。 + +```js +const readFilePromise = (path) => + new Promise((resolve, reject) => { + readFile(path, (error, result) => { + if (error) { + reject(error); + } else { + resolve(result); + } + }); + }); + +readFilePromise("./data.txt") + .then((result) => console.log(result)) + .catch((error) => console.error("Failed to read data")); +``` + +`resolve` コールバックと `reject` コールバックは、実行関数のスコープ内でのみ利用できるため、プロミスが構築された後にそれらにアクセスすることはできません。プロミスの解決方法を決定する前にプロミスを構築したい場合は、代わりに {{jsxref("Promise.withResolvers()")}} メソッドを使用することができます。このメソッドは、`resolve` と `reject` の関数を公開します。 + +### resolve 関数 + +`resolve` 関数は、以下の動作をします。 + +- 新しく作成したプロミスと同じ値でプロミスが呼ばれた場合（「連結された」プロミス）、プロミスは {{jsxref("TypeError")}} で拒否されます。 +- [thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenable) でない値（プリミティブ、またはプロパティが存在しない場合も含め、`then` プロパティが呼び出せないオブジェクト）で名付けられた場合、プロミスは即座にその値で履行されます。 +- もし、thenable 値（別の `Promise` インスタンスを含みます）で呼び出された場合、thenable の `then` メソッドが保存され、将来呼び出されます（常に非同期で呼び出されます）。`then` メソッドは、2 つのコールバックとともに呼び出されます。このコールバックは、`executor` 関数に渡す `resolveFunc` および `rejectFunc` とまったく同じ動作をする 2 つの新しい関数です。 `then` メソッドを呼んで例外が発生すると、現在のプロミスは発生したエラーとともに拒否されます。 + +最後の場合、これは次のようなコードを意味しています。 ```js -const myFirstPromise = new Promise((resolve, reject) => { - // 次のどちらかを呼び出す非同期処理を行います。 - // - // resolve(someValue) // 履行 - // または - // reject("failure reason") // 拒否 +new Promise((resolve, reject) => { + resolve(thenable); }); ``` -### Promise を返す関数の作成 +Is roughly equivalent to: -関数にプロミス機能を提供するには、次のように単にプロミスを返すようにします。 +```js +new Promise((resolve, reject) => { + try { + thenable.then( + (value) => resolve(value), + (reason) => reject(reason), + ); + } catch (e) { + reject(e); + } +}); +``` + +ただし、`resolve(thenable)` の場合は例外です。 + +1. `resolve` は同期的に呼び出されるため、たとえ `anotherPromise.then()` を通して添付されたハンドラーがまだ呼び出されていない場合でも、`resolve` または `reject` を再度呼び出しても効果はありません。 +2. `then` メソッドは非同期で呼び出されるため、thenable が渡されてもプロミスは即座に解決されることはありません。 + +`resolve` は、`thenable.then()` が `value` として渡した何かを再び呼び出すため、リゾルバー関数は入れ子になった thenable を平坦化することができます。つまり、thenable が別の thenable を呼び出して `onFulfilled` ハンドラーを実行するような場合です。この効果により、実際のプロミスの履行ハンドラーが thenable を履行値として受け取ることは決してありません。 + +## 例 + +### コールバックベースの API をプロミスベースのものに変換 + +プロミス機能を指定された関数に持たせるには、適切な時点で `resolve` および `reject` 関数を呼んでプロミスを返します。 ```js function myAsyncFunction(url) { @@ -94,6 +164,54 @@ function myAsyncFunction(url) { } ``` +### resolveFunc の呼び出しの効果 + +`resolveFunc` を呼び出すとプロミスが解決されるため、その後 `resolveFunc` または `rejectFunc` を再度呼び出しても効果はありません。 ただし、プロミスは待機中、履行済みまたは拒否済みの、いずれかの状態を持つことがあります。 + +この `pendingResolved` プロミスは、作成された時点で解決されます。なぜなら、それはすでに内部プロミスの最終的な状態と一致するように「ロックイン」されているためであり、実行者内で後から `resolveOuter` や `rejectOuter` を呼び出したり、エラーが発生しても、最終的な状態には何の効果もありません。しかし、内部プロミスは 100 ミリ秒後まで待機状態であるため、外部プロミスも待機状態となります。 + +```js +const pendingResolved = new Promise((resolveOuter, rejectOuter) => { + resolveOuter( + new Promise((resolveInner) => { + setTimeout(() => { + resolveInner("inner"); + }, 100); + }), + ); +}); +``` + +この `fulfilledResolved` プロミスは、それが解決された瞬間に履行されます。なぜなら、それはthenable ではない値で解決されるからです。しかし、それが作成された時点では、まだ `resolve` や `reject` が呼び出されていないため、未解決の状態です。未解決のプロミスは、必ず待機状態に置かれます。 + +```js +const fulfilledResolved = new Promise((resolve, reject) => { + setTimeout(() => { + resolve("outer"); + }, 100); +}); +``` + +`rejectFunc` を呼び出すと、明らかにプロミスが拒否されます。しかし、`resolveFunc` コールバックが呼び出された場合でも、プロミスを即座に拒否させるには、2 つの方法があります。 + +```js +// 1. プロミスそのもので解決 +const rejectedResolved1 = new Promise((resolve) => { + // メモ: resolve は非同期で呼び出されなければならず、 + // rejectedResolved1変数が初期化される + setTimeout(() => resolve(rejectedResolved1)); // TypeError: Chaining cycle detected for promise # +}); + +// 2. `then` プロパティにアクセスすると発生するオブジェクトで解決 +const rejectedResolved2 = new Promise((resolve) => { + resolve({ + get then() { + throw new Error("then プロパティが取得できません"); + }, + }); +}); +``` + ## 仕様書 {{Specifications}} @@ -104,5 +222,6 @@ function myAsyncFunction(url) { ## 関連情報 -- `Promise` のポリフィルは [`core-js`](https://github.com/zloirock/core-js#ecmascript-promise) で利用できます +- [`Promise` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-promise) - [プロミスの使用](/ja/docs/Web/JavaScript/Guide/Using_promises) +- {{jsxref("Promise.withResolvers()")}} From 147c9e4dca09bd6d41cc9002a302f5b9cafcee44 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 9 Oct 2024 23:55:03 +0900 Subject: [PATCH 004/221] =?UTF-8?q?2023/11/04=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../reference/global_objects/promise/allsettled/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/promise/allsettled/index.md b/files/ja/web/javascript/reference/global_objects/promise/allsettled/index.md index ffde5de304f183..9d5b19a05cacf5 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/allsettled/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/allsettled/index.md @@ -2,14 +2,14 @@ title: Promise.allSettled() slug: Web/JavaScript/Reference/Global_Objects/Promise/allSettled l10n: - sourceCommit: 3f0cd840cd9575701c65b8c6a1e172a2b0c3bd62 + sourceCommit: c607c483fe079c61de5e32fba1a6cce61896e97d --- {{JSRef}} **`Promise.allSettled()`** は静的メソッドで、入力としてプロミスの反復可能オブジェクトを受け取り、単一の {{jsxref("Promise")}} を返します。この返されたプロミスは、入力のすべてのプロミスが決定したとき（空の反復可能オブジェクトが渡された場合を含む）に履行され、各プロミスの結果を記述するオブジェクトの配列が返されます。 -{{EmbedInteractiveExample("pages/js/promise-allsettled.html")}} +{{EmbedInteractiveExample("pages/js/promise-allsettled.html", "taller")}} ## 構文 @@ -78,7 +78,7 @@ Promise.allSettled([ ## 関連情報 - [`Promise.allSettled` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-promise) -- [プロミスの使用](/ja/docs/Web/JavaScript/Guide/Using_promises) +- [プロミスの使用](/ja/docs/Web/JavaScript/Guide/Using_promises)ガイド - [プロミスを使った行儀のよい非同期のプログラミング](/ja/docs/Learn/JavaScript/Asynchronous/Promises) - {{jsxref("Promise")}} - {{jsxref("Promise.all()")}} From a9bd5ae43701c185a57e07c88837a39a99ac0d87 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sun, 13 Oct 2024 13:51:50 +0900 Subject: [PATCH 005/221] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0=20(#23957)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2024/07/26 時点の英語版に基づき更新 * Update index.md --- .../global_objects/promise/finally/index.md | 18 ++++------ .../global_objects/promise/resolve/index.md | 33 +++++++++---------- .../promise/symbol.species/index.md | 25 +++++++------- 3 files changed, 34 insertions(+), 42 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/promise/finally/index.md b/files/ja/web/javascript/reference/global_objects/promise/finally/index.md index 4ed563c7430f44..9bc1daf87b608f 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/finally/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/finally/index.md @@ -2,12 +2,12 @@ title: Promise.prototype.finally() slug: Web/JavaScript/Reference/Global_Objects/Promise/finally l10n: - sourceCommit: 2eb202adbe3d83292500ed46344d63fbbae410b5 + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} -**`finally()`** は {{jsxref("Promise")}} のメソッドで、プロミスが決定したとき（履行されたか拒否されたかのどちらか）に呼び出される関数を準備します。直ちに同等の {{jsxref("Promise")}} オブジェクトを返すため、プロミスの他のメソッドを[連鎖](/ja/docs/Web/JavaScript/Guide/Using_promises#連鎖)呼び出しすることができます。 +**`finally()`** は {{jsxref("Promise")}} インスタンスのメソッドで、プロミスが決定したとき（履行されたか拒否されたかのどちらか）に呼び出される関数を準備します。直ちに他の {{jsxref("Promise")}} オブジェクトを返すため、プロミスの他のメソッドを[連鎖](/ja/docs/Web/JavaScript/Guide/Using_promises#連鎖)呼び出しすることができます。 これによって、プロミスの {{jsxref("Promise/then", "then()")}} ハンドラーと {{jsxref("Promise/catch", "catch()")}} ハンドラーでコードが重複することを避けることができます。 @@ -16,21 +16,17 @@ l10n: ## 構文 ```js-nolint -finally(onFinally) - -finally(() => { - // プロミスの決定（履行または拒否）後に実行されるコード -}) +promiseInstance.finally(onFinally) ``` ### 引数 - `onFinally` - - : `Promise` が決定したら呼び出される関数 ({{jsxref("Function")}}) です。このハンドラーは引数を取りません。 + - : このプロミスが決定したときに非同期で実行する関数です。返値が拒否されたプロミスでない限り、その返値は無視されます。関数は引数なしで呼び出されます。 ### 返値 -同等の {{jsxref("Promise")}} を返します。ハンドラーがエラーを発生したり、拒否されたプロミスを返したりした場合、代わりに `finally()` が返すプロミスがその値で拒否されます。そうでなければ、ハンドラーの返す値は元のプロミスの状態に影響しません。 +同等の {{jsxref("Promise")}} を返します。この新しいプロミスは、現在のプロミスの状態に関わらず、常に返されるまで待機します。 `onFinally` でエラーが発生したり、拒否されたプロミスが返された場合、新しいプロミスは同じ値で拒否されます。それ以外の場合、新しいプロミスは現在のプロミスと同じ状態で決定されます。 ## 解説 @@ -40,7 +36,7 @@ finally(() => { - 関数をインラインで作成する場合、関数を 2 度宣言するか、変数を作成するかのどちらかで、一度に渡すことができます。 - `onFinally` コールバックは一切引数を受け取りません。この用途では、拒否された理由や履行された値などを提供する必要がなく、それらを気にしないときに適しています。 -- `finally()` の呼び出しは通常透過的で、元のプロミスの最終的な状態を変更することはありません。ですから例えば、 +- 通常、`finally()` を呼び出すと、元のプロミスの最終的な状態を反映するようになります。ですから例えば、 - `Promise.resolve(2).then(() => 77, () => {})` が最終的に `77` の値で履行されるプロミスを返すのとは異なり、`Promise.resolve(2).finally(() => 77)` は最終的に `2` の値で履行されるプロミスを返します。 - 同様に、`Promise.reject(3).then(() => {}, () => 88)` が最終的に `88` の値で履行されるプロミスを返すのとは異なり、`Promise.reject(3).finally(() => 88)` は最終的に `3` の値で拒否されるプロミスを返します。 @@ -61,7 +57,7 @@ promise.then( ); ``` -`finally()` は `then()` を呼び出すので、サブクラス化に対応しています。さらに、上記の {{jsxref("Promise.resolve()")}} の呼び出しに注目してください。実際には、 `onFinally()` の返値は `Promise.resolve()` と同じアルゴリズムで解決されますが、解決されたプロミスを構築するために使用される実際のコンストラクターはサブクラスとなります。 `finally()` はこのコンストラクターを [`promise.constructor[@@species]`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/@@species) で取得します。 +`finally()` は `then()` を呼び出すので、サブクラス化に対応しています。さらに、上記の {{jsxref("Promise.resolve()")}} の呼び出しに注目してください。実際には、 `onFinally()` の返値は `Promise.resolve()` と同じアルゴリズムで解決されますが、解決されたプロミスを構築するために使用される実際のコンストラクターはサブクラスとなります。 `finally()` はこのコンストラクターを [`promise.constructor[Symbol.species]`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Symbol.species) で取得します。 ## 例 diff --git a/files/ja/web/javascript/reference/global_objects/promise/resolve/index.md b/files/ja/web/javascript/reference/global_objects/promise/resolve/index.md index c277524f068a25..d85d0085c08e2e 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/resolve/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/resolve/index.md @@ -2,12 +2,12 @@ title: Promise.resolve() slug: Web/JavaScript/Reference/Global_Objects/Promise/resolve l10n: - sourceCommit: 3fe5c1d405128b70e38347931153fd2ce10b3545 + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} -**`Promise.resolve()`** は静的メソッドで、 {{jsxref("Promise")}} を与えられた値で「解決」させます。値がプロミスの場合は、そのプロミスが返されます。その値が [Thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables) であれば、`Promise.resolve()` は `then()` メソッドを、準備した 2 つのコールバックと共に呼び出します。それ以外の場合は、その値で履行するプロミスが返されます。 +**`Promise.resolve()`** は静的メソッドで、 {{jsxref("Promise")}} を与えられた値で「解決」させます。値がプロミスの場合は、そのプロミスが返されます。その値が [Thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenable) であれば、`Promise.resolve()` は `then()` メソッドを、準備した 2 つのコールバックと共に呼び出します。それ以外の場合は、その値で履行するプロミスが返されます。 この関数は複数階層のプロミス風オブジェクト (例えば、何かで解決するプロミスで解決するプロミス) を単一の階層に平坦化します。 @@ -32,14 +32,16 @@ Promise.resolve(value) `Promise.resolve()` はプロミスを _解決_ します。これはプロミスを履行したり拒否したりすることとは異なります。用語の定義については、[プロミスの説明](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#description)を参照してください。簡単に言うと、 `Promise.resolve()` は、最終的な状態が他のプロミス、 Thenable オブジェクト、または他の値に依存しているプロミスを返します。 -`Promise.resolve()` は汎用で、サブクラス化を対応しています。つまり、`Promise` のサブクラスで呼び出すことができ、その結果はサブクラス型のプロミスになります。これを行うには、サブクラスのコンストラクターは [`Promise()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) コンストラクターと同じ定義で実装する必要があります。引数として `resolve` と `reject` コールバックで呼び出すことができる単一の `executor` 関数を受け入れることができます。 +> **メモ:** `value` 式の評価で同期的にエラーが発生する可能性がある場合、このエラーは捕捉されず、`Promise.resolve()` によって拒否されたプロミスにラップされます。この用途には {{jsxref("Promise/try", "Promise.try(() => value)")}} を使用することを検討してください。 + +`Promise.resolve()` は汎用で、サブクラス化に対応しています。つまり、`Promise` のサブクラスで呼び出すことができ、その結果はサブクラス型のプロミスになります。これを行うには、サブクラスのコンストラクターは [`Promise()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) コンストラクターと同じ定義で実装する必要があります。引数として `resolve` と `reject` コールバックで呼び出すことができる単一の `executor` 関数を受け入れることができます。 `Promise.resolve()` は、ネイティブの `Promise` のインスタンスを特別扱いしています。 `value` が `Promise` またはそのサブクラスに属し、 `value.constructor === Promise` の場合、新しい `Promise` インスタンスを作成せずに、`Promise.resolve()` で直接 `value` を返すことができます。そうでない場合、`Promise.resolve()` は基本的に `new Promise((resolve) => resolve(value))` の一括指定となります。 -解決ロジックの大部分は，実際には `Promise()` コンストラクターに渡される[リゾルバー関数](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise#resolver_function)で実装されます。概要をまとめると、次のようになります。 +解決ロジックの大部分は，実際には `Promise()` コンストラクターに渡される [`resolve` 関数](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise#resolve_関数)で実装されます。概要をまとめると、次のようになります。 -- [Thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables) でない値が渡された場合，返されたプロミスはその値ですでに履行されたものとなります。 - Thenable が渡された場合、`then` メソッドを呼び出され、引数としてリゾルバー関数のペアを渡すことで、返されるプロミスはその Thenable の状態を採用することになります。（しかし、ネイティブのプロミスはラッパーを作成せずに直接 `Promise.resolve()` を通すので、ネイティブのプロミスでは `then` メソッドは呼ばれません）。リゾルバー関数が別の Thenable オブジェクトを受け取ると、それは再び解決されるので、最終的なプロミスの履行値は決して Thenable になることはないでしょう。 +- [Thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenable) でない値が渡された場合，返されたプロミスはその値ですでに履行されたものとなります。 + Thenable が渡された場合、`then` メソッドを呼び出され、引数として解決関数のペアを渡すことで、返されるプロミスはその Thenable の状態を採用することになります。（しかし、ネイティブのプロミスはラッパーを作成せずに直接 `Promise.resolve()` を通すので、ネイティブのプロミスでは `then` メソッドは呼ばれません）。`resolve` 関数が別の Thenable オブジェクトを受け取ると、それは再び解決されるので、最終的なプロミスの履行値は決して Thenable になることはないでしょう。 ## 例 @@ -104,16 +106,13 @@ p1.then( }, ); -// Thenable throws before callback +// Thenable throws // Promise rejects -const thenable = { - then(onFulfilled) { +const p2 = Promise.resolve({ + then() { throw new TypeError("Throwing"); - onFulfilled("Resolving"); }, -}; - -const p2 = Promise.resolve(thenable); +}); p2.then( (v) => { // 呼び出されない @@ -130,9 +129,7 @@ const thenable = { onFulfilled("Resolving"); throw new TypeError("Throwing"); }, -}; - -const p3 = Promise.resolve(thenable); +}); p3.then( (v) => { console.log(v); // "Resolving" @@ -177,7 +174,7 @@ Promise.resolve(thenable); // 無限の再帰を引き起こす ### Promise 以外のコンストラクターに対する resolve() の呼び出し -`Promise.resolve()` は汎用的なメソッドです。これは `Promise()` コンストラクタと同じ定義を実装した任意のコンストラクターで呼び出すことができます。例えば、`resolve` として `console.log` を渡すコンストラクターで呼び出すことができます。 +`Promise.resolve()` は汎用的なメソッドです。これは `Promise()` コンストラクターと同じ定義を実装した任意のコンストラクターで呼び出すことができます。例えば、`resolve` として `console.log` を渡すコンストラクターで呼び出すことができます。 ```js class NotPromise { @@ -194,7 +191,7 @@ class NotPromise { Promise.resolve.call(NotPromise, "foo"); // Logs "Resolved foo" ``` -入れ子になった Thenable を平坦化する機能は `Promise()` コンストラクターのリゾルバー関数で実装されています。そのため、他のコンストラクターで呼び出すと、そのコンストラクターがリゾルバーをどのように実装しているかによって入れ子の Thenable が平坦化されない場合があります。 +入れ子になった Thenable を平坦化する機能は `Promise()` コンストラクターの `resolve` 関数で実装されています。そのため、他のコンストラクターで呼び出すと、そのコンストラクターが `resolve` 関数をどのように実装しているかによって入れ子の Thenable が平坦化されない場合があります。 ```js const thenable = { diff --git a/files/ja/web/javascript/reference/global_objects/promise/symbol.species/index.md b/files/ja/web/javascript/reference/global_objects/promise/symbol.species/index.md index e2d1966823427f..33ae80fd2aab12 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/symbol.species/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/symbol.species/index.md @@ -1,30 +1,29 @@ --- -title: get Promise[@@species] +title: Promise[Symbol.species] slug: Web/JavaScript/Reference/Global_Objects/Promise/Symbol.species -original_slug: Web/JavaScript/Reference/Global_Objects/Promise/@@species l10n: - sourceCommit: 0f248adcab759bdad247a5dbfb7da12dc32bce59 + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} -**`Promise[@@species]`** アクセサープロパティは、プロミスのメソッドからの返値を構築するのに使用されるコンストラクターを返します。 +**`Promise[Symbol.species]`** アクセサープロパティは、プロミスのメソッドからの返値を構築するのに使用されるコンストラクターを返します。 -> **警告:** `@@species` が存在すると、任意のコードの実行が可能になり、セキュリティ上の脆弱性を生み出す可能性があります。また、特定の最適化も非常に難しくなります。エンジンの実装者は[この機能を削除するかどうか調査](https://github.com/tc39/proposal-rm-builtin-subclassing)しています。可能であれば、この機能に頼ることは避けてください。 +> **警告:** `Symbol.species` が存在すると、任意のコードの実行が可能になり、セキュリティ上の脆弱性を生み出す可能性があります。また、特定の最適化も非常に難しくなります。エンジンの実装者は[この機能を削除するかどうか調査](https://github.com/tc39/proposal-rm-builtin-subclassing)しています。可能であれば、この機能に頼ることは避けてください。 ## 構文 -```js -Promise[Symbol.species]; +```js-nolint +Promise[Symbol.species] ``` ### 返値 -`get @@species` が呼び出されたコンストラクター (`this`) の値です。この返値は、新しいプロミスを作成するプロミス連鎖メソッドから返値を作成するために使用されます。 +`get [Symbol.species]` が呼び出されたコンストラクター (`this`) の値です。この返値は、新しいプロミスを作成するプロミス連鎖メソッドから返値を作成するために使用されます。 ## 解説 -`@@species` アクセサープロパティは `Promise` オブジェクトの既定のコンストラクターを返します。サブクラスのコンストラクターはこれを上書きしてコンストラクターの割り当てを変更することができます。既定の実装では、基本的に次のようになります。 +`[Symbol.species]` アクセサープロパティは `Promise` オブジェクトの既定のコンストラクターを返します。サブクラスのコンストラクターはこれを上書きしてコンストラクターの割り当てを変更することができます。既定の実装では、基本的に次のようになります。 ```js // 解説のため架空の基礎実装 @@ -35,14 +34,14 @@ class Promise { } ``` -この多相的な実装のため、派生したサブクラスの `@@species` も既定ではコンストラクター自身を返すことになります。 +この多相的な実装のため、派生したサブクラスの `[Symbol.species]` も既定ではコンストラクター自身を返すことになります。 ```js class SubPromise extends Promise {} -SubPromise[Symbol.species] === Promise; // true +SubPromise[Symbol.species] === SubPromise; // true ``` -プロミス連鎖メソッドである [`then()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/then)、[`catch()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch)、[`finally()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/finally) は、新しいプロミスオブジェクトを返します。これらは `this.constructor[@@species]` を介して新しいプロミスを構築するためのコンストラクターを取得します。 `this.constructor` が `undefined` の場合、または `this.constructor[@@species]` が `undefined` または `null` の場合、既定の {{jsxref("Promise/Promise", "Promise()")}} コンストラクターが使用されます。それ以外の場合は、 `this.constructor[@@species]` から返されるコンストラクターが使用され、新しいプロミスオブジェクトが構築されます。 +プロミス連鎖メソッドである [`then()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/then)、[`catch()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch)、[`finally()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/finally) は、新しいプロミスオブジェクトを返します。これらは `this.constructor[Symbol.species]` を介して新しいプロミスを構築するためのコンストラクターを取得します。 `this.constructor` が `undefined` の場合、または `this.constructor[Symbol.species]` が `undefined` または `null` の場合、既定の {{jsxref("Promise/Promise", "Promise()")}} コンストラクターが使用されます。それ以外の場合は、 `this.constructor[Symbol.species]` から返されるコンストラクターが使用され、新しいプロミスオブジェクトが構築されます。 ## 例 @@ -77,7 +76,7 @@ class MyPromise extends Promise { console.log(MyPromise.resolve(1).then(() => {}).someValue); // 1 ``` -`@@species` を上書きすることで、プロミスのメソッドは基底の `Promise` 型を返すことになります。 +`[Symbol.species]` を上書きすることで、プロミスのメソッドは基底の `Promise` 型を返すことになります。 ```js class MyPromise extends Promise { From 8ced7a28554400ddf9cdb7ed70cee43d08aa0eaa Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 00:55:49 +0900 Subject: [PATCH 006/221] =?UTF-8?q?2024/09/07=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../global_objects/promise/try/index.md | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 files/ja/web/javascript/reference/global_objects/promise/try/index.md diff --git a/files/ja/web/javascript/reference/global_objects/promise/try/index.md b/files/ja/web/javascript/reference/global_objects/promise/try/index.md new file mode 100644 index 00000000000000..db3166e55e2467 --- /dev/null +++ b/files/ja/web/javascript/reference/global_objects/promise/try/index.md @@ -0,0 +1,157 @@ +--- +title: Promise.try() +slug: Web/JavaScript/Reference/Global_Objects/Promise/try +l10n: + sourceCommit: b67fd42cfb01dd4d9504c4182b462851588a0bad +--- + +{{JSRef}}{{SeeCompatTable}} + +**`Promise.try()`** 静的メソッドは、あらゆる種類のコールバック（返す、発生する、同期的、非同期的）を受け取り、その結果を {{jsxref("Promise")}} でラップします。 + +## 構文 + +```js-nolint +Promise.try(func) +``` + +### 引数 + +- `func` + - : 引数なしで同期的に呼び出される関数です。何らかの処理を行うことができ、返値を返すことも、エラーを発生させることも、プロミスを返すことも可能です。 + +### 返値 + +{{jsxref("Promise")}} で、次のようなものです。 + +- `func` が同期的に値を返す場合は、すでに履行されたもの。 +- `func` が同期的にエラーを発生した場合は、すでに拒否されたもの。 +- 非同期で履行または拒否された場合、`func` はプロミスを返します。 + +## 解説 + +コールバックを受け取る API もあります。 コールバックは同期または非同期のどちらでも可能です。 結果をプロミスでラップすることで、すべてを統一的に処理したい場合、最もわかりやすい方法は、{{jsxref("Promise/resolve", "Promise.resolve(func())")}} でしょう。 問題は、`func()` で同期敵にエラーが発生した場合、このエラーが補足されず、拒否されたプロミスに変換されないことです。 + +一般的な手法（履行されたか拒否されたかに関わらず、関数呼び出しの結果をプロミスに持ち上げる）は、以下のようにすることが多いです。 + +```js +new Promise((resolve) => resolve(func())); +``` + +しかし、`Promise.try()` はもっと便利です。 + +```js +Promise.try(func); +``` + +組み込みの `Promise()` コンストラクターでは、実行時に発生したエラーは自動的に捕捉され、拒否に変換されます。そのため、これらの 2 つの手法はほぼ同等ですが、`Promise.try()` の方がより簡潔で読みやすい点が異なります。 + +なお、`Promise.try()` はこれと非常に似ていますが、同等ではありません。 + +```js +Promise.resolve().then(func); +``` + +違いは、{{jsxref("Promise/then", "then()")}} に渡されたコールバックは常に非同期で呼び出されるのに対し、`Promise()` コンストラクターの実行は同期で呼び出されることです。 `Promise.try` も関数を同期で呼び出し、可能であれば即座にプロミスを解決します。 + +`Promise.try()` を {{jsxref("Promise/catch", "catch()")}} および {{jsxref("Promise/finally", "finally()")}} と組み合わせて使用することで、単一の連鎖で同期的および非同期的なエラーの両方を処理することができ、プロミスエラー処理を同期的エラー処理とほとんど同じように見せることができます。 + +## 例 + +### Promise.try() の使用 + +次の例では、コールバックをプロミスに「引き上げ」、結果を処理し、エラー処理を行います。 + +```js +function doSomething(action) { + return Promise.try(action) + .then((result) => console.log(result)) + .catch((error) => console.error(error)) + .finally(() => console.log("Done")); +} + +doSomething(() => "Sync result"); + +doSomething(() => { + throw new Error("Sync error"); +}); + +doSomething(async () => "Async result"); + +doSomething(async () => { + throw new Error("Async error"); +}); +``` + +async/await では、同じコードは次のようになります。 + +```js +async function doSomething(action) { + try { + const result = await action(); + console.log(result); + } catch (error) { + console.error(error); + } finally { + console.log("Done"); + } +} +``` + +### Promise 以外のコンストラクターにおける try() の呼び出し + +`Promise.try()` は汎用メソッドです。これは、`Promise()` コンストラクターと同じシグネチャを実装する任意のコンストラクターで呼び出すことができます。 + +以下は、実際の `Promise.try()` にやや忠実な近似表現です（ただし、やはりこれはポリフィルとして使用すべきではありません）。 + +```js +Promise.try = function (func) { + return new this((resolve, reject) => { + try { + resolve(func()); + } catch (error) { + reject(error); + } + }); +}; +``` + +`Promise.try()` の実装方法（つまり、`try...catch`）により、`this` を任意のカスタムコンストラクターに設定して `Promise.try()` を安全に呼び出すことができ、同期してエラーが発生することはありません。 + +```js +class NotPromise { + constructor(executor) { + // The "resolve" and "reject" functions behave nothing like the native + // promise's, but Promise.try() just calls resolve + executor( + (value) => console.log("Resolved", value), + (reason) => console.log("Rejected", reason), + ); + } +} + +const p = Promise.try.call(NotPromise, () => "hello"); +// Logs: Resolved hello + +const p2 = Promise.try.call(NotPromise, () => { + throw new Error("oops"); +}); +// Logs: Rejected Error: oops +``` + +`Promise()` とは異なり、この `NotPromise()` コンストラクターは、executor を実行する際に例外を適切に処理しません。しかし、`throw`が発生しても、`Promise.try()` は例外を捕捉し、それを `reject()` に渡してログ出力します。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [`Promise.try` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#promisetry) +- [プロミスの使用](/ja/docs/Web/JavaScript/Guide/Using_promises)ガイド +- {{jsxref("Promise")}} +- [`Promise()` コンストラクター](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) From e16fcd6ff2d6bb13d83d849f2c798f4709536640 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 01:09:04 +0900 Subject: [PATCH 007/221] =?UTF-8?q?2024/07/18=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../global_objects/promise/then/index.md | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/promise/then/index.md b/files/ja/web/javascript/reference/global_objects/promise/then/index.md index ce54f99cc27463..379799b27b00d9 100644 --- a/files/ja/web/javascript/reference/global_objects/promise/then/index.md +++ b/files/ja/web/javascript/reference/global_objects/promise/then/index.md @@ -2,12 +2,12 @@ title: Promise.prototype.then() slug: Web/JavaScript/Reference/Global_Objects/Promise/then l10n: - sourceCommit: 3918b803fda416a26fc2b7a62976d2cd87187460 + sourceCommit: 5c55770dc681e7855fe960cf6a725d4c7be4e95f --- {{JSRef}} -**`then()`** は {{jsxref("Promise")}} インスタンスのメソッドであり、最大 2 つの引数として、この `Promise` が成功した場合と失敗した場合のコールバック関数を取ります。これは直ちに同等の {{jsxref("Promise")}} オブジェクトを返し、他のプロミスのメソッドに対する[連鎖](/ja/docs/Web/JavaScript/Guide/Using_promises#連鎖)呼び出しを行うことができます。 +**`then()`** は {{jsxref("Promise")}} インスタンスのメソッドであり、最大 2 つの引数として、この `Promise` が成功した場合と失敗した場合のコールバック関数を取ります。コールバックは、それが呼び出されたプロミス内に格納され、すぐに別の {{jsxref("Promise")}} オブジェクトを返値において返し、他のプロミスのメソッドに対する[連鎖](/ja/docs/Web/JavaScript/Guide/Using_promises#連鎖)呼び出しを行うことができます。 {{EmbedInteractiveExample("pages/js/promise-then.html")}} @@ -57,11 +57,21 @@ then(onFulfilled, onRejected) `onRejected` ハンドラーの詳細については、 {{jsxref("Promise/catch", "catch()")}} のリファレンスを参照してください。 -`then()` は、新しいプロミスオブジェクトを返すことです。同じプロミスオブジェクトで `then()` メソッドを 2 回呼び出すと（連鎖するのではなく）、このプロミスオブジェクトは 2 組の決定ハンドラーを保有することになります。同じプロミスオブジェクトに付けられたすべてのハンドラーは、常に追加された順番に呼び出されます。さらに、 `then()` の各呼び出しによって返される 2 つのプロミスは、別個の連鎖を始め、お互いの決定を待つことはありません。 +`then()` は新しいプロミスオブジェクトを返しますが、呼び出されたプロミスオブジェクトを変更し、ハンドラーを内部リストに追加します。 したがって、ハンドラーは元のプロミスによって保持され、その寿命は少なくとも元のプロミスの寿命と同じ長さになります。 例えば、次の例では、返されたプロミスが保持されないにもかかわらず、最終的にはメモリーを使い果たします。 -`then()` チェーンに沿って発生する [Thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables) オブジェクトは常に[解決](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise#resolver_function)されます。`onFulfilled` ハンドラーは thenable オブジェクトを決して受け取らず、いずれかのハンドラーによって返される thenable は常に次のハンドラーに渡される前に解決されます。これは、新しいプロミスを構築するときに、 `executor` から渡された `resolve` 関数と `reject` 関数が保存され、現在のプロミスが決定したときに、それぞれの関数が履行された値または拒絶の理由とともに呼び出されるからです。解決ロジックは、 {{jsxref("Promise/Promise", "Promise()")}} コンストラクターから渡されるリゾルバー関数から決まります。 +```js +const pendingPromise = new Promise(() => {}); +while (true) { + pendingPromise.then(doSomething); +} +``` + +`then()` は、新しいプロミスオブジェクトを返すことです。 +同じプロミスオブジェクトで `then()` メソッドを 2 回呼び出すと（連鎖するのではなく）、このプロミスオブジェクトは 2 組の決定ハンドラーを保有することになります。同じプロミスオブジェクトに付けられたすべてのハンドラーは、常に追加された順番に呼び出されます。さらに、 `then()` の各呼び出しによって返される 2 つのプロミスは、別個の連鎖を始め、お互いの決定を待つことはありません。 + +`then()` チェーンに沿って発生する [Thenable](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenable) オブジェクトは常に[解決](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise#resolver_function)されます。`onFulfilled` ハンドラーは thenable オブジェクトを決して受け取らず、いずれかのハンドラーによって返される thenable は常に次のハンドラーに渡される前に解決されます。これは、新しいプロミスを構築するときに、 `executor` から渡された `resolve` 関数と `reject` 関数が保存され、現在のプロミスが決定したときに、それぞれの関数が履行された値または拒絶の理由とともに呼び出されるからです。解決ロジックは、 {{jsxref("Promise/Promise", "Promise()")}} コンストラクターから渡されるリゾルバー関数から決まります。 -`then()` はサブクラス化に対応しており、`Promise` のサブクラスのインスタンスに対して呼び出すことができ、その結果はサブクラスの型のプロミスになります。返す値の種類は [`@@species`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/@@species) プロパティでカスタマイズすることができます。 +`then()` はサブクラス化に対応しており、`Promise` のサブクラスのインスタンスに対して呼び出すことができ、その結果はサブクラスの型のプロミスになります。返す値の種類は [`[Symbol.species]`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/Symbol.species) プロパティでカスタマイズすることができます。 ## 例 From 2eeb4b09d60ff267e8d07b70d03b22f8239fbeea Mon Sep 17 00:00:00 2001 From: contradiction29 Date: Sat, 12 Oct 2024 16:13:21 +0900 Subject: [PATCH 008/221] Translation: Add glossary for LCP --- .../largest_contentful_paint/index.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 files/ja/glossary/largest_contentful_paint/index.md diff --git a/files/ja/glossary/largest_contentful_paint/index.md b/files/ja/glossary/largest_contentful_paint/index.md new file mode 100644 index 00000000000000..862fa544147651 --- /dev/null +++ b/files/ja/glossary/largest_contentful_paint/index.md @@ -0,0 +1,25 @@ +--- +title: Largest contentful paint +slug: Glossary/Largest_contentful_paint +l10n: + sourceCommit: 8bbefa76803785b6e0e1d278679c38b092e6b234 +--- + +{{GlossarySidebar}} + +**Largest Contentful Paint (LCP)** はウェブサイトのユーザビリティを測定する指標であり、Google が [Core Web Vitals](https://web.dev/explore/learn-core-web-vitals) を構成する指標群の一つとして設計しました。LCP は、ブラウザーがページの読み込みを開始してから、ビューポート内で視認可能な最大の画像またはテキストブロックのレンダリングが完了するまでの時間を測定します。 + +LCP を決定する要素の例として、以下が挙げられます : + +- {{HTMLElement("img")}} 要素 +- SVG 内の [``](/ja/docs/Web/SVG/Element/image) 要素 +- {{HTMLElement("video")}} 要素のポスター画像 +- {{cssxref("background-image")}} が設定された要素 +- {{HTMLElement("p")}} などのテキストノードのまとまり + +## 関連情報 + +- [`LargestContentfulPaint`](/ja/docs/Web/API/LargestContentfulPaint) +- web.dev 上の [LCP](https://web.dev/articles/lcp) +- {{Glossary("First contentful paint")}} +- {{Glossary("First paint")}} From 057931e6dc847648c14cfc5d4dede4c1896efd5c Mon Sep 17 00:00:00 2001 From: Alexander <83426363+darchrow820@users.noreply.github.com> Date: Sun, 13 Oct 2024 12:10:16 +0300 Subject: [PATCH 009/221] Update index.md (#23972) Fixed some typos --- files/ru/web/javascript/reference/statements/var/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/files/ru/web/javascript/reference/statements/var/index.md b/files/ru/web/javascript/reference/statements/var/index.md index a9b786a0cee6b6..7012e702935622 100644 --- a/files/ru/web/javascript/reference/statements/var/index.md +++ b/files/ru/web/javascript/reference/statements/var/index.md @@ -5,7 +5,7 @@ slug: Web/JavaScript/Reference/Statements/var {{jsSidebar("Statements")}} -Оператор **var** объявляет переменную, инициализируя её, при необходимости. +Оператор **var** объявляет переменную, инициализируя её при необходимости. {{EmbedInteractiveExample("pages/js/statement-var.html")}} @@ -25,7 +25,7 @@ var varname1 [= value1 [, varname2 [, varname3 ... [, varnameN]]]]; ## Описание -Объявление переменной всегда обрабатывается до выполнения кода, где бы она ни находилась. Область видимости переменной, объявленной через `var`, это её текущий _контекст выполнения_. Который может ограничиваться функцией или быть глобальным, для переменных, объявленных за пределами функции. +Объявление переменной всегда обрабатывается до выполнения кода, где бы она ни находилась. Область видимости переменной, объявленной через `var`, это её текущий _контекст выполнения_. Который может ограничиваться функцией или быть глобальным для переменных, объявленных за пределами функции. Присвоение значения необъявленной переменной подразумевает, что она будет создана как глобальная переменная (переменная становится свойством глобального объекта) после выполнения присваивания значения. Различия между объявленной и необъявленной переменными следующие: @@ -73,7 +73,7 @@ console.log(a, b); // Возбудит ReferenceError. ### Поднятие переменных -Объявление переменных (как и любые другие объявления) обрабатываются до выполнения кода. Где бы не находилось объявление, это равнозначно тому, что переменную объявили в самом начале кода. Это значит, что переменная становится доступной до того, как она объявлена. Такое поведение называется "поднятием" (в некоторых источниках "всплытием"). +Объявление переменных (как и любые другие объявления) обрабатываются до выполнения кода. Где бы ни находилось объявление, это равнозначно тому, что переменную объявили в самом начале кода. Это значит, что переменная становится доступной до того, как она объявлена. Такое поведение называется "поднятием" (в некоторых источниках "всплытием"). ```js bla = 2; @@ -86,7 +86,7 @@ var bla; bla = 2; ``` -Поэтому объявление переменных рекомендовано выносить в начало их области видимости (в начало глобального кода или в начало функции). Это даёт понять какие переменные принадлежат функции (т.е. являются локальными), а какие обрабатываются в цепи областей видимости (т.е. являются глобальными). +Поэтому объявление переменных рекомендовано выносить в начало их области видимости (в начало глобального кода или в начало функции). Это даёт понять, какие переменные принадлежат функции (т.е. являются локальными), а какие обрабатываются в цепи областей видимости (т.е. являются глобальными). Важно отметить, что подъем будет влиять на объявление переменной, но не на инициализацию её значения. Значение присваивается при выполнении оператора присваивания: From 60fbc0fa3e4cbf19f34e7501c4d28ed0a7a66a5a Mon Sep 17 00:00:00 2001 From: Anton Date: Sun, 13 Oct 2024 12:11:47 +0300 Subject: [PATCH 010/221] [ru] Update box-sizing: change position-relative to position: relative (#23961) Update position --- files/ru/web/css/box-sizing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/ru/web/css/box-sizing/index.md b/files/ru/web/css/box-sizing/index.md index bfa897562778d9..35510851ffa8bb 100644 --- a/files/ru/web/css/box-sizing/index.md +++ b/files/ru/web/css/box-sizing/index.md @@ -16,7 +16,7 @@ slug: Web/CSS/box-sizing - `content-box` даёт стандартное поведение свойства box-sizing. Если вы выставите элементу ширину 100 пикселей, то ширина его контента будет 100 пикселей, а ширина границ и внутренних отступов при рендере будет добавлена к финальной ширине, делая элемент шире ста пикселей. - `border-box` говорит браузеру учитывать любые границы и внутренние отступы в значениях, которые вы указываете в ширине и высоте элемента. Если вы выставите элементу ширину 100 пикселей, то эти 100 пикселей будут включать в себя границы и внутренние отступы, а контент сожмётся, чтобы выделить для них место. Обычно это упрощает работу с размерами элементов. -> **Примечание:**Часто выставление `box-sizing: border-box` полезно для размещения элементов. Оно сильно упрощает работу с размерами элементов, и как правило устраняет ряд подводных камней, на которые вы можете наткнуться, размещая контент. С другой стороны, используя `position-relative` или `position: absolute`, `box-sizing: content-box` позволяет позиционным значениям быть зависимыми только от контента, а не от границ и отступов, что иногда желательно. +> **Примечание:**Часто выставление `box-sizing: border-box` полезно для размещения элементов. Оно сильно упрощает работу с размерами элементов, и как правило устраняет ряд подводных камней, на которые вы можете наткнуться, размещая контент. С другой стороны, используя `position: relative` или `position: absolute`, `box-sizing: content-box` позволяет позиционным значениям быть зависимыми только от контента, а не от границ и отступов, что иногда желательно. ## Синтаксис From d0df5af968337b8769e16a51e7836ea9127dc281 Mon Sep 17 00:00:00 2001 From: alattalatta Date: Sun, 13 Oct 2024 20:00:33 +0900 Subject: [PATCH 011/221] =?UTF-8?q?[ko]=20showDirectoryPicker,=20showOpenF?= =?UTF-8?q?ilePicker,=20showSaveFilePicker=20=EB=B2=88=EC=97=AD=20(#23977)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * showopenfilepicker * showsavefilepicker * showdirectorypicker * 디렉토리 -> 디렉터리 통일 * showdirectorypicker: rephrase mode option * Adjust writing style of TypeError cases * Update files/ko/web/api/window/showdirectorypicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showsavefilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showsavefilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showsavefilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showsavefilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showdirectorypicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showdirectorypicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showdirectorypicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showdirectorypicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showopenfilepicker/index.md Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Apply suggestions from code review Co-authored-by: 1ilsang <1ilsangc@gmail.com> * Update files/ko/web/api/window/showdirectorypicker/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: 1ilsang <1ilsangc@gmail.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../api/window/showdirectorypicker/index.md | 78 ++++++++++++ .../api/window/showopenfilepicker/index.md | 120 ++++++++++++++++++ .../api/window/showsavefilepicker/index.md | 103 +++++++++++++++ 3 files changed, 301 insertions(+) create mode 100644 files/ko/web/api/window/showdirectorypicker/index.md create mode 100644 files/ko/web/api/window/showopenfilepicker/index.md create mode 100644 files/ko/web/api/window/showsavefilepicker/index.md diff --git a/files/ko/web/api/window/showdirectorypicker/index.md b/files/ko/web/api/window/showdirectorypicker/index.md new file mode 100644 index 00000000000000..e16645b4519be0 --- /dev/null +++ b/files/ko/web/api/window/showdirectorypicker/index.md @@ -0,0 +1,78 @@ +--- +title: "Window: showDirectoryPicker() 메서드" +short-title: showDirectoryPicker() +slug: Web/API/Window/showDirectoryPicker +l10n: + sourceCommit: 4458494807b6f4898d504b6c0af0a45f8031cbf3 +--- + +{{APIRef("File System API")}}{{Securecontext_Header}}{{SeeCompatTable}} + +{{domxref("Window")}} 인터페이스의 **`showDirectoryPicker()`** 메서드는 +사용자가 디렉터리 한 개를 선택할 수 있는 +디렉터리 선택창을 엽니다. + +## 구문 + +```js-nolint +showDirectoryPicker() +``` + +### 매개변수 + +- `options` {{optional_inline}} + + - : 아래의 옵션을 포함하는 객체입니다. + + - `id` {{optional_inline}} + - : ID를 지정하면 브라우저가 선택창의 ID마다 마지막으로 탐색한 디렉터리를 기억합니다. + 다른 선택창에서 같은 ID를 사용한다면, 이전에 해당 ID로 탐색했던 디렉터리에서 + 선택창이 열립니다. + - `mode` {{optional_inline}} + - : 디렉터리에 대한 읽기 전용 접근 시 `"read"`, 읽기와 쓰기 모두 가능한 접근 시 `"readwrite"`이어야 합니다. + 기본 값은 `"read"`입니다. + - `startIn` {{optional_inline}} + - : 선택창이 열릴 때의 최초 디렉터리를 가리키는 `FileSystemHandle`, 또는 널리 알려진 디렉터리 식별자(`"desktop"`, `"documents"`, `"downloads"`, `"music"`, `"pictures"`, 또는 `"videos"`)입니다. + +### 반환 값 + +{{domxref('FileSystemDirectoryHandle')}} 객체로 이행하는 {{jsxref("Promise")}}. + +### 예외 + +- `AbortError` {{domxref("DOMException")}} + - : 사용자가 디렉터리를 선택하지 않고 선택창을 닫았을 때, + 사용자 에이전트가 판단했을 때 디렉터리가 너무 민감하거나 위험할 때, 또는 지정한 `mode` 옵션에 대해 + 선택한 디렉터리의 {{domxref('PermissionStatus.state')}}가 `"granted"`가 아닐 때 발생합니다. +- `SecurityError` {{domxref("DOMException")}} + - : [동일 출처 정책](/ko/docs/Web/Security/Same-origin_policy)에 의해 호출이 차단됐거나, 버튼 클릭과 같은 사용자 상호작용에 의해 호출된 것이 아니라면 발생합니다. + +## 보안 + +[사용자의 임시 활성화](/ko/docs/Web/Security/User_activation)가 필요합니다. 이 기능이 동작하려면 사용자가 페이지 또는 UI 요소와 상호작용해야 합니다. + +## 예제 + +다음 비동기 함수는 디렉터리 선택창을 열고, 사용자가 디렉터리를 선택한 후에 +{{domxref('FileSystemDirectoryHandle')}}를 반환합니다. + +```js +async function getDir() { + const dirHandle = await window.showDirectoryPicker(); + + // dirHandle을 사용하는 코드들 +} +``` + +## 명세서 + +{{Specifications}} + +## 브라우저 호환성 + +{{Compat}} + +## 같이 보기 + +- [File System API](/ko/docs/Web/API/File_System_API) +- [The File System Access API: simplifying access to local files](https://developer.chrome.com/docs/capabilities/web-apis/file-system-access) diff --git a/files/ko/web/api/window/showopenfilepicker/index.md b/files/ko/web/api/window/showopenfilepicker/index.md new file mode 100644 index 00000000000000..f8406797f66f76 --- /dev/null +++ b/files/ko/web/api/window/showopenfilepicker/index.md @@ -0,0 +1,120 @@ +--- +title: "Window: showOpenFilePicker() 메서드" +short-title: showOpenFilePicker() +slug: Web/API/Window/showOpenFilePicker +l10n: + sourceCommit: 4458494807b6f4898d504b6c0af0a45f8031cbf3 +--- + +{{APIRef("File System API")}}{{SecureContext_Header}}{{SeeCompatTable}} + +{{domxref("Window")}} 인터페이스의 **`showOpenFilePicker()`** 메서드는 +사용자가 파일 한 개 또는 여러 개를 선택할 수 있는 파일 선택창을 열고 +선택한 파일들의 핸들을 반환합니다. + +## 구문 + +```js-nolint +showOpenFilePicker() +``` + +### 매개변수 + +- `options` {{Optional_Inline}} + + - : 아래의 옵션을 포함하는 객체입니다. + + - `excludeAcceptAllOption` {{Optional_Inline}} + - : 기본 값 `false`인 불리언입니다. + 기본적으로 파일 선택창에는 파일 유형 필터(아래의 `type` 참고)를 + 적용하지 않는 옵션이 존재합니다. + 이 옵션을 `true`로 설정하면 사용자가 해당 옵션을 선택할 수 없습니다. + - `id` {{Optional_Inline}} + - : ID를 지정하면 브라우저가 선택창의 ID마다 마지막으로 탐색한 디렉터리를 기억합니다. + 다른 선택창에서 같은 ID를 사용한다면, 이전에 해당 ID로 탐색했던 디렉터리에서 + 선택창이 열립니다. + - `multiple` {{Optional_Inline}} + - : 기본 값 `false`인 불리언입니다. + `true`로 설정 시 여러 파일을 선택할 수 있습니다. + - `startIn` {{Optional_Inline}} + - : 선택창이 열릴 때의 최초 디렉터리를 가리키는 `FileSystemHandle`, 또는 널리 알려진 디렉터리 식별자(`"desktop"`, `"documents"`, `"downloads"`, `"music"`, `"pictures"`, 또는 `"videos"`)입니다. + - `types` {{Optional_Inline}} + + - : 선택 가능한 파일 유형들의 {{jsxref('Array')}}입니다. + 각 요소는 아래의 옵션을 포함하는 객체입니다. + + - `description` {{Optional_Inline}} + - : 사용 가능한 파일 유형에 대한 설명입니다. 기본 값은 빈 문자열입니다. + - `accept` + - : 키는 [MIME 유형](/ko/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)이고 값은 파일 확장자들의 {{jsxref('Array')}}인 {{jsxref('Object')}}입니다 + (아래 예제를 참고하세요). + +### 반환 값 + +{{domxref('FileSystemFileHandle')}} 객체들의 {{jsxref('Array')}}로 이행하는 {{jsxref("Promise")}}. + +### 예외 + +- `AbortError` {{domxref("DOMException")}} + - : 사용자가 파일을 선택하지 않고 선택창을 닫았을 때, 또는 사용자 에이전트가 판단했을 때 + 파일이 너무 민감하거나 위험할 때 발생합니다. +- `SecurityError` {{domxref("DOMException")}} + - : [동일 출처 정책](/ko/docs/Web/Security/Same-origin_policy)에 의해 호출이 차단됐거나, 버튼 클릭과 같은 사용자 상호작용에 의해 호출된 것이 아니라면 발생합니다. +- {{jsxref("TypeError")}} + - : 다음과 같은 상황에 의해 허용하는 파일 유형을 처리할 수 없으면 발생합니다. + - `types` 옵션의 `accept` 옵션 내 어떤 키가 유효한 MIME 유형이 아닌 경우. + - `types` 옵션의 `accept` 옵션 내 어떤 값이 유효하지 않은 경우, 예컨대 `.`로 시작하지 않거나, `.`로 끝나거나, 유효하지 않은 코드 포인트를 포함하거나, 길이가 16 초과할 때. + - `types` 옵션이 비어있는데 `excludeAcceptAllOption` 옵션이 `true`인 경우. + +## 보안 + +[사용자의 임시 활성화](/ko/docs/Web/Security/User_activation)가 필요합니다. 이 기능이 동작하려면 사용자가 페이지 또는 UI 요소와 상호작용해야 합니다. + +## 예제 + +다음 코드에서는 `showOpenFilePicker()` 메서드에 전달할 옵션 객체를 정의합니다. +이미지 파일 유형을 선택할 수 있고, 모든 파일 유형 허용 옵션이나 다중 선택은 +비활성화합니다. + +```js +const pickerOpts = { + types: [ + { + description: "Images", + accept: { + "image/*": [".png", ".gif", ".jpeg", ".jpg"], + }, + }, + ], + excludeAcceptAllOption: true, + multiple: false, +}; +``` + +다음으로는 파일 선택창을 열고 선택한 파일을 반환하는 비동기 함수를 +생성합니다. + +```js +// 파일 핸들 참조 생성 +let fileHandle; + +async function getFile() { + // 파일 선택창을 열고, 반환 배열의 첫 번째 값을 가져오기 위해 구조 분해 + [fileHandle] = await window.showOpenFilePicker(pickerOpts); + + // 파일 핸들을 사용하는 코드들 +} +``` + +## 명세서 + +{{Specifications}} + +## 브라우저 호환성 + +{{Compat}} + +## 같이 보기 + +- [File System API](/ko/docs/Web/API/File_System_API) +- [The File System Access API: simplifying access to local files](https://developer.chrome.com/docs/capabilities/web-apis/file-system-access) diff --git a/files/ko/web/api/window/showsavefilepicker/index.md b/files/ko/web/api/window/showsavefilepicker/index.md new file mode 100644 index 00000000000000..465949c3cbbaad --- /dev/null +++ b/files/ko/web/api/window/showsavefilepicker/index.md @@ -0,0 +1,103 @@ +--- +title: "Window: showSaveFilePicker() 메서드" +short-title: showSaveFilePicker() +slug: Web/API/Window/showSaveFilePicker +l10n: + sourceCommit: 4458494807b6f4898d504b6c0af0a45f8031cbf3 +--- + +{{APIRef("File System API")}}{{SecureContext_Header}}{{SeeCompatTable}} + +{{domxref("Window")}} 인터페이스의 **`showSaveFilePicker()`** 메서드는 사용자가 +기존 파일을 선택하거나, 새로운 파일 이름을 입력해서 파일을 저장할 수 있는 +선택창을 엽니다. + +## 구문 + +```js-nolint +showSaveFilePicker() +``` + +### 매개변수 + +- `options` {{Optional_Inline}} + + - : 아래의 옵션을 포함하는 객체입니다. + + - `excludeAcceptAllOption` {{Optional_Inline}} + - : 기본 값 `false`인 불리언입니다. + 기본적으로 파일 선택창에는 파일 유형 필터(아래의 `type` 참고)를 + 적용하지 않는 옵션이 존재합니다. 이 옵션을 `true`로 설정하면 + 사용자가 해당 옵션을 선택할 수 없습니다. + - `id` {{Optional_Inline}} + - : ID를 지정하면 브라우저가 선택창의 ID마다 마지막으로 탐색한 디렉터리를 기억합니다. + 다른 선택창에서 같은 ID를 사용한다면, 이전에 해당 ID로 탐색했던 디렉터리에서 + 선택창이 열립니다. + - `startIn` {{Optional_Inline}} + - : 선택창이 열릴 때의 최초 디렉터리를 가리키는 `FileSystemHandle`, 또는 널리 알려진 디렉터리 식별자(`"desktop"`, `"documents"`, + `"downloads"`, `"music"`, `"pictures"`, 또는 `"videos"`)입니다. + - `suggestedName` {{Optional_Inline}} + - : 추천하는 파일 이름을 지정하는 {{jsxref('String')}}입니다. + - `types` {{Optional_Inline}} + + - : 저장 가능한 파일 유형들의 {{jsxref('Array')}}입니다. + 각 요소는 아래의 옵션을 포함하는 객체입니다. + + - `description` {{Optional_Inline}} + - : 사용 가능한 파일 유형에 대한 설명입니다. + 기본 값은 빈 문자열입니다. + - `accept` + - : 키는 [MIME 유형](/ko/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)이고 값은 파일 확장자들의 {{jsxref('Array')}}인 {{jsxref('Object')}}입니다 + (아래 예제를 참고하세요). + +### 반환 값 + +{{domxref('FileSystemFileHandle')}} 객체로 이행하는 {{jsxref("Promise")}}. + +### 예외 + +- `AbortError` {{domxref("DOMException")}} + - : 사용자가 파일을 선택하지 않고 선택창을 닫았을 때, 또는 사용자 에이전트가 판단했을 때 + 파일이 너무 민감하거나 위험할 때 발생합니다. + - `SecurityError` {{domxref("DOMException")}} + - : [동일 출처 정책](/ko/docs/Web/Security/Same-origin_policy)에 의해 호출이 차단됐거나, 버튼 클릭과 같은 사용자 상호작용에 의해 호출된 것이 아니라면 발생합니다. +- {{jsxref("TypeError")}} + - : 다음과 같은 상황에 의해 허용하는 파일 유형을 처리할 수 없으면 발생합니다. + - `types` 옵션의 `accept` 옵션 내 어떤 키가 유효한 MIME 유형이 아닌 경우. + - `types` 옵션의 `accept` 옵션 내 어떤 값이 유효하지 않은 경우, 예컨대 `.`로 시작하지 않거나, `.`로 끝나거나, 유효하지 않은 코드 포인트를 포함하거나, 길이가 16 초과할 때. + - `types` 옵션이 비어있는데 `excludeAcceptAllOption` 옵션이 `true`인 경우. + +## 보안 + +[사용자의 임시 활성화](/ko/docs/Web/Security/User_activation)가 필요합니다. 이 기능이 동작하려면 사용자가 페이지 또는 UI 요소와 상호작용해야 합니다. + +## 예제 + +다음 코드는 텍스트 파일들을 선택할 수 있는 파일 선택창을 엽니다. + +```js +async function getNewFileHandle() { + const opts = { + types: [ + { + description: "Text file", + accept: { "text/plain": [".txt"] }, + }, + ], + }; + return await window.showSaveFilePicker(opts); +} +``` + +## 명세서 + +{{Specifications}} + +## 브라우저 호환성 + +{{Compat}} + +## 같이 보기 + +- [File System API](/ko/docs/Web/API/File_System_API) +- [The File System Access API: simplifying access to local files](https://developer.chrome.com/docs/capabilities/web-apis/file-system-access) From ea0b454a9a36256304cbe1af49ed796ca526ca0d Mon Sep 17 00:00:00 2001 From: SphinxKnight Date: Sun, 13 Oct 2024 20:07:13 +0200 Subject: [PATCH 012/221] Follow-up of #23776 (#23963) * Fix #23767 * minor changes * http to https * Minor review for #23776 * Apply typofix suggestion from @cw118 Co-authored-by: Carolyn Wu <87150472+cw118@users.noreply.github.com> --------- Co-authored-by: Quentin <59255702+quentin-rey@users.noreply.github.com> Co-authored-by: Carolyn Wu <87150472+cw118@users.noreply.github.com> --- files/fr/glossary/unicode/index.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/files/fr/glossary/unicode/index.md b/files/fr/glossary/unicode/index.md index a71e55a90ac010..10a02a288f38d3 100644 --- a/files/fr/glossary/unicode/index.md +++ b/files/fr/glossary/unicode/index.md @@ -1,19 +1,21 @@ --- title: Unicode slug: Glossary/Unicode +l10n: + sourceCommit: eb061bd719102c148cf87d12fd7056ed0c5071c8 --- {{GlossarySidebar}} Unicode est un {{Glossary("Character set","jeu de caractères")}} standard qui énumère et définit les {{Glossary("Character","caractères")}} des différentes langues du monde, systèmes d'écriture et symboles. -En attribuant un nombre à chaque caractère, les programmeurs peuvent {{Glossary("Character encoding", "encoder des caractères")}}, pour permettre aux ordinateurs de stocker, traiter et transmettre toute combinaison de langues dans le même fichier ou programme. +En attribuant un nombre à chaque caractère, les développeuses et développeurs peuvent {{Glossary("Character encoding", "encoder des caractères")}}, pour permettre aux ordinateurs de stocker, traiter et transmettre toute combinaison de langues dans le même fichier ou programme. -Avant Unicode, il était difficile et sujet aux erreurs de mélanger les langues dans les mêmes données. Par exemple, un jeu de caractères stockait des caractères japonais et un autre l'alphabet arabe. S'il n'était pas clairement indiqué quelles parties des données étaient dans quel jeu de caractères, d'autres programmes et ordinateurs affichaient incorrectement le texte ou l'endommageaient pendant le traitement. Si vous avez déjà vu du texte où des caractères comme des citations entre guillemets en cursives (`“”`) remplacés par du charabia comme `£`,alors vous avez vu ce problème, connu sous le nom [Mojibake](https://fr.wikipedia.org/wiki/Mojibake). +Avant Unicode, il était difficile et sujet aux erreurs de mélanger les langues dans les mêmes données. Par exemple, un jeu de caractères stockait des caractères japonais et un autre l'alphabet arabe. S'il n'était pas clairement indiqué quelles parties des données appartenaient à quel jeu de caractères, d'autres programmes et ordinateurs affichaient incorrectement le texte ou l'endommageaient pendant le traitement. Si vous avez déjà vu du texte ou des caractères comme des citations entre guillemets anglais (“”) remplacés par du charabia comme `£`, alors vous avez vu ce problème, connu sous le nom [Mojibake](https://fr.wikipedia.org/wiki/Mojibake). L'encodage de caractères Unicode le plus courant sur le Web est {{Glossary("UTF-8")}}. D'autres encodages existent, comme UTF-16 ou l'obsolète UCS-2, mais UTF-8 est recommandé. ## Voir aussi - [Unicode](https://fr.wikipedia.org/wiki/Unicode) sur Wikipédia -- [The Unicode Standard : A Technical Introduction](https://www.unicode.org/standard/principles.html) (en) +- [The Unicode Standard: A Technical Introduction](https://www.unicode.org/standard/principles.html) (en anglais) From a1b72e5fec39bb339689b26174749eb71c6cd686 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 23:24:46 +0900 Subject: [PATCH 013/221] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../global_objects/string/charat/index.md | 6 +- .../reference/global_objects/string/index.md | 78 ++++++++++--------- .../global_objects/string/match/index.md | 10 +-- .../global_objects/string/replace/index.md | 24 +++--- .../global_objects/string/split/index.md | 10 +-- 5 files changed, 65 insertions(+), 63 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/string/charat/index.md b/files/ja/web/javascript/reference/global_objects/string/charat/index.md index 05ba1bf3a96ed0..df26bcc41a5ba8 100644 --- a/files/ja/web/javascript/reference/global_objects/string/charat/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/charat/index.md @@ -2,7 +2,7 @@ title: String.prototype.charAt() slug: Web/JavaScript/Reference/Global_Objects/String/charAt l10n: - sourceCommit: 6d606174faaedaa5dee7b7ebd87602cd51e5dd7e + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} @@ -79,7 +79,7 @@ console.log(str.charAt(0)); // "\ud842"、これは妥当な Unicode 文字で console.log(str.charAt(1)); // "\udfb7"、これは妥当な Unicode 文字ではない ``` -指定された位置の完全な Unicode コードポイントを取得するには、{{jsxref("String.prototype.codePointAt()")}} や[スプレッド構文](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator)のように、Unicode コードポイントで分割して Unicode コードポイントの配列にするインデックスメソッドを使用してください +指定された位置の完全な Unicode コードポイントを取得するには、{{jsxref("String.prototype.codePointAt()")}} や[スプレッド構文](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator)のように、Unicode コードポイントで分割して Unicode コードポイントの配列にするインデックスメソッドを使用してください ```js const str = "𠮷𠮾"; @@ -105,4 +105,4 @@ console.log([...str][0]); // "𠮷" - {{jsxref("String.prototype.codePointAt()")}} - {{jsxref("String.prototype.split()")}} - {{jsxref("String.fromCodePoint()")}} -- [JavaScript has a Unicode problem – Mathias Bynens](https://mathiasbynens.be/notes/javascript-unicode) +- [JavaScript has a Unicode problem](https://mathiasbynens.be/notes/javascript-unicode) (Mathias Bynens, 2013) diff --git a/files/ja/web/javascript/reference/global_objects/string/index.md b/files/ja/web/javascript/reference/global_objects/string/index.md index 02a7a922388d71..466772082cf81e 100644 --- a/files/ja/web/javascript/reference/global_objects/string/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/index.md @@ -2,7 +2,7 @@ title: String slug: Web/JavaScript/Reference/Global_Objects/String l10n: - sourceCommit: 270351317fdaa57ba9123a19aa281e9e40bb0baa + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} @@ -11,7 +11,7 @@ l10n: ## 解説 -文字列は、テキスト形式で表現可能なデータを保持するのに便利です。最もよく使われる操作として、文字列の長さをチェックする {{jsxref("String/length", "length")}} プロパティ、 [文字列に対する + および += 演算子](/ja/docs/Web/JavaScript/Guide/Expressions_and_operators#文字列演算子)を用いた文字列の連結、文字列の中の部分文字列の存在や位置をチェックする {{jsxref("String.prototype.indexOf()", "indexOf()")}} メソッド、部分文字列を取り出す {{jsxref("String.prototype.substring()", "substring()")}} メソッドが挙げられます。 +文字列は、テキスト形式で表現可能なデータを保持するのに便利です。最もよく使われる操作として、文字列の長さをチェックする {{jsxref("String/length", "length")}} プロパティ、 [文字列に対する `+` および `+=` 演算子](/ja/docs/Web/JavaScript/Guide/Expressions_and_operators#文字列演算子)を用いた文字列の連結、文字列の中の部分文字列の存在や位置をチェックする {{jsxref("String/indexOf", "indexOf()")}} メソッド、部分文字列を取り出す {{jsxref("String/substring", "substring()")}} メソッドが挙げられます。 ### 文字列の生成 @@ -34,7 +34,7 @@ const string4 = new String("文字列オブジェクト"); ### 文字へのアクセス -文字列内の個々の文字へのアクセス方法には、2 通りの方法があります。そのひとつは {{jsxref("String.prototype.charAt()", "charAt()")}} メソッドです。 +文字列内の個々の文字へのアクセス方法には、2 通りの方法があります。そのひとつは {{jsxref("String/charAt", "charAt()")}} メソッドです。 ```js "ねこ".charAt(1); // "こ" が返される @@ -99,7 +99,7 @@ areEqual("ı", "I", "tr"); // true ### 文字列プリミティブと String オブジェクト -JavaScript では、 `String` オブジェクトと{{Glossary("Primitive", "プリミティブ文字列")}}は区別されることに注意してください。（{{jsxref("Boolean")}} や {{jsxref("Global_Objects/Number", "Number")}} にも同じことが言えます。） +JavaScript では、 `String` オブジェクトと{{Glossary("Primitive", "プリミティブ文字列")}}は区別されることに注意してください。（{{jsxref("Boolean")}} や {{jsxref("Number", "Number")}} にも同じことが言えます。） 文字列リテラル（二重引用符または単一引用符で示されます）、および `String` 関数をコンストラクター以外の場面で（すなわち {{jsxref("Operators/new", "new")}} キーワードを使わずに）呼び出した場合はプリミティブの文字列になります。 文字列プリミティブに対してメソッドを呼び出したり、プロパティを参照したりするコンテキストでは、JavaScript は自動的に文字列プリミティブをラップし、ラッパーオブジェクトに対してメソッドを呼び出したり、プロパティを参照したりします。 @@ -129,7 +129,7 @@ console.log(eval(s2)); // 文字列の "2 + 2" を返す こういった理由から、プリミティブの文字列を期待して実装されたコードは `String` オブジェクトでうまく動作しないことがあります。しかし、一般的にはこれらの違いを考慮しなければならないことはあまりありません。 -なお、`String` オブジェクトは {{jsxref("String.prototype.valueOf()", "valueOf()")}} メソッドを用いることで、プリミティブの文字列に変換することができます。 +なお、`String` オブジェクトは {{jsxref("String/valueOf", "valueOf()")}} メソッドを用いることで、プリミティブの文字列に変換することができます。 ```js console.log(eval(s2.valueOf())); // 数値の 4 を返す @@ -146,7 +146,7 @@ console.log(eval(s2.valueOf())); // 数値の 4 を返す - 数値は [`toString(10)`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Number/toString) と同じアルゴリズムで変換されます。 - [長整数](/ja/docs/Web/JavaScript/Reference/Global_Objects/BigInt)は [`toString(10)`](/ja/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toString) と同じアルゴリズムで変換されます。 - [シンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol)は {{jsxref("TypeError")}} が発生します。 -- オブジェクトは最初に[プリミティブに変換](/ja/docs/Web/JavaScript/Data_structures#primitive_coercion)され、これは [`[@@toPrimitive]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) を（`"string"` をヒントとして）呼び出すことで行われ、次に `toString()`、そして `valueOf()` メソッドがこの順序で呼び出されます。結果のプリミティブはそれから文字列に変換されます。 +- オブジェクトは最初に[プリミティブに変換](/ja/docs/Web/JavaScript/Data_structures#プリミティブ変換)され、これは [`[Symbol.toPrimitive]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) を（`"string"` をヒントとして）呼び出すことで行われ、次に `toString()`、そして `valueOf()` メソッドがこの順序で呼び出されます。結果のプリミティブはそれから文字列に変換されます。 JavaScript でほぼ同じ効果を得る方法はいくつかあります。 @@ -160,18 +160,18 @@ JavaScript でほぼ同じ効果を得る方法はいくつかあります。 文字列は基本的に [UTF-16 コード単位](https://ja.wikipedia.org/wiki/UTF-16)の並びとして表します。UTF-16 エンコーダーでは、すべてのコード単位は正確に 16 ビット長です。つまり、単一の UTF-16 コード単位として表現可能な文字は、最大で 216 個、つまり 65536 通りあります。この文字集合は[基本多言語面 (BMP)](https://ja.wikipedia.org/wiki/基本多言語面) と呼ばれ、ラテン語、ギリシャ語、キリル文字のような最も一般的な文字や多くの東アジアの文字を含みます。各コード単位は `u` の文字列の後にちょうど 4 つの 16 進数を続けて書くことができます。 -しかし、Unicode の文字集合全体は 65536 よりはるかにずっと大きいのです。追加の文字は UTF-16 でサロゲートペアとして格納されます。これは単一の文字を表す 16 ビットのコード単位のペアです。曖昧さを避けるために、ペアの 2 つの部分は `0xD800` と `0xDFFF` の間でなければならず、これらのコード単位は単一のコード単位の文字をエンコードするためには使用しません。（より正確には、高サロゲートは `0xD800` から `0xDBFF` までの値があり、低サロゲートは `0xDC00` から `0xDFFF` までの値があります）。各 Unicode 文字は、 1 つないし 2 つの UTF-16 コード単位から成っており、Unicode コードポイントとも呼ばれます。各 Unicode コードポイントは文字列の中で `\u{xxxxxx}` と書くことができ、ここで `xxxxxx` は 1-6 桁の 16 進数を表します。 +しかし、Unicode の文字集合全体は 65536 よりはるかにずっと大きいのです。追加の文字は UTF-16 でサロゲートペアとして格納されます。これは単一の文字を表す 16 ビットのコード単位のペアです。曖昧さを避けるために、ペアの 2 つの部分は `0xD800` と `0xDFFF` の間でなければならず、これらのコード単位は単一のコード単位の文字をエンコードするためには使用しません。（より正確に言えば、上位サロゲート（上位サロゲートコード単位とも呼ばれる）は、`0xD800`から`0xDBFF`（両端値を含む）までの値を持ち、下位サロゲート（下位サロゲートコード単位とも呼ばれる）は、`0xDC00` から `0xDFFF`（両端値を含む）までの値を持ちます。各 Unicode コードポイントは文字列の中で `\u{xxxxxx}` と書くことができ、ここで `xxxxxx` は 1-6 桁の 16 進数を表します。 「孤立サロゲート」とは、下記の記述のいずれかを満たす 16 ビットのコード単位です。 -- `0xD800` から `0xDBFF` までの範囲（つまり高サロゲート）にあるものの、文字列の最後のコード単位であるか、次のコード単位が低サロゲートではないもの。 -- `0xDC00` から `0xDFFF` までの範囲（つまり低サロゲート）にあるものの、文字列の最初のコード単位であるか、前のコード単位が高サロゲートではないもの。 +- `0xD800` から `0xDBFF` までの範囲（つまり上位サロゲート）にあるものの、文字列の最後のコード単位であるか、次のコード単位が下位サロゲートではないもの。 +- `0xDC00` から `0xDFFF` までの範囲（つまり下位サロゲート）にあるものの、文字列の最初のコード単位であるか、前のコード単位が上位サロゲートではないもの。 孤立サロゲートは Unicode 文字を表しません。すべて UTF-16 コード単位に基づいて動作するため、ほとんどの JavaScript 組み込みメソッドは正しく扱いますが、他のシステムとやりとりするとき、孤立サロゲートはしばしば有効な値ではありません。例えば、[`encodeURI()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) は孤立サロゲートがあると {{jsxref("URIError")}} が発生します。これは URI エンコーディングが UTF-8 エンコーディングを使用しており、孤立サロゲートに対するエンコーディングを持たないためです。孤立サロゲートを格納しない文字列は _well-formed_ 文字列と呼ばれ、UTF-16 を扱わない関数（`encodeURI()` や {{domxref("TextEncoder")}} など）で使用しても安全です。{{jsxref("String/isWellFormed", "isWellFormed()")}} メソッドで文字列が整形されているか調べたり、{{jsxref("String/toWellFormed", "toWellFormed()")}} メソッドで孤立サロゲートをサニタイズすることができます。 Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚単位として扱われるべき Unicode 文字並びがあります。最も一般的なケースは絵文字で、様々なバリエーションがある絵文字の多くは、実際には複数の絵文字で形成されており、たいていの場合、\ (`U+200D`) 文字で結合されています。 -どのレベルの文字を反復処理するのかに注意する必要があります。例えば、[`split("")`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/split) は UTF-16 コード単位で分割し、サロゲートペアを区切ります。文字列インデックスも各 UTF-16 コード単位のインデックスを参照します。他にも、[`@@iterator()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) はUnicode コードポイントで反復処理します。書記素クラスターを反復処理するには独自のコードが必要です。 +どのレベルの文字を反復処理するのかに注意する必要があります。例えば、[`split("")`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/split) は UTF-16 コード単位で分割し、サロゲートペアを区切ります。文字列インデックスも各 UTF-16 コード単位のインデックスを参照します。他にも、[`[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator) はUnicode コードポイントで反復処理します。書記素クラスターを反復処理するには独自のコードが必要です。 ```js "😄".split(""); // ['\ud83d', '\ude04']; 孤立サロゲートを 2 つに分割 @@ -194,7 +194,7 @@ Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚 ## コンストラクター - {{jsxref("String/String", "String()")}} - - : 新しい `String` オブジェクトを生成するために使用します。コンストラクターではなく関数として呼び出されたときは型変換を行うので、普通はより有用です。 + - : `String` オブジェクトを生成します。関数として呼び出された場合、`String` 型のプリミティブ値を返します。 ## 静的メソッド @@ -221,7 +221,7 @@ Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚 - {{jsxref("String.prototype.at()")}} - : 指定した `index` にある文字（UTF-16 コード単位）を返します。負の整数を受け入れ、その場合は文字列の最後の文字から遡ります。 -- {{jsxref("String.prototype.charAt()")}} +- {{jsxref("String/charAt")}} - : `index` で指定された位置の文字（UTF-16 コード単位 1 つ）を返します。 - {{jsxref("String.prototype.charCodeAt()")}} - : `index` で指定された位置の文字の UTF-16 コード単位の値を示す数を返します。 @@ -234,11 +234,11 @@ Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚 - {{jsxref("String.prototype.includes()")}} - : 呼び出した文字列に `searchString` が含まれているかを返します。 - {{jsxref("String.prototype.indexOf()")}} - - : 呼び出す {{jsxref("String")}} オブジェクト内で、`searchValue` が最初に現れる位置を返します。見つからなかった場合は `-1` を返します。 + - : この文字列内で、`searchValue` が最初に現れる位置を返します。見つからなかった場合は `-1` を返します。 - {{jsxref("String.prototype.isWellFormed()")}} - - : 文字列に[孤立サロゲート](#utf-16_characters_unicode_code_points_and_grapheme_clusters)が含まれているかどうかを示す論理値を返します。 + - : 文字列に[孤立サロゲート](#utf-16_文字、unicode_コードポイント、書記素クラスター)が含まれているかどうかを示す論理値を返します。 - {{jsxref("String.prototype.lastIndexOf()")}} - - : 呼び出した {{jsxref("String")}} オブジェクト内で、`searchValue` が最後に現れる位置を返します。見つからない場合は `-1` を返します。 + - : この文字列内で、`searchValue` が最後に現れる位置を返します。見つからない場合は `-1` を返します。 - {{jsxref("String.prototype.localeCompare()")}} - : 参照文字列 `compareString` が、並べ替え順において、与えられた文字列の前になるか後になるか、あるいは、同じかどうかを示す数値を返します。 - {{jsxref("String.prototype.match()")}} @@ -265,21 +265,21 @@ Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚 - : 呼び出した文字列を、部分文字列 `sep` が現れるところで分割し、文字列の配列を生成して返します。 - {{jsxref("String.prototype.startsWith()")}} - : 呼び出した文字列が文字列 `searchString` で開始されているかを判断します。 -- {{jsxref("String.prototype.substr()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.substr()")}} {{deprecated_inline}} - : 指定されたインデックスから、指定された文字数だけ文字列の一部を返します。 -- {{jsxref("String.prototype.substring()")}} +- {{jsxref("String/substring")}} - : 呼び出した文字列の指定された位置以降（または区間）にある文字が入った新しい文字列を返します。 - {{jsxref("String.prototype.toLocaleLowerCase()")}} - : 文字列内の文字が、現在のロケールに沿って小文字に変換されます。 - ほとんどの言語では、これは {{jsxref("String.prototype.toLowerCase()", "toLowerCase()")}} と同じものを返します。 + ほとんどの言語では、これは {{jsxref("String/toLowerCase", "toLowerCase()")}} と同じものを返します。 - {{jsxref("String.prototype.toLocaleUpperCase()")}} - : 文字列内の文字が、現在のロケールに沿って大文字に変換されます。 - ほとんどの言語では、これは {{jsxref("String.prototype.toUpperCase()", "toUpperCase()")}} と同じものを返します。 + ほとんどの言語では、これは {{jsxref("String/toUpperCase", "toUpperCase()")}} と同じものを返します。 - {{jsxref("String.prototype.toLowerCase()")}} - : 小文字に変換された文字列の値を呼び出して返します。 @@ -295,9 +295,9 @@ Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚 - : 文字列の末尾にあるホワイトスペースを削除します。 - {{jsxref("String.prototype.trimStart()")}} - : 文字列の先頭にあるホワイトスペースを削除します。 -- {{jsxref("String.prototype.valueOf()")}} +- {{jsxref("String/valueOf")}} - : 指定されたオブジェクトのプリミティブ値を返します。{{jsxref("Object.prototype.valueOf()")}} メソッドを上書きします。 -- [`String.prototype[@@iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) +- [`String.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator) - : 文字列値のコードポイントを反復処理し、文字列値として各コードポイントを返す、新しいイテレーターオブジェクトを返します。 ### HTML ラッパーメソッド @@ -307,31 +307,31 @@ Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚 > > これらはとても古い HTML 標準に基づいており、現在利用できる HTML タグや属性のサブセットしか提供していないため、使用するのには限界があります。多くが今日では非推奨または標準外のマークアップを生成します。さらに、単純な文字列の連結を検証やサニタイズなしに行うため、[`innerHTML`](/ja/docs/Web/API/Element/innerHTML) を使用して直接挿入するとセキュリティ上の脅威となる可能性があります。代わりに [DOM API](/ja/docs/Web/API/Document_Object_Model)、例えば [`document.createElement()`](/ja/docs/Web/API/Document/createElement) など使用してください。 -- {{jsxref("String.prototype.anchor()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.anchor()")}} {{deprecated_inline}} - : [``](/ja/docs/Web/HTML/Element/a#name)（ハイパーテキストのターゲット） -- {{jsxref("String.prototype.big()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.big()")}} {{deprecated_inline}} - : {{HTMLElement("big")}} -- {{jsxref("String.prototype.blink()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.blink()")}} {{deprecated_inline}} - : `` -- {{jsxref("String.prototype.bold()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.bold()")}} {{deprecated_inline}} - : {{HTMLElement("b")}} -- {{jsxref("String.prototype.fixed()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.fixed()")}} {{deprecated_inline}} - : {{HTMLElement("tt")}} -- {{jsxref("String.prototype.fontcolor()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.fontcolor()")}} {{deprecated_inline}} - : [``](/ja/docs/Web/HTML/Element/font#color) -- {{jsxref("String.prototype.fontsize()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.fontsize()")}} {{deprecated_inline}} - : [``](/ja/docs/Web/HTML/Element/font#size) -- {{jsxref("String.prototype.italics()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.italics()")}} {{deprecated_inline}} - : {{HTMLElement("i")}} -- {{jsxref("String.prototype.link()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.link()")}} {{deprecated_inline}} - : [``](/ja/docs/Web/HTML/Element/a#href)（URL へのリンク） -- {{jsxref("String.prototype.small()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.small()")}} {{deprecated_inline}} - : {{HTMLElement("small")}} -- {{jsxref("String.prototype.strike()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.strike()")}} {{deprecated_inline}} - : {{HTMLElement("strike")}} -- {{jsxref("String.prototype.sub()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.sub()")}} {{deprecated_inline}} - : {{HTMLElement("sub")}} -- {{jsxref("String.prototype.sup()")}} {{Deprecated_Inline}} +- {{jsxref("String.prototype.sup()")}} {{deprecated_inline}} - : {{HTMLElement("sup")}} これらのメソッドは文字列そのものが HTML タグを含むかどうかを調べないので、無効な HTML を作成する可能性があることに注意してください。 @@ -350,15 +350,17 @@ Unicode 文字の上に、書記素クラスターと呼ばれる 1 つの視覚 ### 文字列変換 -`String` を使用すると、 {{jsxref("String.prototype.toString()", "toString()")}} よりも信頼性の高い代替手段となり、[`null`](/ja/docs/Web/JavaScript/Reference/Operators/null) および {{jsxref("undefined")}} に対して使用することもできます。 +`String()` 関数は、値の {{jsxref("String.prototype.toString()", "toString()")}} メソッドを呼び出すよりも、値を文字列に変換する信頼性の高い方法です。前者は [`null`](/ja/docs/Web/JavaScript/Reference/Operators/null) や {{jsxref("undefined")}} に対して使用しても動作するからです。例を示します。 ```js +// null や undefined のプロパティにアクセスすることはできない + const nullVar = null; -nullVar.toString(); // TypeError: nullVar is null +nullVar.toString(); // TypeError: Cannot read properties of null String(nullVar); // "null" const undefinedVar = undefined; -undefinedVar.toString(); // TypeError: undefinedVar is undefined +undefinedVar.toString(); // TypeError: Cannot read properties of undefined String(undefinedVar); // "undefined" ``` @@ -372,5 +374,5 @@ String(undefinedVar); // "undefined" ## 関連情報 -- [JavaScript ガイドのテキスト処理](/ja/docs/Web/JavaScript/Guide/Text_formatting) +- [テキスト処理](/ja/docs/Web/JavaScript/Guide/Text_formatting)ガイド - {{jsxref("RegExp")}} diff --git a/files/ja/web/javascript/reference/global_objects/string/match/index.md b/files/ja/web/javascript/reference/global_objects/string/match/index.md index 21b8f38a43bf7f..f6cdca307312ca 100644 --- a/files/ja/web/javascript/reference/global_objects/string/match/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/match/index.md @@ -2,12 +2,12 @@ title: String.prototype.match() slug: Web/JavaScript/Reference/Global_Objects/String/match l10n: - sourceCommit: 8a6bfb2736b78904e81c94b82f86278031e65c80 + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} -**`match()`** メソッドは、[正規表現](/ja/docs/Web/JavaScript/Guide/Regular_expressions)に対する文字列の照合結果を受け取ります。 +**`match()`** は {{jsxref("String")}} 値のメソッドで、この文字列の[正規表現](/ja/docs/Web/JavaScript/Guide/Regular_expressions)に対する照合結果を受け取ります。 {{EmbedInteractiveExample("pages/js/string-match.html", "shorter")}} @@ -36,13 +36,13 @@ match(regexp) ## 解説 -`String.prototype.match` 自体の実装はとてもシンプルです。引数の文字列を最初の引数として `Symbol.match` メソッドを呼び出すだけです。実際の実装は [`RegExp.prototype[@@match]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) から来ています。 +`String.prototype.match` 自体の実装はとてもシンプルです。引数の文字列を最初の引数として `Symbol.match` メソッドを呼び出すだけです。実際の実装は [`RegExp.prototype[Symbol.match]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.match) から来ています。 - ある文字列が正規表現 {{jsxref("RegExp")}} に一致するかどうかを知る必要がある場合は、 {{jsxref("RegExp.prototype.test()")}} を使用してください。 - 一番最初に一致したものだけが欲しい場合は、代わりに {{jsxref("RegExp.prototype.exec()")}} を使ったほうが良いかもしれません。 - キャプチャグループを取得する場合でグローバルフラグを設定する場合は、 {{jsxref("RegExp.prototype.exec()")}} を使用してください。 -正規表現が渡されたときの `match()` の意味についての詳しい情報は、[`RegExp.prototype[@@match]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match) を参照してください。 +正規表現が渡されたときの `match()` の意味についての詳しい情報は、[`RegExp.prototype[Symbol.match]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.match) を参照してください。 ## 例 @@ -105,7 +105,7 @@ const str = "Nothing will come of nothing."; str.match(); // returns [""] ``` -### RegExp ではないオブジェクトを引数にする +### match() を `[Symbol.match]()` を実装している RegExp でないオブジェクトで使用 オブジェクトに `Symbol.match` メソッドがある場合、カスタムマッチャーとして使用することができます。 `Symbol.match` の返値が `match()` の返値になります。 diff --git a/files/ja/web/javascript/reference/global_objects/string/replace/index.md b/files/ja/web/javascript/reference/global_objects/string/replace/index.md index b916c48b3a9130..89891195864f75 100644 --- a/files/ja/web/javascript/reference/global_objects/string/replace/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/replace/index.md @@ -2,12 +2,12 @@ title: String.prototype.replace() slug: Web/JavaScript/Reference/Global_Objects/String/replace l10n: - sourceCommit: d85a7ba8cca98c2f6cf67a0c44f0ffd467532f20 + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} -**`replace()`** メソッドは、`pattern` に一致する文字列の一部またはすべてを `replacement` で置き換えた新しい文字列を返します。`pattern` には文字列または正規表現 ({{jsxref("RegExp")}}) を指定することができ、 `replacement` には文字列または一致するごとに呼び出される関数を指定することができます。`pattern` が文字列の場合、最初に一致した箇所のみを置き換えます。元の文字列は変更されません。 +**`replace()`** は {{jsxref("String")}} 値のメソッドで、`pattern` に一致する文字列の一部またはすべてを `replacement` で置き換えた新しい文字列を返します。`pattern` には文字列または正規表現 ({{jsxref("RegExp")}}) を指定することができ、 `replacement` には文字列または一致するごとに呼び出される関数を指定することができます。`pattern` が文字列の場合、最初に一致した箇所のみを置き換えます。元の文字列は変更されません。 {{EmbedInteractiveExample("pages/js/string-replace.html")}} @@ -36,7 +36,7 @@ replace(pattern, replacement) 文字列パターンは一度だけ置換されます。 グローバルな検索と置換を行うには、正規表現を `g` フラグで使用するか、代わりに [`replaceAll()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) を使用してください。 -`pattern` が [`Symbol.replace`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) メソッドを持つオブジェクト（`RegExp` オブジェクトを含む）である場合、そのメソッドはターゲット文字列と `replacement` を引数として呼び出されます。その返値は `replace()` の返値となります。この場合、`replace()` の動作は完全に `@@replace` メソッドによってエンコードされます。例えば、以下の説明で「グループをキャプチャする」と書かれているものは、実際には [`RegExp.prototype[@@replace]`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) によって提供される機能です。 +`pattern` が [`Symbol.replace`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) メソッドを持つオブジェクト（`RegExp` オブジェクトを含む）である場合、そのメソッドはターゲット文字列と `replacement` を引数として呼び出されます。その返値は `replace()` の返値となります。この場合、`replace()` の動作は完全に `[Symbol.replace]()` メソッドによってエンコードされます。例えば、以下の説明で「グループをキャプチャする」と書かれているものは、実際には [`RegExp.prototype[Symbol.replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace) によって提供される機能です。 `pattern` が空文字列の場合、文字列の始めには置換後の文字列が置かれます。 @@ -44,7 +44,7 @@ replace(pattern, replacement) "xxx".replace("", "_"); // "_xxx" ``` -`g` フラグを持つ正規表現は、 `replace()` が複数回置換する唯一のケースです。正規表現プロパティ（特に [sticky](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) フラグ）と `replace()` の相互作用については、[`RegExp.prototype[@@replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) を参照してください。 +`g` フラグを持つ正規表現は、 `replace()` が複数回置換する唯一のケースです。正規表現プロパティ（特に [sticky](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) フラグ）と `replace()` の相互作用については、[`RegExp.prototype[Symbol.replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace) を参照してください。 ### 置換文字列としての文字列の指定 @@ -91,7 +91,7 @@ function replacer(match, p1, p2, /* …, */ pN, offset, string, groups) { - `match` - : 一致した部分文字列（上記の `$&` に対応）です。 -- `p1, p2, …, pN` +- `p1`, `p2`, …, `pN` - : キャプチャグループ（名前付きキャプチャグループを含む）で見つかった `n` 番目の文字列で、`replace()` の第一引数が {{jsxref("RegExp")}} オブジェクトだった場合に提供されるものです。（上記の `$1`, `$2`, などに対応します。）例えば `pattern` が `/(\a+)(\b+)/` であった場合、`p1` は `\a+` に対する一致、`p2` は `\b+` に対する一致となります。そのグループが論理和の一部である場合（`"abc".replace(/(a)|(b)/, replacer)` など）、一致しない選択肢は `undefined` なります。 - `offset` - : 一致した部分文字列の、分析中の文字列全体の中でのオフセットです。例えば、文字列全体が `'abcd'` で、一致した部分文字列が `'bc'` ならば、この引数は 1 となります。 @@ -130,7 +130,7 @@ console.log(newstr); // Twas the night before Christmas... これは `'Twas the night before Christmas...'` と出力します。 > [!NOTE] -> 正規表現についてのその他の例は[このガイド](/ja/docs/Web/JavaScript/Guide/Regular_expressions)を参照してください。 +> 正規表現についてのその他の例は、[正規表現ガイド](/ja/docs/Web/JavaScript/Guide/Regular_expressions)を参照してください。 ### 大文字小文字を区別しないフラグとグローバルフラグの使用 @@ -175,7 +175,7 @@ function styleHyphenFormat(propertyName) { `styleHyphenFormat('borderTop')`を入力すると `'border-top'` を返します。 -最終的な置換が行われる前に、一致の*結果*をさらに変換したいので、関数を使用する必要があります。これにより、[`toLowerCase()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) メソッドの前に一致の評価が行われます。関数を使わず一致を使ってこれを行おうとした場合、 {{jsxref("String.prototype.toLowerCase()", "toLowerCase()")}} は何の効果もないでしょう。 +最終的な置換が行われる前に、一致の*結果*をさらに変換したいので、関数を使用する必要があります。これにより、[`toLowerCase()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) メソッドの前に一致の評価が行われます。関数を使わず一致を使ってこれを行おうとした場合、 {{jsxref("String/toLowerCase", "toLowerCase()")}} は何の効果もないでしょう。 ```js example-bad // 動作しない @@ -248,9 +248,9 @@ console.log("abcd".replace(/(?bc)/, addOffset)); // "abc (1) d" ## 関連情報 - [`String.prototype.replace` のポリフィル (`core-js`) （`Symbol.replace` への対応など、現代の修正や実装に対応したもの）](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) -- {{jsxref("String.prototype.replaceAll", "String.prototype.replaceAll()")}} -- {{jsxref("String.prototype.match", "String.prototype.match()")}} -- {{jsxref("RegExp.prototype.exec", "RegExp.prototype.exec()")}} -- {{jsxref("RegExp.prototype.test", "RegExp.prototype.test()")}} +- {{jsxref("String.prototype.replaceAll()")}} +- {{jsxref("String.prototype.match()")}} +- {{jsxref("RegExp.prototype.exec()")}} +- {{jsxref("RegExp.prototype.test()")}} - [`Symbol.replace`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) -- [`RegExp.prototype[@@replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) +- [`RegExp.prototype[Symbol.replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace) diff --git a/files/ja/web/javascript/reference/global_objects/string/split/index.md b/files/ja/web/javascript/reference/global_objects/string/split/index.md index 86fa6a9f458090..25403ecb335e33 100644 --- a/files/ja/web/javascript/reference/global_objects/string/split/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/split/index.md @@ -2,12 +2,12 @@ title: String.prototype.split() slug: Web/JavaScript/Reference/Global_Objects/String/split l10n: - sourceCommit: 6d606174faaedaa5dee7b7ebd87602cd51e5dd7e + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} -**`split()`** メソッドは、パターンを受け取り、{{jsxref("String")}} をパターン検索によって部分文字列の順序付きリストに分割し、これらの部分文字列を配列に入れ、その配列を返します。 +**`split()`** は {{jsxref("String")}} 値のメソッドで、パターンを受け取り、この文字列をパターン検索によって部分文字列の順序付きリストに分割し、これらの部分文字列を配列に入れ、その配列を返します。 {{EmbedInteractiveExample("pages/js/string-split.html", "taller")}} @@ -21,7 +21,7 @@ split(separator, limit) ### 引数 - `separator` - - : 各分割がどこで行われるかを表すパターンです。`undefined`、文字列、または [`Symbol.split`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/split) メソッドを持つオブジェクトを指定することができます。典型的な例は{{jsxref("Global_Objects/RegExp", "正規表現", "", 1)}}です。`separator` を省略したり `undefined` を渡したりすると、`split()` は呼び出し元の文字列を 1 つの要素とする配列を返します。`undefined` でない値、または `@@split` メソッドを持つオブジェクトはすべて[文字列に変換されます](/ja/docs/Web/JavaScript/Reference/Global_Objects/String#文字列変換)。 + - : 各分割がどこで行われるかを表すパターンです。`undefined`、文字列、または [`Symbol.split`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/split) メソッドを持つオブジェクトを指定することができます。典型的な例は{{jsxref("Global_Objects/RegExp", "正規表現", "", 1)}}です。`separator` を省略したり `undefined` を渡したりすると、`split()` は呼び出し元の文字列を 1 つの要素とする配列を返します。`undefined` でない値、または `[Symbol.split]()` メソッドを持つオブジェクトはすべて[文字列に変換されます](/ja/docs/Web/JavaScript/Reference/Global_Objects/String#文字列変換)。 - `limit` {{optional_inline}} - : 配列に含める部分文字列の数の制限を指定する非負の整数。指定した場合は、指定した `separator` が出現するたびに文字列を分割しますが、`limit` 個の項目が配列に格納された時点で分割を終了します。残った文字列は配列に格納されません。 - 制限数に達する以前に文字列の末尾に達した場合は、配列の要素が `limit` よりも少なくなることがあります。 @@ -41,7 +41,7 @@ split(separator, limit) > したがって、`"".split("")` は `separator` として文字列を渡され、`limit` が `0` でないときに空の配列を生成する唯一の方法です。 > [!WARNING] -> 区切り文字として空文字列 (`""`) が用いられた場合、文字列はユーザが認識する文字（[書記素クラスタ](https://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries)）や Unicode 文字（コードポイント）ではなく、UTF-16 コード単位で分割されます。 これは[サロゲートペア](https://unicode.org/faq/utf_bom.html#utf16-2)を破壊します。[StackOverflow の "How do you get a string to a character array in JavaScript?"](https://stackoverflow.com/questions/4547609/how-to-get-character-array-from-a-string/34717402#34717402) を参照してください。 +> 区切り文字として空文字列 (`""`) が用いられた場合、文字列はユーザーが認識する文字（[書記素クラスタ](https://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries)）や Unicode 文字（コードポイント）ではなく、UTF-16 コード単位で分割されます。 これは[サロゲートペア](https://unicode.org/faq/utf_bom.html#utf16-2)を破壊します。[StackOverflow の "How do you get a string to a character array in JavaScript?"](https://stackoverflow.com/questions/4547609/how-to-get-character-array-from-a-string/34717402#34717402) を参照してください。 `separator` が空文字列に一致する正規表現である場合、一致する文字列が UTF-16 コード単位で分割されるか、Unicode コード点で分割されるかは、正規表現が [Unicode-aware](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicode#unicode-aware_mode) かどうかに依存します。 @@ -288,4 +288,4 @@ console.log(commands.split(splitCommands, 3)); // ["light on", "brightness up", - {{jsxref("String.prototype.indexOf()")}} - {{jsxref("String.prototype.lastIndexOf()")}} - {{jsxref("Array.prototype.join()")}} -- [JavaScript での正規表現の使用](/ja/docs/Web/JavaScript/Guide/Regular_expressions) +- [正規表現](/ja/docs/Web/JavaScript/Guide/Regular_expressions)ガイド From 527d92818cfd0236de26bda20734b99a27831592 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 23:38:31 +0900 Subject: [PATCH 014/221] =?UTF-8?q?2024/07/15=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../string/codepointat/index.md | 12 +++++------ .../global_objects/string/length/index.md | 6 +++--- .../global_objects/string/matchall/index.md | 20 +++++++++---------- .../global_objects/string/replaceall/index.md | 16 +++++++-------- .../global_objects/string/search/index.md | 14 ++++++------- .../string/symbol.iterator/index.md | 18 ++++++++++------- 6 files changed, 45 insertions(+), 41 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/string/codepointat/index.md b/files/ja/web/javascript/reference/global_objects/string/codepointat/index.md index ffb5694bd5887c..97254c541a769b 100644 --- a/files/ja/web/javascript/reference/global_objects/string/codepointat/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/codepointat/index.md @@ -2,14 +2,14 @@ title: String.prototype.codePointAt() slug: Web/JavaScript/Reference/Global_Objects/String/codePointAt l10n: - sourceCommit: a49d60648404407784b04ff5ff7e16a6a8d1ac25 + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} **`codePointAt()`** は {{jsxref("String")}} のメソッドで、指定されたインデックスから始まる文字の Unicode コードポイント値である非負の整数を返します。インデックスは Unicode コードポイントではなく、UTF-16 コード単位に基づくことに注意してください。 -{{EmbedInteractiveExample("pages/js/string-codepointat.html","shorter")}} +{{EmbedInteractiveExample("pages/js/string-codepointat.html", "shorter")}} ## 構文 @@ -27,8 +27,8 @@ codePointAt(index) 指定された位置 `index` にある文字のコードポイント値を表す非負の整数値です。 - `index` が `0` – `str.length - 1` の範囲外であれば、`codePointAt()` は {{jsxref("undefined")}} を返します。 -- `index` の位置の要素が UTF-16 高サロゲートであった場合、そのコードポイントのサロゲートペアを返します。 -- `index` の位置の要素が UTF-16 低サロゲートであった場合、低サロゲートコードポイントのみを返します。 +- `index` の位置の要素が UTF-16 上位サロゲートであった場合、そのコードポイントのサロゲートペアを返します。 +- `index` の位置の要素が UTF-16 下位サロゲートであった場合、下位サロゲートコード単位のみを返します。 ## 解説 @@ -57,7 +57,7 @@ Unicode のコードポイントは `0` から `1114111` (`0x10FFFF`) までの ### codePointAt() の繰り返し -要素が UTF-16 の低サロゲートである `index` へのインデックス付けは、低サロゲートのみを返すので、文字列のインデックスをループに使わない方がよいでしょう。 +文字列インデックスを使用してループ処理を行うと、同じコードポイントが 2 回参照されることになります（1 回目は上位サロゲート、2 回目は下位サロゲート）。また、2 回目に `codePointAt()` が返すのは下位サロゲートのみです。そのため、インデックスによるループ処理は避けた方が良いでしょう。 ```js example-bad const str = "\ud83d\udc0e\ud83d\udc71\u2764"; @@ -68,7 +68,7 @@ for (let i = 0; i < str.length; i++) { // '1f40e', 'dc0e', '1f471', 'dc71', '2764' ``` -代わりに、[`for...of`](/ja/docs/Web/JavaScript/Guide/Loops_and_iteration#for...of_statement) 文や[スプレッド構文](/ja/docs/Web/JavaScript/Reference/Operators/Spread_syntax)を使用してください。どちらも文字列の [`@@iterator`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator) を呼び出し、コードポイント単位で反復処理をします。それから、`codePointAt(0)` でそれぞれの要素のコードポイントを取得してください。 +代わりに、[`for...of`](/ja/docs/Web/JavaScript/Guide/Loops_and_iteration#for...of_statement) 文や[スプレッド構文](/ja/docs/Web/JavaScript/Reference/Operators/Spread_syntax)を使用してください。どちらも文字列の [`[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator) を呼び出し、コードポイント単位で反復処理をします。それから、`codePointAt(0)` でそれぞれの要素のコードポイントを取得してください。 ```js for (const codePoint of str) { diff --git a/files/ja/web/javascript/reference/global_objects/string/length/index.md b/files/ja/web/javascript/reference/global_objects/string/length/index.md index 2cbcce953503c0..09b04e72c3db83 100644 --- a/files/ja/web/javascript/reference/global_objects/string/length/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/length/index.md @@ -2,7 +2,7 @@ title: "String: length" slug: Web/JavaScript/Reference/Global_Objects/String/length l10n: - sourceCommit: f01f00dd9fb1dbb2af9c40c5b06421e883d71910 + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} @@ -33,7 +33,7 @@ l10n: const str1 = "a".repeat(2 ** 29 - 24); // 成功する const str2 = "a".repeat(2 ** 29 - 23); // RangeError: Invalid string length -const buffer = new Uint8Array(2 ** 29 - 24).fill("a".codePointAt(0)); // このバッファのサイズは 512MiB +const buffer = new Uint8Array(2 ** 29 - 24).fill("a".codePointAt(0)); // このバッファーのサイズは 512MiB const str = new TextDecoder().decode(buffer); // この文字列のサイズは 1GiB ``` @@ -41,7 +41,7 @@ const str = new TextDecoder().decode(buffer); // この文字列のサイズは 静的プロパティの `String.length` は文字列の長さとは関係なく、 `String` 関数の[アリティ](/ja/docs/Web/JavaScript/Reference/Global_Objects/Function/length)（簡単に言えば、それが持つ形式的な引数の数）であり、1 です。 -`length` は文字数ではなくコード単位で数えるため、文字数を取得したい場合は、まず文字列を[イテレーター](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/@@iterator)で分割し、文字ごとに反復処理をしてください。 +`length` は文字数ではなくコード単位で数えるため、文字数を取得したい場合は、まず文字列を[イテレーター](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator)で分割し、文字ごとに反復処理をしてください。 ```js function getCharacterLength(str) { diff --git a/files/ja/web/javascript/reference/global_objects/string/matchall/index.md b/files/ja/web/javascript/reference/global_objects/string/matchall/index.md index 9e0d8129b1f7c5..c4a8dbeef9375b 100644 --- a/files/ja/web/javascript/reference/global_objects/string/matchall/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/matchall/index.md @@ -2,12 +2,12 @@ title: String.prototype.matchAll() slug: Web/JavaScript/Reference/Global_Objects/String/matchAll l10n: - sourceCommit: d85a7ba8cca98c2f6cf67a0c44f0ffd467532f20 + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`matchAll()`** は[正規表現](/ja/docs/Web/JavaScript/Guide/Regular_expressions)に一致するすべての文字列を、[キャプチャグループ](/ja/docs/Web/JavaScript/Guide/Regular_expressions/Groups_and_backreferences)を含み、イテレーターで返すメソッドです。 +**`matchAll()`** は {{jsxref("String")}} 値のメソッドで、この文字列と[正規表現](/ja/docs/Web/JavaScript/Guide/Regular_expressions)を照合したすべての結果を、[キャプチャグループ](/ja/docs/Web/JavaScript/Guide/Regular_expressions/Groups_and_backreferences)を含み、イテレーターで返すメソッドです。 {{EmbedInteractiveExample("pages/js/string-matchall.html")}} @@ -29,7 +29,7 @@ matchAll(regexp) ### 返値 -一致したものの[反復可能なイテレーターオブジェクト](/ja/docs/Web/JavaScript/Reference/Global_Objects/Iterator)（再起動不可能なもの）です。それぞれの一致する配列は {{jsxref("RegExp.prototype.exec()")}} の返値と同じ形です。 +一致したものの[反復可能なイテレーターオブジェクト](/ja/docs/Web/JavaScript/Reference/Global_Objects/Iterator)（再起動不可能なもの）、または一致するものがなければ空のイテレーターです。イテレーターが生成するそれぞれの値は、{{jsxref("RegExp.prototype.exec()")}} の返値と同じ形です。 ### 例外 @@ -38,7 +38,7 @@ matchAll(regexp) ## 解説 -`String.prototype.matchAll` の実装自体は、正規表現がグローバルであるという余分な入力検証を除けば）非常にシンプルで、引数の文字列を最初の引数として `Symbol.matchAll` メソッドを呼び出すだけです。実際の実装は [`RegExp.prototype[@@matchAll]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) から来ています。 +`String.prototype.matchAll` の実装自体は、正規表現がグローバルであるという余分な入力検証を除けば）非常にシンプルで、引数の文字列を最初の引数として `Symbol.matchAll` メソッドを呼び出すだけです。実際の実装は [`RegExp.prototype[Symbol.matchAll]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.matchAll) から来ています。 ## 例 @@ -92,7 +92,7 @@ str.matchAll(regexp); // TypeError ``` -`matchAll` では内部的に `regexp` の複製を作成します。そのため {{jsxref("Global_Objects/RegExp/exec", "regexp.exec()")}} とは違って文字列をスキャンした際に `lastIndex` が変わることはありません。 +`matchAll` では内部的に `regexp` の複製を作成します。そのため {{jsxref("RegExp/exec", "regexp.exec()")}} とは違って文字列をスキャンした際に `lastIndex` が変わることはありません。 ```js const regexp = /[a-c]/g; @@ -108,7 +108,7 @@ Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`); `matchAll` はキャプチャグループへのよりよいアクセスを実現します。 -{{jsxref("Global_Objects/String/match", "match()")}} では、グローバル `g` フラグを使用するとキャプチャグループが無視されてしまいます。 +{{jsxref("String/match", "match()")}} では、グローバル `g` フラグを使用するとキャプチャグループが無視されてしまいます。 ```js const regexp = /t(e)(st(\d?))/g; @@ -128,7 +128,7 @@ array[1]; // ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4] ``` -### matchAll() を RegExp ではない @@matchAll を実装しているオブジェクトで使用 +### matchAll() を RegExp ではない `[Symbol.matchAll]()` を実装しているオブジェクトで使用 オブジェクトに `Symbol.matchAll` メソッドがあれば、それをカスタムマッチャーとして使うことができます。`Symbol.matchAll` の返値は `matchAll()` の返値となる。 @@ -154,9 +154,9 @@ str.matchAll({ - [`String.prototype.matchAll` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) - {{jsxref("String.prototype.match()")}} -- [JavaScript での正規表現の使用](/ja/docs/Web/JavaScript/Guide/Regular_expressions) -- [キャプチャグループ](/ja/docs/Web/JavaScript/Guide/Regular_expressions/Groups_and_backreferences) +- [JavaScript での正規表現の使用](/ja/docs/Web/JavaScript/Guide/Regular_expressions)ガイド +- [グループと後方参照](/ja/docs/Web/JavaScript/Guide/Regular_expressions/Groups_and_backreferences)ガイド - {{jsxref("RegExp")}} - {{jsxref("RegExp.prototype.exec()")}} - {{jsxref("RegExp.prototype.test()")}} -- [`RegExp.prototype[@@matchAll]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll) +- [`RegExp.prototype[Symbol.matchAll]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.matchAll) diff --git a/files/ja/web/javascript/reference/global_objects/string/replaceall/index.md b/files/ja/web/javascript/reference/global_objects/string/replaceall/index.md index 34efb10357d641..e2209ecf94e21f 100644 --- a/files/ja/web/javascript/reference/global_objects/string/replaceall/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/replaceall/index.md @@ -2,12 +2,12 @@ title: String.prototype.replaceAll() slug: Web/JavaScript/Reference/Global_Objects/String/replaceAll l10n: - sourceCommit: 6e3889be77fa45d5823216d0cc61b4f7c4b99e1b + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`replaceAll()`** メソッドは、`pattern` に一致したすべての文字列を `replacement` で置き換えた新しい文字列を返します。`pattern` は文字列または {{jsxref("RegExp")}} を指定することができ、`replacement` は文字列または各一致に対して呼び出される関数を指定することができます。元の文字列は変更されません。 +**`replaceAll()`** は {{jsxref("String")}} 値のメソッドで、`pattern` に一致したすべての文字列を `replacement` で置き換えた新しい文字列を返します。`pattern` には文字列または {{jsxref("RegExp")}} を指定することができ、`replacement` は文字列または各一致に対して呼び出される関数を指定することができます。元の文字列は変更されません。 {{EmbedInteractiveExample("pages/js/string-replaceall.html")}} @@ -58,14 +58,14 @@ console.log(unsafeRedactName(report, "ha.*er")); // "A [REDACTED]s in their name console.log(safeRedactName(report, "ha.*er")); // "A hacker called [REDACTED] used special characters in their name to breach the system." ``` -`pattern` が [`Symbol.replace`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) メソッドを持つオブジェクト（`RegExp` オブジェクトを含む）である場合、そのメソッドは対象の文字列と `replacement` を引数として呼び出されます。その返値は `replaceAll()` の返値となります。この場合、`replaceAll()` の動作は完全に `@@replace` メソッドによってエンコードされるので、 `replace()` と同じ結果になります（正規表現がグローバルであるかどうかの余分な入力検証を除けば）。 +`pattern` が [`Symbol.replace`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace) メソッドを持つオブジェクト（`RegExp` オブジェクトを含む）である場合、そのメソッドは対象の文字列と `replacement` を引数として呼び出されます。その返値は `replaceAll()` の返値となります。この場合、`replaceAll()` の動作は完全に `[Symbol.replace]()` メソッドによってエンコードされるので、 `replace()` と同じ結果になります（正規表現がグローバルであるかどうかの余分な入力検証を除けば）。 `pattern` が空文字列の場合、[`split()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/split) の動作と同様に、UTF-16 のコード単位ごとに置換文字列が挿入されます。 ```js "xxx".replaceAll("", "_"); // "_x_x_x_" ``` -正規表現プロパティ（特に [sticky](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) フラグ）と `replaceAll()` との相互作用については、[`RegExp.prototype[@@replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace) を参照してください。 +正規表現プロパティ（特に [sticky](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) フラグ）と `replaceAll()` との相互作用については、[`RegExp.prototype[Symbol.replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace) を参照してください。 ## 例 @@ -103,7 +103,7 @@ console.log(safeRedactName(report, "ha.*er")); // "A hacker called [REDACTED] us ## 関連情報 - [`String.prototype.replaceAll` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) -- {{jsxref("String.prototype.replace", "String.prototype.replace()")}} -- {{jsxref("String.prototype.match", "String.prototype.match()")}} -- {{jsxref("RegExp.prototype.exec", "RegExp.prototype.exec()")}} -- {{jsxref("RegExp.prototype.test", "RegExp.prototype.test()")}} +- {{jsxref("String.prototype.replace()")}} +- {{jsxref("String.prototype.match()")}} +- {{jsxref("RegExp.prototype.exec()")}} +- {{jsxref("RegExp.prototype.test()")}} diff --git a/files/ja/web/javascript/reference/global_objects/string/search/index.md b/files/ja/web/javascript/reference/global_objects/string/search/index.md index 192ffc4e771b4d..f362b356367b80 100644 --- a/files/ja/web/javascript/reference/global_objects/string/search/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/search/index.md @@ -2,12 +2,12 @@ title: String.prototype.search() slug: Web/JavaScript/Reference/Global_Objects/String/search l10n: - sourceCommit: d85a7ba8cca98c2f6cf67a0c44f0ffd467532f20 + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`search()`** メソッドは、正規表現とこの {{jsxref("String")}} オブジェクトが一致するかどうかを調べます。 +**`search()`** は {{jsxref("String")}} 値のメソッドで、正規表現とこの文字列の一致する箇所を検索し、文字列内の最初に一致する箇所の位置を返します。 {{EmbedInteractiveExample("pages/js/string-search.html")}} @@ -31,14 +31,14 @@ search(regexp) ## 解説 -`String.prototype.search()` 自体の実装はとてもシンプルです。引数の文字列を最初の引数として `Symbol.search` メソッドを呼び出すだけです。実際の実装は [`RegExp.prototype[@@search]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) から来ています。 +`String.prototype.search()` 自体の実装はとてもシンプルです。引数の文字列を最初の引数として `Symbol.search` メソッドを呼び出すだけです。実際の実装は [`RegExp.prototype[Symbol.search]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.search) から来ています。 -`regexp` の `g` フラグは `search()` の結果には影響がなく、検索は常に正規表現の `lastIndex` が 0 であるかのように行われます。`search()` の動作についての詳しい情報は、[`RegExp.prototype[@@search]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) を参照してください。 +`regexp` の `g` フラグは `search()` の結果には影響がなく、検索は常に正規表現の `lastIndex` が 0 であるかのように行われます。`search()` の動作についての詳しい情報は、[`RegExp.prototype[Symbol.search]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.search) を参照してください。 パターンが見つかるかどうかを知りたい場合、かつ、文字列内のインデックスを知りたい場合は、`search()` を使用してください。 - パターンが存在するかどうかを知りたいだけであれば、{{jsxref("RegExp.prototype.test()")}} メソッドを使用してください。これは論理値を返します。 -- 一致したテキストの内容が必要な場合は、{{jsxref("String.prototype.match()", "match()")}} または {{jsxref("RegExp.prototype.exec()")}} を使用してください。 +- 一致したテキストの内容が必要な場合は、{{jsxref("String.prototype.match()")}} または {{jsxref("RegExp.prototype.exec()")}} を使用してください。 ## 例 @@ -65,7 +65,7 @@ console.log(str.search(reDot)); // ドット記号 '.' が見つからないの ## 関連情報 - [`String.prototype.search` のポリフィル (`core-js`) （`Symbol.search` のようなの現代の修正や挙動つき）](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) -- [JavaScript の正規表現の使用](/ja/docs/Web/JavaScript/Guide/Regular_expressions) +- [正規表現](/ja/docs/Web/JavaScript/Guide/Regular_expressions)ガイド - {{jsxref("String.prototype.match()")}} - {{jsxref("RegExp.prototype.exec()")}} -- [`RegExp.prototype[@@search]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@search) +- [`RegExp.prototype[Symbol.search]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.search) diff --git a/files/ja/web/javascript/reference/global_objects/string/symbol.iterator/index.md b/files/ja/web/javascript/reference/global_objects/string/symbol.iterator/index.md index ab3df9f6fbd4b2..bc60d6215da900 100644 --- a/files/ja/web/javascript/reference/global_objects/string/symbol.iterator/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/symbol.iterator/index.md @@ -1,15 +1,13 @@ --- -title: String.prototype[@@iterator]() +title: String.prototype[Symbol.iterator]() slug: Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator -original_slug: Web/JavaScript/Reference/Global_Objects/String/@@iterator l10n: - sourceCommit: 427e8d03276b4915c08c5f0541452fb1c830c295 + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`[@@iterator]()`** は {{jsxref("String")}} 値のメソッドで、[反復可能プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols)を実装しており、[スプレッド構文](/ja/docs/Web/JavaScript/Reference/Operators/Spread_syntax)や{{jsxref("Statements/for...of", "for...of")}}ループ -文字列値のコードポイントを走査し、それぞれのコードポイントを文字列値として返すイテレーターオブジェクトを返します。 +**`[Symbol.iterator]()`** は {{jsxref("String")}} 値のメソッドで、[反復可能プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols)を実装しており、[スプレッド構文](/ja/docs/Web/JavaScript/Reference/Operators/Spread_syntax)や {{jsxref("Statements/for...of", "for...of")}} ループなど、反復可能オブジェクトを期待するほとんどの構文で文字列が利用できるようにします。これは、文字列値の Unicode コードポイントを個別の文字列として返す[文字列イテレーターオブジェクト](/ja/docs/Web/JavaScript/Reference/Global_Objects/Iterator)を返します。 {{EmbedInteractiveExample("pages/js/string-prototype-@@iterator.html")}} @@ -19,6 +17,10 @@ l10n: string[Symbol.iterator]() ``` +### 引数 + +なし。 + ### 返値 新しい[反復可能なイテレーターオブジェクト](/ja/docs/Web/JavaScript/Reference/Global_Objects/Iterator)で、この文字列の各 Unicode コードポイントを、独立した文字列として生成します。 @@ -42,7 +44,7 @@ string[Symbol.iterator]() ### for...of ループを用いた反復処理 -このメソッドを直接呼び出す必要はほとんどないことに注意してください。`iterator` メソッドが存在することで、文字列は[反復可能](/ja/docs/Web/JavaScript/Reference/Iteration_protocols#反復可能プロトコル)になり、`for...of` ループのような反復処理構文は自動的にこのメソッドを呼び出して、ループするイテレーターを取得します。 +このメソッドを直接呼び出す必要はほとんどないことに注意してください。`[Symbol.iterator]()` メソッドが存在することで、文字列は[反復可能](/ja/docs/Web/JavaScript/Reference/Iteration_protocols#反復可能プロトコル)になり、`for...of` ループのような反復処理構文は自動的にこのメソッドを呼び出して、ループするイテレーターを取得します。 ```js const str = "A\uD835\uDC68B\uD835\uDC69C\uD835\uDC6A"; @@ -81,5 +83,7 @@ console.log(strIter.next().value); // "\uD835\uDC68" ## 関連情報 -- [`String.prototype[@@iterator]` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [`String.prototype[Symbol.iterator]` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-string-and-regexp) +- [テキスト処理](/ja/docs/Web/JavaScript/Guide/Text_formatting)ガイド +- {{jsxref("Symbol.iterator")}} - [反復処理プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols) From ce0e6940f9d09b61ea06abef91a06b6c2e474fba Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 23:41:56 +0900 Subject: [PATCH 015/221] =?UTF-8?q?2023/11/29=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../reference/global_objects/string/indexof/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/string/indexof/index.md b/files/ja/web/javascript/reference/global_objects/string/indexof/index.md index a2e5960ca40d51..d7fd7ff21432ab 100644 --- a/files/ja/web/javascript/reference/global_objects/string/indexof/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/indexof/index.md @@ -2,14 +2,14 @@ title: String.prototype.indexOf() slug: Web/JavaScript/Reference/Global_Objects/String/indexOf l10n: - sourceCommit: 6bd17cb9cbc2d11163617b9f71706e93fdd743c8 + sourceCommit: c367939020b2cbd60da7bd56a14670659d5e9491 --- {{JSRef}} **`indexOf()`** は {{jsxref("String")}} 値のメソッドで、この文字列を検索し、指定した部分文字列が最初に出現するインデックスを返します。 オプションで開始位置を取り、指定した数値以上のインデックスで指定した部分文字列が最初に出現するインデックスを返します。 -{{EmbedInteractiveExample("pages/js/string-indexof.html")}} +{{EmbedInteractiveExample("pages/js/string-indexof.html", "taller")}} ## 構文 @@ -107,7 +107,7 @@ console.log(str.indexOf("new")); // 6 以下の例は 2 つの文字列の変数を定義しています。 -それらの変数は、2 番目の文字列が大文字を含んでいることを除けば、同じ文字列を含んでいます。1 番目の {{domxref("console.log()")}} メソッドは `19` を表示します。しかし、`indexOf()` メソッドは大文字と小文字を区別するので、`"cheddar"` という文字列は `myCapString` では見つけられません。ですから、 `console.log()` メソッドは `-1` を表示します。 +それらの変数は、2 番目の文字列が大文字を含んでいることを除けば、同じ文字列を含んでいます。1 番目の {{domxref("console/log_static", "console.log()")}} メソッドは `19` を表示します。しかし、`indexOf()` メソッドは大文字と小文字を区別するので、`"cheddar"` という文字列は `myCapString` では見つけられません。ですから、 `console.log()` メソッドは `-1` を表示します。 ```js const myString = "brie, pepper jack, cheddar"; From f00f770a0230fe88e647da0407884d08933dbf33 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 23:43:46 +0900 Subject: [PATCH 016/221] =?UTF-8?q?2023/08/25=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../global_objects/string/iswellformed/index.md | 10 +++++++--- .../global_objects/string/towellformed/index.md | 10 +++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/string/iswellformed/index.md b/files/ja/web/javascript/reference/global_objects/string/iswellformed/index.md index d2b2a6ac1868ad..9624019bd1fa92 100644 --- a/files/ja/web/javascript/reference/global_objects/string/iswellformed/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/iswellformed/index.md @@ -2,7 +2,7 @@ title: String.prototype.isWellFormed() slug: Web/JavaScript/Reference/Global_Objects/String/isWellFormed l10n: - sourceCommit: 5635446aa0127d686183ddd4fd5adcc34be567da + sourceCommit: 27180875516cc311342e74b596bfb589b7211e0c --- {{JSRef}} @@ -15,6 +15,10 @@ l10n: isWellFormed() ``` +### 引数 + +なし。 + ### 返値 この文字列に孤立サロゲートがある場合は `true`、そうでなれば `false`。 @@ -31,10 +35,10 @@ JavaScript の文字列は UTF-16 エンコードです。UTF-16 エンコーデ ```js const strings = [ - // 孤立高サロゲート + // 孤立上位サロゲート "ab\uD800", "ab\uD800c", - // 孤立低サロゲート + // 孤立下位サロゲート "\uDFFFab", "c\uDFFFab", // 整形式 diff --git a/files/ja/web/javascript/reference/global_objects/string/towellformed/index.md b/files/ja/web/javascript/reference/global_objects/string/towellformed/index.md index 346713ef71fdcd..efaccc1467b41b 100644 --- a/files/ja/web/javascript/reference/global_objects/string/towellformed/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/towellformed/index.md @@ -2,7 +2,7 @@ title: String.prototype.toWellFormed() slug: Web/JavaScript/Reference/Global_Objects/String/toWellFormed l10n: - sourceCommit: 5635446aa0127d686183ddd4fd5adcc34be567da + sourceCommit: 27180875516cc311342e74b596bfb589b7211e0c --- {{JSRef}} @@ -15,6 +15,10 @@ l10n: toWellFormed() ``` +### 引数 + +なし。 + ### 返値 この文字列のコピーで、孤立サロゲートをすべて Unicode 置換文字 U+FFFD に置き換えた新しい文字列です。 もし `str` が[整形式](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/isWellFormed) であれば、やはり新しい文字列が返されます（基本的には `str` のコピーです）。 @@ -33,10 +37,10 @@ JavaScript の文字列は UTF-16 でエンコードされています。UTF-16 ```js const strings = [ - // 孤立高サロゲート + // 孤立上位サロゲート "ab\uD800", "ab\uD800c", - // 孤立低サロゲート + // 孤立下位サロゲート "\uDFFFab", "c\uDFFFab", // 整形式 From 843c412749b699cedb2f654ee23dea692ea70b29 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 23:46:01 +0900 Subject: [PATCH 017/221] =?UTF-8?q?2023/11/04=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../reference/global_objects/string/lastindexof/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/string/lastindexof/index.md b/files/ja/web/javascript/reference/global_objects/string/lastindexof/index.md index 6cc9b6e654beeb..0027c33fbaa023 100644 --- a/files/ja/web/javascript/reference/global_objects/string/lastindexof/index.md +++ b/files/ja/web/javascript/reference/global_objects/string/lastindexof/index.md @@ -2,14 +2,14 @@ title: String.prototype.lastIndexOf() slug: Web/JavaScript/Reference/Global_Objects/String/lastIndexOf l10n: - sourceCommit: be500eeadf5eba4722689ce9b150c506e8a9c7fa + sourceCommit: c607c483fe079c61de5e32fba1a6cce61896e97d --- {{JSRef}} **`lastIndexOf()`** は {{jsxref("String")}} 値のメソッドで、この文字列を検索し、指定した部分文字列が最後に出現するインデックスを返します。オプションで開始位置を取り、指定した数値以下のインデックスにおいて、指定した部分文字列が最後にに出現するインデックスを返します。 -{{EmbedInteractiveExample("pages/js/string-lastindexof.html", "shorter")}} +{{EmbedInteractiveExample("pages/js/string-lastindexof.html")}} ## 構文 @@ -65,7 +65,7 @@ lastIndexOf(searchString, position) ### indexOf() と lastIndexOf() の使用 -以下の例は、 {{jsxref("String.prototype.indexOf()", "indexOf()")}} と `lastIndexOf()` を使用して文字列 `"Brave, Brave New World"` の中の値の位置を示します。 +以下の例は、 {{jsxref("String/indexOf", "indexOf()")}} と `lastIndexOf()` を使用して文字列 `"Brave, Brave New World"` の中の値の位置を示します。 ```js const anyString = "Brave, Brave New World"; From 54107b91c209e16f1b5e79d2384b88417090f2e1 Mon Sep 17 00:00:00 2001 From: Sheep-realms <38580457+sheep-realms@users.noreply.github.com> Date: Mon, 14 Oct 2024 14:49:07 +0800 Subject: [PATCH 018/221] zh-cn: update some broken links in `
` (#24008) Co-authored-by: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Co-authored-by: Allo --- files/zh-cn/web/html/element/article/index.md | 126 ++++++++++++------ 1 file changed, 87 insertions(+), 39 deletions(-) diff --git a/files/zh-cn/web/html/element/article/index.md b/files/zh-cn/web/html/element/article/index.md index bdfa77c2f7b186..b7fa5e3112bb97 100644 --- a/files/zh-cn/web/html/element/article/index.md +++ b/files/zh-cn/web/html/element/article/index.md @@ -9,48 +9,18 @@ slug: Web/HTML/Element/article {{EmbedInteractiveExample("pages/tabbed/article.html", "tabbed-standard")}} -给定文档中可以包含多篇文章;例如，阅读器在博客上滚动时一个接一个地显示每篇文章的文本，每个帖子将包含在`
`元素中，可能包含一个或多个`
`。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
内容分类Flow content, sectioning content, palpable content.
允许的内容Flow content.
标签省略不允许，开始标签和结束标签都不能省略。
允许的父元素所有接受 Flow content的元素。注意<article>元素不能成为{{HTMLElement("address")}}元素的子元素。
允许的 ARIA rolesapplication, document, feed, main, presentation, region
DOM 实例{{domxref("HTMLElement")}}
+给定文档中可以包含多篇文章；例如，阅读器在博客上滚动时一个接一个地显示每篇文章的文本，每个帖子将包含在 `
` 元素中，可能包含一个或多个 `
`。 ## 属性 -此元素只具有[全局属性](/zh-CN/docs/HTML/Global_attributes)。 +此元素只具有[全局属性](/zh-CN/docs/Web/HTML/Global_attributes)。 ## 使用说明 -- 每个`
`，通常包括标题（\

- \

元素）作为`
`元素的子元素。 -- 当`
`元素嵌套使用时，则该元素代表与外层元素有关的文章。例如，代表博客评论的`
`元素可嵌套在代表博客文章的`
`元素中。 -- `
`元素的作者信息可通过{{HTMLElement("address")}}元素提供，但是不适用于嵌套的`
`元素。 -- `
`元素的发布日期和时间可通过{{HTMLElement("time")}}元素的[`pubdate`](/zh-CN/docs/Web/HTML/Element/time#pubdate)属性表示。 -- 可以使用{{HTMLElement("time")}} 元素的[`datetime`](/zh-CN/docs/Web/HTML/Element/time#datetime)属性来描述`
`元素的发布日期和时间。请注意{{HTMLElement("time")}}的*[`pubdate`](/zh-CN/docs/Web/HTML/Element/time#pubdate)* 属性不再是*{{glossary("W3C")}}* *{{glossary("HTML5")}}*标准。 +- 每个 `
`，通常包括标题（[`

`—`

`](/zh-CN/docs/Web/HTML/Element/Heading_Elements) 元素）作为 `
` 元素的子元素。 +- 当 `
` 元素嵌套使用时，则该元素代表与外层元素有关的文章。例如，代表博客评论的 `
` 元素可嵌套在代表博客文章的 `
` 元素中。 +- `
` 元素的作者信息可通过 {{HTMLElement("address")}} 元素提供，但是不适用于嵌套的 `
` 元素。 +- 可以使用 {{HTMLElement("time")}} 元素的 [`datetime`](/zh-CN/docs/Web/HTML/Element/time#datetime) 属性来描述 `
` 元素的发布日期和时间。 ## 示例 @@ -94,6 +64,84 @@ slug: Web/HTML/Element/article
``` +## 技术概要 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ 内容分类 + + 流式内容、分段内容、短语内容 +
允许的内容 + 流式内容。 +
标签省略不允许，开始标签和结束标签都不能省略。
允许的父元素 + 所有接受流式内容的元素。注意<article>元素不能成为 {{HTMLElement("address")}} 元素的子元素。 +
隐含的 ARIA 角色 + article +
允许的 ARIA 角色 + application、document、feed、main、none、presentation、region +
DOM 接口{{domxref("HTMLElement")}}
+ ## 规范 {{Specifications}} @@ -102,7 +150,7 @@ slug: Web/HTML/Element/article {{Compat}} -## 相关文章 +## 参见 -- Others section-related elements: {{HTMLElement("body")}}, {{HTMLElement("nav")}}, {{HTMLElement("section")}}, {{HTMLElement("aside")}}, {{HTMLElement("h1")}}, {{HTMLElement("h2")}}, {{HTMLElement("h3")}}, {{HTMLElement("h4")}}, {{HTMLElement("h5")}}, {{HTMLElement("h6")}}, {{HTMLElement("hgroup")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("address")}} -- [Sections and outlines of an HTML5 document](/zh-CN/docs/Sections_and_Outlines_of_an_HTML5_document). +- 其他分段相关元素：{{HTMLElement("body")}}、{{HTMLElement("nav")}}、{{HTMLElement("section")}}、{{HTMLElement("aside")}}、{{HTMLElement("Heading_Elements", "h1")}}、{{HTMLElement("Heading_Elements", "h2")}}、{{HTMLElement("Heading_Elements", "h3")}}、{{HTMLElement("Heading_Elements", "h4")}}、{{HTMLElement("Heading_Elements", "h5")}}、{{HTMLElement("Heading_Elements", "h6")}}、{{HTMLElement("hgroup")}}、{{HTMLElement("header")}}、{{HTMLElement("footer")}}、{{HTMLElement("address")}} +- [使用 HTML 分段和大纲](/zh-CN/docs/Web/HTML/Element/Heading_Elements) From f9cf014d57929d561edb12d0fc0581cf8b4420ef Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 14 Oct 2024 11:40:52 +0000 Subject: [PATCH 019/221] Bump autocorrect-node from 2.11.1 to 2.12.0 (#24049) --- package.json | 2 +- yarn.lock | 68 ++++++++++++++++++++++++++-------------------------- 2 files changed, 35 insertions(+), 35 deletions(-) diff --git a/package.json b/package.json index dc17c86fca0394..c1804f226d382d 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,7 @@ "node": ">=18.12.0" }, "dependencies": { - "autocorrect-node": "2.11.1", + "autocorrect-node": "2.12.0", "cld": "^2.10.0", "fdir": "^6.4.0", "front-matter": "^4.0.2", diff --git a/yarn.lock b/yarn.lock index 928d8a3281667c..021f38fc59b82e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -93,41 +93,41 @@ argparse@^2.0.1: resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38" integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q== -autocorrect-node-darwin-arm64@2.11.1: - version "2.11.1" - resolved "https://registry.yarnpkg.com/autocorrect-node-darwin-arm64/-/autocorrect-node-darwin-arm64-2.11.1.tgz#d45d4f804720535bab6a24e695f48d1736e8f398" - integrity sha512-7VdYsMAbJuLVHXPM6hv9+Sds91VX55DaMjiVvC6/p/orAg3pIy1wnk2JfJ0GKouKbkOKBp1fT2XFCJXVPBdh5w== - -autocorrect-node-darwin-x64@2.11.1: - version "2.11.1" - resolved "https://registry.yarnpkg.com/autocorrect-node-darwin-x64/-/autocorrect-node-darwin-x64-2.11.1.tgz#09a9c69b1945762bb2eb929fa1eaba728522cb67" - integrity sha512-oHiIq+RQm70DfgliW2W5/J8i7ov2cZyyK6l73fHxKOUzwVi7CSxMV6CHnthOZ7yUA07Y2QlFqVyYYPYbMykavA== - -autocorrect-node-linux-x64-gnu@2.11.1: - version "2.11.1" - resolved "https://registry.yarnpkg.com/autocorrect-node-linux-x64-gnu/-/autocorrect-node-linux-x64-gnu-2.11.1.tgz#0d83cd938648ff7ca0046d472ee7c68ff25a50dd" - integrity sha512-qWFiur7vXgnMLQ0zLpJ+ZRpBg23FQY0UrWIXgv+5uSVgPIUcDWa78FVpSDVmeWelpP3XTJ4ljUQuuXdok8oQEA== - -autocorrect-node-linux-x64-musl@2.11.1: - version "2.11.1" - resolved "https://registry.yarnpkg.com/autocorrect-node-linux-x64-musl/-/autocorrect-node-linux-x64-musl-2.11.1.tgz#570bf961dbfe1ed6a122ff6025a317bbacb62626" - integrity sha512-Hml5ZRdZMqpeM1p/j7TVy6xdv0+I5yxpRBAMCIkYJp6Le/NIz9EkEP9eYFxHOwdL+MexXvOd/1xSeHEjUL6JDw== - -autocorrect-node-win32-x64-msvc@2.11.1: - version "2.11.1" - resolved "https://registry.yarnpkg.com/autocorrect-node-win32-x64-msvc/-/autocorrect-node-win32-x64-msvc-2.11.1.tgz#7a54dc04d53115993bf7a9843d510da0f4f7eca6" - integrity sha512-1Cx2iI0eVz/tLyjnkaDx0uH+fXMRxV16tEjbnX0mWPV+LVp2KM5zqYYuzsSkm6f9O6dOFWGUn0ybKZ4QpZb/Dg== - -autocorrect-node@2.11.1: - version "2.11.1" - resolved "https://registry.yarnpkg.com/autocorrect-node/-/autocorrect-node-2.11.1.tgz#5e84f6541a2f62e9eb5858f46d6bcc6f610b5920" - integrity sha512-xalvvRcynT9BEKCq05SinOkaoINtmkqWk8qHQMh/R6ZA962we3W+zv1I4Qx6Ac3CcegSbGoJgCcYM59ZABhBNQ== +autocorrect-node-darwin-arm64@2.12.0: + version "2.12.0" + resolved "https://registry.yarnpkg.com/autocorrect-node-darwin-arm64/-/autocorrect-node-darwin-arm64-2.12.0.tgz#48e97140979bc8931c7adaff0c4cd88d791efbfb" + integrity sha512-40CtwUvV9/NIWbfrNeQG84ubpoNi5P5Bn/tATt3l+hCDu/x8wx2cOqmw6+ff6RZQdCsTrUWQ79QA8cwck9JoFA== + +autocorrect-node-darwin-x64@2.12.0: + version "2.12.0" + resolved "https://registry.yarnpkg.com/autocorrect-node-darwin-x64/-/autocorrect-node-darwin-x64-2.12.0.tgz#5a468c93fa144dd6595667def11429ad3c1994ab" + integrity sha512-d3VWYpLc1Ed2IoP5nBbS6uvbW3qn4EsaMJbOIRD0DdLI+k4OsLCwqNRF3+lMqWGGjaEgPnGYJMe5iswyULqKLg== + +autocorrect-node-linux-x64-gnu@2.12.0: + version "2.12.0" + resolved "https://registry.yarnpkg.com/autocorrect-node-linux-x64-gnu/-/autocorrect-node-linux-x64-gnu-2.12.0.tgz#126f71b7a968f33aab6c30a4f9abcbe90be31d6e" + integrity sha512-M5ebzPmr9fI63pf4x/3XOHyif5mhYEFssvH/T+frLaMeTCxdlv1bo5374HCJkpo1nF9OtfU+67EgmqQlYXEZyw== + +autocorrect-node-linux-x64-musl@2.12.0: + version "2.12.0" + resolved "https://registry.yarnpkg.com/autocorrect-node-linux-x64-musl/-/autocorrect-node-linux-x64-musl-2.12.0.tgz#5ed91722f5353cd5eb9e6d4b4cf5b5409fbff712" + integrity sha512-tFdMJdEsHtAf18L/Ctsjw5+zDIJlRoPeVSwvoreYTiVmF+hbFT2GLIcDsy+KRgSL912VCYFmRnV0BWhHKDHmqw== + +autocorrect-node-win32-x64-msvc@2.12.0: + version "2.12.0" + resolved "https://registry.yarnpkg.com/autocorrect-node-win32-x64-msvc/-/autocorrect-node-win32-x64-msvc-2.12.0.tgz#5c1206ec88010c8c2100535f3071c5e960e6a3cf" + integrity sha512-tM9eGRtwoKMCeqpOsi8VsLJ8XfCTjvnwmceiXps0kkbVEXHiOg5rQfbnRxqkdDIFvMF0EUaWBKugW1COQdxpfg== + +autocorrect-node@2.12.0: + version "2.12.0" + resolved "https://registry.yarnpkg.com/autocorrect-node/-/autocorrect-node-2.12.0.tgz#eb5b2867d7f557dc90a103bf2188ac02196a8a59" + integrity sha512-EvFr9N0whajPMpEm+UceE6x9VNqTfmCUfCcZ10/7pYXM0b8emLMo/J404mzTgZkmBwh5jD5VNNvumkKF9jRyrg== optionalDependencies: - autocorrect-node-darwin-arm64 "2.11.1" - autocorrect-node-darwin-x64 "2.11.1" - autocorrect-node-linux-x64-gnu "2.11.1" - autocorrect-node-linux-x64-musl "2.11.1" - autocorrect-node-win32-x64-msvc "2.11.1" + autocorrect-node-darwin-arm64 "2.12.0" + autocorrect-node-darwin-x64 "2.12.0" + autocorrect-node-linux-x64-gnu "2.12.0" + autocorrect-node-linux-x64-musl "2.12.0" + autocorrect-node-win32-x64-msvc "2.12.0" balanced-match@^1.0.0: version "1.0.2" From e64184215f4229a90055f8a999be0f71fb281e65 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 16:25:13 +0900 Subject: [PATCH 020/221] =?UTF-8?q?2023/02/19=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/svgnumber/index.md | 32 +++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 files/ja/web/api/svgnumber/index.md diff --git a/files/ja/web/api/svgnumber/index.md b/files/ja/web/api/svgnumber/index.md new file mode 100644 index 00000000000000..5da4ab7487eb37 --- /dev/null +++ b/files/ja/web/api/svgnumber/index.md @@ -0,0 +1,32 @@ +--- +title: SVGNumber +slug: Web/API/SVGNumber +l10n: + sourceCommit: 226ac33eb70ed5411dd2d68bd602c80cafd780b6 +--- + +{{APIRef("SVG")}} + +**`SVGNumber`** インターフェイスは、{{cssxref("<number>")}} 基本データ型に対応します。 + +`SVGNumber` オブジェクトは読み取り専用として指定されていることがあり、その場合はオブジェクトを変更しようとすると例外が発生します。 + +## インスタンスプロパティ + +- {{domxref("SVGNumber.value")}} + + - : 数値を表す浮動小数点数です。 + + メモ: `SVGNumber` が読み取り専用である場合、この値を変更しようとすると {{domxref("DOMException")}} が NO_MODIFICATION_ALLOWED_ERR のコードで発生します。 + +## インスタンスメソッド + +_このインターフェイスは固有のメソッドを提供していません。_ + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} From d71a427712571be0cd51802088bcb407705a7723 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 10 Oct 2024 17:19:26 +0900 Subject: [PATCH 021/221] =?UTF-8?q?2024/09/03=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/svglength/index.md | 320 ++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 files/ja/web/api/svglength/index.md diff --git a/files/ja/web/api/svglength/index.md b/files/ja/web/api/svglength/index.md new file mode 100644 index 00000000000000..254b949d8631e0 --- /dev/null +++ b/files/ja/web/api/svglength/index.md @@ -0,0 +1,320 @@ +--- +title: SVGLength +slug: Web/API/SVGLength +l10n: + sourceCommit: b25d8774aa7bcc6a053e26cf804ad454f51e134b +--- + +{{APIRef("SVG")}} + +## SVG length インターフェイス + +`SVGLength` インターフェイスは、[\](/ja/docs/Web/SVG/Content_type#length) 基本データ型に対応します。 + +`SVGLength` オブジェクトは読み取り専用として指定されていることがあり、その場合はオブジェクトを変更しようとすると例外が発生します。 + +### インターフェイス概要 + + + + + + + + + + + + + + + + + + + + + + + + +
実装しているものなし
メソッド +
    +
  • + void newValueSpecifiedUnits(in unsigned short + unitType, in float + valueInSpecifiedUnits) +
    • +
  • + void convertToSpecifiedUnits(in unsigned short + unitType) +
    • +
+
プロパティ +
    +
  • readonly unsigned short unitType
    • +
  • float value
    • +
  • float valueInSpecifiedUnits
    • +
  • + string valueAsString +
    • +
+
定数 +
    +
  • SVG_LENGTHTYPE_UNKNOWN = 0
    • +
  • SVG_LENGTHTYPE_NUMBER = 1
    • +
  • SVG_LENGTHTYPE_PERCENTAGE = 2
    • +
  • SVG_LENGTHTYPE_EMS = 3
    • +
  • SVG_LENGTHTYPE_EXS = 4
    • +
  • SVG_LENGTHTYPE_PX = 5
    • +
  • SVG_LENGTHTYPE_CM = 6
    • +
  • SVG_LENGTHTYPE_MM = 7
    • +
  • SVG_LENGTHTYPE_IN = 8
    • +
  • SVG_LENGTHTYPE_PT = 9
    • +
  • SVG_LENGTHTYPE_PC = 10
    • +
+
正規文書 + SVG 1.1 (2nd Edition) +
+ +## 例 + +```xml + + + + +``` + +Results on a desktop monitor (pixel units will be dpi-dependent): + +```plain +value: 37.7952766418457, valueInSpecifiedUnits: 6: 1, valueAsString: 1cm +value: 26.66666603088379, valueInSpecifiedUnits 9: 20, valueAsString: 20pt +value: 26.66666603088379, valueInSpecifiedUnits 8: 0.277777761220932, valueAsString: 0.277778in +``` + +## 定数 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名前値説明
SVG_LENGTHTYPE_UNKNOWN0 + 単位の型が定義済みの単位の型ではありません。この型の新しい値を定義しようとしたり、既存の値をこの型に切り替えようとしたりすることはできません。 +
SVG_LENGTHTYPE_NUMBER1 + 単位の型が指定されておらず（すなわち、単位のない値が指定されています）。ユーザー単位での値を示しています。 +
SVG_LENGTHTYPE_PERCENTAGE2パーセント値が指定されていました。
SVG_LENGTHTYPE_EMS3値が em 単位（CSS2 で定義）を使用して指定されていました。
SVG_LENGTHTYPE_EXS4値が ex 単位（CSS2 で定義）を使用して指定されていました。
SVG_LENGTHTYPE_PX5値が px 単位（CSS2 で定義）を使用して指定されていました。
SVG_LENGTHTYPE_CM6値が cm 単位（CSS2 で定義）を使用して指定されていました。
SVG_LENGTHTYPE_MM7値が mm 単位（CSS2 で定義）を使用して指定されていました。
SVG_LENGTHTYPE_IN8値が in 単位（CSS2 で定義）を使用して指定されていました。
SVG_LENGTHTYPE_PT9値が pt 単位（CSS2 で定義）を使用して指定されていました。
SVG_LENGTHTYPE_PC10値が pc 単位（CSS2 で定義）を使用して指定されていました。
+ +## インスタンスプロパティ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名前型解説
unitTypeunsigned short + 値の型で、このインターフェイスで定義されている SVG_LENGTHTYPE_* 定数のいずれかで指定されます。 +
valuefloat +

+ ユーザー単位における浮動小数点数値としての値。この属性を設定すると、この設定を反映して、valueInSpecifiedUnits と valueAsString が自動的に更新されます。 +

+

+ 設定時の例外: 長さが読み取り専用属性に対応している場合、またはオブジェクト自体が読み取り専用である場合に、{{ domxref("DOMException") }} 例外が NO_MODIFICATION_ALLOWED_ERR のコードで発生します。 +

+
valueInSpecifiedUnitsfloat +

+ unitType で指定された単位における浮動小数点数としての値。この属性を設定すると、value および valueAsString が自動的に更新され、この設定が反映されます。 +

+

+ 設定時の例外: 長さが読み取り専用属性に対応している場合、またはオブジェクト自体が読み取り専用である場合に、{{ domxref("DOMException") }} 例外が NO_MODIFICATION_ALLOWED_ERR のコードで発生します。 +

+
valueAsStringstring +

+ unitType で指定された単位での文字列値。この属性を設定すると、value、valueInSpecifiedUnits、unitType が自動的に更新され、この設定が反映されます。 +

+

設定時の例外:

+
    +
  • + 代入された文字列が有効な <length> として解釈できない場合、{{ domxref("DOMException") }} 例外が SYNTAX_ERR のコードで発生します。 +
    • +
  • + 長さが読み取り専用属性に対応している場合、またはオブジェクト自体が読み取り専用である場合に、{{ domxref("DOMException") }} 例外が NO_MODIFICATION_ALLOWED_ERR のコードで発生します。 +
    • +
+
+ +## インスタンスメソッド + + + + + + + + + + + + + + + + + + + + + +
名前と引数返値説明
+ newValueSpecifiedUnits(in unsigned short + unitType, in float valueInSpecifiedUnits) + void +

+ 関連する unitType を伴う数値として値をリセットし、それによってこのオブジェクト上のすべての属性の値を置き換えます。 +

+

例外:

+
    +
  • + unitType が SVG_LENGTHTYPE_UNKNOWN である場合、または有効な単位型定数（このインターフェイスで定義されている他の SVG_LENGTHTYPE_* 定数のいずれか）でない場合、{{ domxref("DOMException") }} が NOT_SUPPORTED_ERR のコードで発生します。 +
    • +
  • + 長さが読み取り専用属性に一致する場合、またはオブジェクト自体が読み取り専用である場合に、{{ domxref("DOMException") }} が NO_MODIFICATION_ALLOWED_ERR のコードで発生します。 +
    • +
+
+ convertToSpecifiedUnits(in unsigned short + unitType) + void + ベースとして保存された値は同じままですが、格納された単位識別子は指定された unitType にリセットされます。このメソッドの結果として、オブジェクトの unitType、valueInSpecifiedUnits、valueAsString の各属性が変更される場合があります。例えば、元の値が "0.5cm" で、ミリメートルへの変換を呼び出した場合、 unitType は SVG_LENGTHTYPE_MM に、valueInSpecifiedUnits は数値 5 に、valueAsString は "5mm" に変更されます。 +
+ +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} From 5a8200194a4e681acbd73cdcf48518add453643f Mon Sep 17 00:00:00 2001 From: Albert Khoroshun Date: Mon, 14 Oct 2024 19:17:48 +0500 Subject: [PATCH 022/221] =?UTF-8?q?[ru]=20Improve=20translation:=20Using?= =?UTF-8?q?=20"=D0=BA=D1=83=D1=81=D0=BE=D0=BA"=20instead=20of=20"=D0=B1?= =?UTF-8?q?=D0=B8=D1=82"=20in=20some=20contexts=20(#23871)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Improve translation: Using "кусок" instead of "бит" in some contexts * used "сегмент" и "часть" instead of "кусок" --- files/ru/learn/javascript/objects/json/index.md | 2 +- .../learn/javascript/objects/object_building_practice/index.md | 2 +- files/ru/web/http/messages/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/files/ru/learn/javascript/objects/json/index.md b/files/ru/learn/javascript/objects/json/index.md index ae4ce4f6347a18..533bf26cbfd50d 100644 --- a/files/ru/learn/javascript/objects/json/index.md +++ b/files/ru/learn/javascript/objects/json/index.md @@ -185,7 +185,7 @@ var section = document.querySelector("section"); request.send(); ``` -5. Последний бит этого раздела предполагает ожидание ответа на возврат с сервера, а затем работы с ним. Добавьте следующий код ниже вашего предыдущего кода: +5. Последняя часть этого раздела предполагает ожидание ответа на возврат с сервера, а затем работы с ним. Добавьте следующий код ниже вашего предыдущего кода: ```js request.onload = function () { diff --git a/files/ru/learn/javascript/objects/object_building_practice/index.md b/files/ru/learn/javascript/objects/object_building_practice/index.md index acaeee7859ae8e..679ee9682db11d 100644 --- a/files/ru/learn/javascript/objects/object_building_practice/index.md +++ b/files/ru/learn/javascript/objects/object_building_practice/index.md @@ -44,7 +44,7 @@ var height = (canvas.height = window.innerHeight); Вы увидите здесь, что мы объединяем несколько назначений вместе, чтобы все переменные были установлены быстрее - это совершенно нормально. -Последний бит исходного скрипта выглядит следующим образом: +Последняя часть исходного скрипта выглядит следующим образом: ```js function random(min, max) { diff --git a/files/ru/web/http/messages/index.md b/files/ru/web/http/messages/index.md index 62da29bc83bc5a..cc90765d4f5e0d 100644 --- a/files/ru/web/http/messages/index.md +++ b/files/ru/web/http/messages/index.md @@ -64,7 +64,7 @@ HTTP запросы - это сообщения, отправляемые кли Тела можно грубо разделить на две категории: - Одноресурсные тела (Single-resource bodies), состоящие из одного отдельного файла, определяемого двумя заголовками: {{HTTPHeader("Content-Type")}} и {{HTTPHeader("Content-Length")}}. -- [Многоресурсные тела (Multiple-resource bodies](/ru/docs/Web/HTTP/Basics_of_HTTP/MIME_types#multipartform-data)), состоящие из множества частей, каждая из которых содержит свой бит информации. Они обычно связаны с [HTML-формами](/ru/docs/Web/Guide/HTML/Forms). +- [Многоресурсные тела (Multiple-resource bodies](/ru/docs/Web/HTTP/Basics_of_HTTP/MIME_types#multipartform-data)), состоящие из множества частей, каждая из которых содержит свой сегмент информации. Они обычно связаны с [HTML-формами](/ru/docs/Web/Guide/HTML/Forms). ## Ответы HTTP From 426c1bd057909b60bf57143dea78cabb039a19c5 Mon Sep 17 00:00:00 2001 From: v-gb Date: Mon, 14 Oct 2024 10:40:45 -0400 Subject: [PATCH 023/221] fr: switch to 1990 spelling in webextension i18n doc (#19382) * fr: switch to 1990 spelling in webextension i18n doc * Update files/fr/mozilla/add-ons/webextensions/internationalization/index.md Co-authored-by: tristantheb --------- Co-authored-by: tristantheb --- .../internationalization/index.md | 70 +++++++++---------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/files/fr/mozilla/add-ons/webextensions/internationalization/index.md b/files/fr/mozilla/add-ons/webextensions/internationalization/index.md index 02a1d199cc0411..aa6fa514a90562 100644 --- a/files/fr/mozilla/add-ons/webextensions/internationalization/index.md +++ b/files/fr/mozilla/add-ons/webextensions/internationalization/index.md @@ -19,11 +19,11 @@ Une extension internationalisée peut contenir les mêmes fonctionnalités que n - `répertoire-racine-de-l'extension/` - `_locales` - `en` - - `messages.json` : un fichier qui contiendra les chaînes de caractères en anglais + - `messages.json` : un fichier qui contiendra les chaines de caractères en anglais - `fr_FR` - - `messages.json` : un fichier qui contiendra les chaînes de caractères en français + - `messages.json` : un fichier qui contiendra les chaines de caractères en français - `de` - - `messages.json` : un fichier qui contiendra les chaînes de caractères en allemand + - `messages.json` : un fichier qui contiendra les chaines de caractères en allemand - etc. - `manifest.json` : des métadonnées relatives aux locales sont ajoutées au [manifeste](/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json) - `fichierJavaScript.js` : de la logique pour récupérer la locale du navigateur, récupérer les messages spécifiques à la locale courante, etc. @@ -31,9 +31,9 @@ Une extension internationalisée peut contenir les mêmes fonctionnalités que n Examinons chacune de ces fonctionnalités supplémentaires. Chacune des sections qui suit représente une étape à suivre pour l'internationalisation de votre extension. -## Fournir des chaînes localisées dans `_locales` +## Fournir des chaines localisées dans `_locales` -L'internationalisation nécessite de fournir des chaînes traduites pour les différentes locales qu'on souhaite prendre en charge. Pour les extensions, le répertoire `_locales`, présent à la racine de l'extension, contient un sous-répertoire pour chaque locale, nommé grâce à [l'étiquette de langue correspondante](https://fr.wikipedia.org/wiki/%C3%89tiquette_d%27identification_de_langues_IETF) et ce dernier contient un fichier `messages.json` avec les chaînes de caractères traduites pour la locale correspondante. +L'internationalisation nécessite de fournir des chaines traduites pour les différentes locales qu'on souhaite prendre en charge. Pour les extensions, le répertoire `_locales`, présent à la racine de l'extension, contient un sous-répertoire pour chaque locale, nommé grâce à [l'étiquette de langue correspondante](https://fr.wikipedia.org/wiki/%C3%89tiquette_d%27identification_de_langues_IETF) et ce dernier contient un fichier `messages.json` avec les chaines de caractères traduites pour la locale correspondante. > [!WARNING] > Contrairement à la convention qui consiste à séparer la sous-étiquette de base et celle de la variante régionale par un tiret (par exemple `en-US` ou `fr-CA`), **il faudra utiliser un tiret bas pour le nom du répertoire sous `_locales`** (par exemple `en_US` ou `fr_CA`). @@ -75,7 +75,7 @@ Regardons maintenant la structure de l'un de ces fichiers ([`_locales/en/message } ``` -Ce fichier est du JSON standard, chaque propriété est un objet avec un nom, qui contient une propriété `message` et une propriété `description`. Tous ces éléments sont des chaînes de caractères et `$URL$` est un emplacement de substitution qui sera remplacé par une sous-chaîne lorsque la propriété `notificationContent` sera manipulée par l'extension. Nous verrons comment faire dans la section [Récupération des messages localisés dans le code JavaScript](#récupérer_des_messages_localisés_dans_le_code_javascript). +Ce fichier est du JSON standard, chaque propriété est un objet avec un nom, qui contient une propriété `message` et une propriété `description`. Tous ces éléments sont des chaines de caractères et `$URL$` est un emplacement de substitution qui sera remplacé par une sous-chaine lorsque la propriété `notificationContent` sera manipulée par l'extension. Nous verrons comment faire dans la section [Récupération des messages localisés dans le code JavaScript](#récupérer_des_messages_localisés_dans_le_code_javascript). > [!NOTE] > Pour plus d'informations sur le contenu des fichiers `messages.json`, voir [la référence des formats de messages localisés](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference). @@ -84,9 +84,9 @@ Ce fichier est du JSON standard, chaque propriété est un objet avec un nom, qu Plusieurs actions sont nécessaires pour internationaliser le manifeste (`manifest.json`) de l'extension. -### Récupérer les chaînes localisées dans le manifeste +### Récupérer les chaines localisées dans le manifeste -[Le manifeste de l'extension](https://github.com/mdn/webextensions-examples/blob/main/notify-link-clicks-i18n/manifest.json) contient des chaînes de caractères qui seront visibles de l'utilisatrice et de l'utilisateur, comme le nom et la description de l'extension. Si vous internationalisez ces propriétés et placez les traductions appropriées dans les fichiers `messages.json`, la traduction appropriée sera affichée en fonction des paramètres de locale du navigateur. +[Le manifeste de l'extension](https://github.com/mdn/webextensions-examples/blob/main/notify-link-clicks-i18n/manifest.json) contient des chaines de caractères qui seront visibles de l'utilisatrice et de l'utilisateur, comme le nom et la description de l'extension. Si vous internationalisez ces propriétés et placez les traductions appropriées dans les fichiers `messages.json`, la traduction appropriée sera affichée en fonction des paramètres de locale du navigateur. Pour internationaliser ces propriétés, renseignez le manifeste ainsi : @@ -95,12 +95,12 @@ Pour internationaliser ces propriétés, renseignez le manifeste ainsi : "description": "__MSG_extensionDescription__", ``` -Ces valeurs spéciales indiqueront au navigateur de rechercher la chaîne localisée correspondante, plutôt que d'utiliser la mème valeur statique pour toutes les locales. +Ces valeurs spéciales indiqueront au navigateur de rechercher la chaine localisée correspondante, plutôt que d'utiliser la même valeur statique pour toutes les locales. -Pour faire référence à un message localisé, composez la chaîne de caractères en concaténant : +Pour faire référence à un message localisé, composez la chaine de caractères en concaténant : 1. Deux tirets bas (`__`) -2. La chaîne `MSG` +2. La chaine `MSG` 3. Un tiret bas (`_`) 4. Le nom du message visé, tel qu'il est défini dans `messages.json` 5. Deux tirets bas (`__`) @@ -127,7 +127,7 @@ Si un message n'est pas disponible dans la locale courante du navigateur, ce der ## Utiliser du code CSS variant selon la locale -Il est aussi possible d'utiliser des chaînes localisées au sein des fichiers CSS de l'extension. Par exemple, on pourra ainsi construire une règle CSS qui varie selon la locale : +Il est aussi possible d'utiliser des chaines localisées au sein des fichiers CSS de l'extension. Par exemple, on pourra ainsi construire une règle CSS qui varie selon la locale : ```css header { @@ -170,15 +170,15 @@ La première ligne récupère le message avec l'identifiant `notificationTitle` } ``` -La propriété `"placeholders"` définit tous les emplacements de substitution ainsi que leur origine pour le remplacement. Pour `"url"`, l'origine du contenu est `$1`, ce qui correspond à la première valeur passée dans le second paramètre de `getMessage()`. Puisque l'emplacement de substitution est appelé `"url"`, nous utilisons `$URL$` pour l'appeler dans la chaîne de message (pour `"nomdemplacement"` vous utiliserez `$NOMDEMPLACEMENT$`, etc.). Si un message possède plusieurs emplacements de substitution, les valeurs à remplacer pourront être fournies sous la forme d'un tableau, passé en deuxième paramètre à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage). Ainsi, fournir le tableau `[a, b, c]` permettra de fournir des valeurs pour les emplacements de substitution dont les origines respectives sont `$1`, `$2`, et `$3`. +La propriété `"placeholders"` définit tous les emplacements de substitution ainsi que leur origine pour le remplacement. Pour `"url"`, l'origine du contenu est `$1`, ce qui correspond à la première valeur passée dans le second paramètre de `getMessage()`. Puisque l'emplacement de substitution est appelé `"url"`, nous utilisons `$URL$` pour l'appeler dans la chaine de message (pour `"nomdemplacement"` vous utiliserez `$NOMDEMPLACEMENT$`, etc.). Si un message possède plusieurs emplacements de substitution, les valeurs à remplacer pourront être fournies sous la forme d'un tableau, passé en deuxième paramètre à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage). Ainsi, fournir le tableau `[a, b, c]` permettra de fournir des valeurs pour les emplacements de substitution dont les origines respectives sont `$1`, `$2`, et `$3`. -Par exemple, dans le fichier `en/messages.json`, la chaîne originale du message `notificationContent` est +Par exemple, dans le fichier `en/messages.json`, la chaine originale du message `notificationContent` est ``` You clicked $URL$. ``` -Si le lien sur lequel on a cliqué pointe vers `https://developer.mozilla.org`, après l'appel à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage), le contenu du deuxième paramètre sera mis à disposition via l'origine `$1`, et remplacera la sous-chaîne `$URL$` tel que défini dans `"url"`. La chaîne de caractères finalement obtenue sera donc : +Si le lien sur lequel on a cliqué pointe vers `https://developer.mozilla.org`, après l'appel à [`i18n.getMessage()`](/fr/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage), le contenu du deuxième paramètre sera mis à disposition via l'origine `$1`, et remplacera la sous-chaine `$URL$` tel que défini dans `"url"`. La chaine de caractères finalement obtenue sera donc : ``` You clicked https://developer.mozilla.org. @@ -186,7 +186,7 @@ You clicked https://developer.mozilla.org. ### Utilisation directe d'un emplacement de substitution -Il est possible d'insérer vos variables (`$1`, `$2`, `$3`, etc.) directement dans les chaînes de message. Par exemple nous pourrions réécrire la propriété `"notificationContent"` comme ceci : +Il est possible d'insérer vos variables (`$1`, `$2`, `$3`, etc.) directement dans les chaines de message. Par exemple nous pourrions réécrire la propriété `"notificationContent"` comme ceci : ```json "notificationContent": { @@ -199,7 +199,7 @@ Cela peut sembler plus rapide et moins complexe, mais l'utilisation de `"placeho ### Substitution codée en dur -Il est également possible d'inclure des chaînes statiques dans des emplacements de substitution, de sorte que la même valeur soit utilisée à chaque fois plutôt que d'obtenir la valeur d'une variable dans le code. Par exemple : +Il est également possible d'inclure des chaines statiques dans des emplacements de substitution, de sorte que la même valeur soit utilisée à chaque fois plutôt que d'obtenir la valeur d'une variable dans le code. Par exemple : ```json "mdn_banner": { @@ -213,18 +213,18 @@ Il est également possible d'inclure des chaînes statiques dans des emplacement } ``` -Dans ce cas, nous plaçons une chaîne statique pour la substitution plutôt que de l'obtenir à partir d'une variable comme `$1`. Cette technique peut s'avérer utile lorsque le fichier de messages est très complexe et qu'il devient nécessaire de séparer différentes valeurs afin de rendre le fichier plus lisible. De plus, ces valeurs sont alors accessibles en JavaScript. +Dans ce cas, nous plaçons une chaine statique pour la substitution plutôt que de l'obtenir à partir d'une variable comme `$1`. Cette technique peut s'avérer utile lorsque le fichier de messages est très complexe et qu'il devient nécessaire de séparer différentes valeurs afin de rendre le fichier plus lisible. De plus, ces valeurs sont alors accessibles en JavaScript. -En outre, vous pouvez utiliser ces substitutions pour spécifier les parties de la chaîne que vous ne souhaitez pas traduire, telles que les noms de personne ou d'entreprise. +En outre, vous pouvez utiliser ces substitutions pour spécifier les parties de la chaine que vous ne souhaitez pas traduire, telles que les noms de personne ou d'entreprise. -## Algorithme de sélection de la chaîne de caractères localisée +## Algorithme de sélection de la chaine de caractères localisée -Les locales peuvent être indiquées à l'aide d'une simple étiquette de langue comme `fr` ou `en`, ou avec en plus une sous-étiquette de région comme `en_US` ou `en_GB`. Lorsqu'on utilise l'API `i18n` afin de récupérer une chaîne de caractères localisée, le navigateur utilise l'algorithme suivant : +Les locales peuvent être indiquées à l'aide d'une simple étiquette de langue comme `fr` ou `en`, ou avec en plus une sous-étiquette de région comme `en_US` ou `en_GB`. Lorsqu'on utilise l'API `i18n` afin de récupérer une chaine de caractères localisée, le navigateur utilise l'algorithme suivant : -1. S'il existe un fichier `messages.json` pour exactement la locale courante, et si ce fichier contient la chaîne demandée, c'est celle-ci qui est renvoyée. -2. Sinon, si la locale courante est fournie avec une sous-étiquette de région (par exemple `en_US`) et qu'il existe un fichier `messages.json` pour l'étiquette de langue correspondante sans région (par exemple `en`), et si ce fichier contient la chaîne, c'est celle-ci qui est renvoyée. -3. Sinon, s'il existe un fichier `messages.json` pour la locale par défaut (fournie via la propriété du manifeste `default_locale`), et que ce fichier contient la chaîne, c'est celle-ci qui est renvoyée. -4. Sinon, c'est la chaîne de caractères vide qui est renvoyée. +1. S'il existe un fichier `messages.json` pour exactement la locale courante, et si ce fichier contient la chaine demandée, c'est celle-ci qui est renvoyée. +2. Sinon, si la locale courante est fournie avec une sous-étiquette de région (par exemple `en_US`) et qu'il existe un fichier `messages.json` pour l'étiquette de langue correspondante sans région (par exemple `en`), et si ce fichier contient la chaine, c'est celle-ci qui est renvoyée. +3. Sinon, s'il existe un fichier `messages.json` pour la locale par défaut (fournie via la propriété du manifeste `default_locale`), et que ce fichier contient la chaine, c'est celle-ci qui est renvoyée. +4. Sinon, c'est la chaine de caractères vide qui est renvoyée. Prenons la structure d'exemple suivante : @@ -239,12 +239,12 @@ Prenons la structure d'exemple suivante : Supposons que `default_locale` vaille `fr`, et que la locale courante du navigateur soit `en_GB` : -- Si l'extension appelle `getMessage("colorLocalised")`, c'est la chaîne `"colour"` qui sera renvoyée +- Si l'extension appelle `getMessage("colorLocalised")`, c'est la chaine `"colour"` qui sera renvoyée - Si `colorLocalised` n'était pas présent dans le fichier pour `en_GB`, `getMessage("colorLocalised")` renverrait alors `"color"` (car `en` est l'étiquette de langue sans région correspondante à `en_GB`), et pas `"couleur"`. ## Messages prédéfinis -L'API `i18n` permet d'utiliser des messages prédéfinis, de la même façon que pour [récupérer les chaînes localisées dans le manifeste](#récupérer_les_chaînes_localisées_dans_le_manifeste) ou [depuis le code CSS](#utiliser_du_code_css_variant_selon_la_locale). Par exemple : +L'API `i18n` permet d'utiliser des messages prédéfinis, de la même façon que pour [récupérer les chaines localisées dans le manifeste](#récupérer_les_chaînes_localisées_dans_le_manifeste) ou [depuis le code CSS](#utiliser_du_code_css_variant_selon_la_locale). Par exemple : ``` __MSG_extensionName__ @@ -270,11 +270,11 @@ Le tableau suivant indique les différents messages prédéfinis disponibles&nbs @@extension_id

- L'UUID généré en interne pour l'extension. Vous pouvez utiliser cette chaîne pour créer des URL pour les ressources à l'intérieur de l'extension. Même les extensions non localisées peuvent utiliser ce message. + L'UUID généré en interne pour l'extension. Vous pouvez utiliser cette chaine pour créer des URL pour les ressources à l'intérieur de l'extension. Même les extensions non localisées peuvent utiliser ce message.

Vous ne pouvez pas utiliser ce message dans un fichier de manifeste.

- Notez également que cet identifiant ne correspond pas à l'identifiant renvoyé par runtime.id qui peut être défini à l'aide de la clé de manifeste browser_specific_settings. C'est l'UUID généré qui apparaît dans l'URL du module complémentaire. Cela signifie que vous ne pouvez pas utiliser cette valeur comme paramètre extensionId pour runtime.sendMessage(), et que vous + Notez également que cet identifiant ne correspond pas à l'identifiant renvoyé par runtime.id qui peut être défini à l'aide de la clé de manifeste browser_specific_settings. C'est l'UUID généré qui apparait dans l'URL du module complémentaire. Cela signifie que vous ne pouvez pas utiliser cette valeur comme paramètre extensionId pour runtime.sendMessage(), et que vous ne pouvez pas l'utiliser pour vérifier la propriété id d'un objet runtime.MessageSender.

@@ -282,31 +282,31 @@ Le tableau suivant indique les différents messages prédéfinis disponibles&nbs @@ui_locale - La locale courante. Cette chaîne peut être utilisée afin de construire des URL variant en fonction de la locale. + La locale courante. Cette chaine peut être utilisée afin de construire des URL variant en fonction de la locale. @@bidi_dir - La direction du texte pour la locale courante. Cette chaîne vaut "ltr" pour les langues écrites de gauche à droite telles que le français ou "rtl" pour les langues écrites de droite à gauche telles que l'arabe. + La direction du texte pour la locale courante. Cette chaine vaut "ltr" pour les langues écrites de gauche à droite telles que le français ou "rtl" pour les langues écrites de droite à gauche telles que l'arabe. @@bidi_reversed_dir - Si @@bidi_dir vaut "ltr", alors cette chaîne vaudra "rtl", sinon elle vaudra "ltr". + Si @@bidi_dir vaut "ltr", alors cette chaine vaudra "rtl", sinon elle vaudra "ltr". @@bidi_start_edge - Si @@bidi_dir vaut "ltr", alors cette chaîne vaudra "left", sinon elle vaudra "right". + Si @@bidi_dir vaut "ltr", alors cette chaine vaudra "left", sinon elle vaudra "right". @@bidi_end_edge - Si @@bidi_dir vaut "ltr", alors cette chaîne vaudra "right", sinon elle vaudra "left". + Si @@bidi_dir vaut "ltr", alors cette chaine vaudra "right", sinon elle vaudra "left". @@ -361,6 +361,6 @@ Pour tester la localisation de votre extension, utilisez [Firefox](https://www.m Ensuite, pour chaque locale que vous prenez en charge et que vous voulez tester, suivez les instructions de la page [Utiliser Firefox dans une autre langue](https://support.mozilla.org/fr/kb/utiliser-firefox-dans-autre-langue) afin de changer la locale utilisée pour l'interface utilisateur de Firefox (si vous connaissez les paramètres, allez dans la section Langue et utilisez Choisir des alternatives). -Lorsque Firefox utilise la locale à tester, [installez l'extension temporairement](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/). Après avoir installé votre extension, vérifiez dans la page `about:debugging` que votre extension est bien mise en place et que l'icône, le nom et la description apparaissent avec la bonne locale. Vous pouvez également vérifier les métadonnées localisées via la page `about:addons`. Finalement, utilisez les fonctionnalités de l'extension pour vérifier que les chaînes localisées sont bien présentes. +Lorsque Firefox utilise la locale à tester, [installez l'extension temporairement](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/). Après avoir installé votre extension, vérifiez dans la page `about:debugging` que votre extension est bien mise en place et que l'icône, le nom et la description apparaissent avec la bonne locale. Vous pouvez également vérifier les métadonnées localisées via la page `about:addons`. Finalement, utilisez les fonctionnalités de l'extension pour vérifier que les chaines localisées sont bien présentes. Si vous souhaitez vous faire la main sur ce processus de test, vous pouvez utiliser [l'exemple d'extension `notify-link-clicks-i18n`](https://github.com/mdn/webextensions-examples/tree/main/notify-link-clicks-i18n). Paramétrez Firefox pour qu'il s'affiche dans l'une des locales prise en charge (l'allemand, le néerlandais ou le japonais), chargez l'extension et allez sur un site web. Cliquez sur un lien pour voir la notification localisée indiquer le lien de l'URL. From 5c4c69409d336096b23acfe3e04cd2cbb0c82d01 Mon Sep 17 00:00:00 2001 From: SphinxKnight Date: Mon, 14 Oct 2024 18:44:23 +0200 Subject: [PATCH 024/221] Fix #23258 (#24009) Fixes #23258 with an update from en-US --- files/fr/web/http/methods/delete/index.md | 90 +++++++++++++++-------- 1 file changed, 61 insertions(+), 29 deletions(-) diff --git a/files/fr/web/http/methods/delete/index.md b/files/fr/web/http/methods/delete/index.md index 6f7568a12b7c87..3d879e775a6252 100644 --- a/files/fr/web/http/methods/delete/index.md +++ b/files/fr/web/http/methods/delete/index.md @@ -1,41 +1,40 @@ --- title: DELETE slug: Web/HTTP/Methods/DELETE +l10n: + sourceCommit: 803a7a460338dab4900fd44cf7ab569e3bf5799a --- {{HTTPSidebar}} -La **méthode HTTP DELETE** supprime la ressource indiquée. +La méthode HTTP **`DELETE`** demande au serveur de supprimer une ressource donnée. + +La méthode `DELETE` n'a pas de sémantique définie pour le corps du message, qui devrait donc être vide. - - + + - - + + - + - + - + - @@ -44,33 +43,61 @@ La **méthode HTTP DELETE** supprime la ressource indiquée. ## Syntaxe -``` -DELETE /file.html HTTP/1.1 +```http +DELETE ["?"] HTTP/1.1 ``` -## Exemple +- `` + - : Identifie la ressource cible de la requête lorsqu'elle est combinée avec l'information fournie par [l'en-tête `Host`](/fr/docs/Web/HTTP/Headers/Host). Il s'agit d'un chemin absolu (par exemple `/chemin/vers/fichier.html`) pour les requêtes vers un serveur originel et d'une URL absolue pour les requêtes vers les serveurs mandataires (proxies) (par exemple `http://www.example.com/chemin/vers/fichier.html`). +- `` {{optional_inline}} + - : Un fragment de requête optionnel précédé d'un point d'interrogation `?`. Utilisé généralement pour fournir de l'information sous la forme de paires `clé=valeur`. -### Requête +## Exemples -``` -DELETE /file.html HTTP/1.1 -``` +### Suppression d'une ressource -### Réponses +La requête suivante demande au serveur la suppression de la ressource `fichier.html` : -Si une méthode `DELETE` est appliquée avec succès, il y a plusieurs codes de statut de réponse possibles : +```http +DELETE /fichier.html HTTP/1.1 +Host: example.com +``` -- Un code de statut {{HTTPStatus("202")}} (`Accepted`) si l'action est en passe de réussir mais n'a pas encore été confirmée. -- Un code de statut {{HTTPStatus("204")}} (`No Content`) si l'action a été confirmée et qu'aucune information supplémentaire n'est à fournir. -- Un code de statut {{HTTPStatus("200")}} (`OK`) si l'action a été confirmée et que le message de réponse inclut une représentation décrivant le statut. +Si la requête réussit, plusieurs [codes de statut de réponses](/fr/docs/Web/HTTP/Status#successful_responses) peuvent être renvoyés. +Une réponse [`204 No Content`](/fr/docs/Web/HTTP/Status/204) indique que la requête a réussi et qu'aucune information supplémentaire ne doit être fournie au client en retour : +```http +HTTP/1.1 204 No Content +Date: Wed, 04 Sep 2024 10:16:04 GMT ``` + +Une réponse [`200 OK`](/fr/docs/Web/HTTP/Status/200) indique que la requête réussit et que le corps de la réponse inclut une représentation décrivant le résultat : + +```http HTTP/1.1 200 OK -Date: Wed, 21 Oct 2015 07:28:00 GMT +Content-Type: text/html; charset=UTF-8 +Date: Fri, 21 Jun 2024 14:18:33 GMT +Content-Length: 1234 + + + +

Fichier "fichier.html" supprimé.

+ + +``` + +Une réponse [`202 Accepted`](/fr/docs/Web/HTTP/Status/202) indique que la requête a été acceptée et qu'elle réussira probablement, mais que la ressource n'a pas encore été supprimée du serveur. + +```http +HTTP/1.1 202 Accepted +Date: Wed, 26 Jun 2024 12:00:00 GMT +Content-Type: text/html; charset=UTF-8 +Content-Length: 1234 -

File deleted.

+

Suppression acceptée pour "fichier.html".

+

Voir la console de statut pour plus de détails.

``` @@ -85,4 +112,9 @@ Date: Wed, 21 Oct 2015 07:28:00 GMT ## Voir aussi -- HTTP status: {{HTTPStatus("200")}}, {{HTTPStatus("202")}}, {{HTTPStatus("204")}} +- [Les méthodes des requêtes HTTP](/fr/docs/Web/HTTP/Methods) +- [Les codes de statut des réponses HTTP](/fr/docs/Web/HTTP/Status) + - [200](/fr/docs/Web/HTTP/Status/200) + - [202](/fr/docs/Web/HTTP/Status/202) + - [204](/fr/docs/Web/HTTP/Status/204) +- [Les en-têtes HTTP](/fr/docs/Web/HTTP/Headers) From 2696ad7a861600459527dce55f226f6ca6373544 Mon Sep 17 00:00:00 2001 From: SphinxKnight Date: Mon, 14 Oct 2024 19:08:55 +0200 Subject: [PATCH 025/221] Fix #23947 (#23971) * Fix #23947with an update * apply fix from @yin1999 Co-authored-by: A1lo --------- Co-authored-by: A1lo --- .../reference/trailing_commas/index.md | 187 +++++++++++++----- 1 file changed, 138 insertions(+), 49 deletions(-) diff --git a/files/fr/web/javascript/reference/trailing_commas/index.md b/files/fr/web/javascript/reference/trailing_commas/index.md index 29b9ae8c0369f1..36a6987895e7bc 100644 --- a/files/fr/web/javascript/reference/trailing_commas/index.md +++ b/files/fr/web/javascript/reference/trailing_commas/index.md @@ -1,95 +1,129 @@ --- title: Virgules finales (trailing commas) slug: Web/JavaScript/Reference/Trailing_commas +l10n: + sourceCommit: 2cd89ba0e74308b8f9bcd5937b76fd1188006358 --- {{JsSidebar("More")}} -Les **virgules finales** (_trailing commas_ en anglais) s'avèrent utiles lorsqu'on souhaite ajouter de nouveaux éléments, paramètres ou de nouvelles propriétés à du code JavaScript. Si on souhaite ajouter une propriété en fin de course, on peut simplement ajouter une ligne sans avoir à modifier la précédente si celle-ci utilise une virgule finale. Cela permet d'avoir des vues de différences (_diffs_) plus claires et de simplifier l'édition de code. +Les **virgules finales** (trailing commas en anglais) s'avèrent utiles lorsqu'on souhaite ajouter de nouveaux éléments, paramètres ou de nouvelles propriétés à du code JavaScript. Si on souhaite ajouter une propriété en fin de course, on peut simplement ajouter une ligne sans avoir à modifier la précédente si celle-ci utilise une virgule finale. Cela permet d'avoir des vues de différences (diffs) plus claires et de simplifier l'édition de code. -Les virgules finales peuvent être utilisées dans les littéraux de tableau depuis le début. Elles sont été ajoutées dans les littéraux objets à partir d'ECMAScript 5 et ECMAScript 2017 permet de les utiliser dans la liste des paramètres d'une fonction. +Les virgules finales peuvent être utilisées dans les littéraux de tableau depuis le début. Elles sont désormais utilisables dans la liste des paramètres d'une fonction, les imports nommés, les exports nommés, etc. -{{Glossary("JSON")}}, en revanche, ne permet pas d'utiliser des virgules finales. +[JSON](/fr/docs/Glossary/JSON), en revanche, ne permet pas d'utiliser des virgules finales. -## Les virgules finales dans les littéraux +## Description -### Tableaux +JavaScript permet d'utiliser des virgules finales à tout endroit où une liste de valeurs séparées par des virgules est acceptée et où plus de valeurs pourraient être attendues après le dernier élément. Cela inclut : -JavaScript ignore les virgules finales dans les tableaux : +- [Les littéraux de tableau](#tableaux) +- [Les littéraux objet](#objets) +- [Les définitions de paramètres](#définition_des_paramètres) +- [Les appels de fonction](#appels_de_fonction) +- [Les imports nommés](#imports_nommés) +- [Les exports nommés](#exports_nommés) +- [Les imports dynamiques](#virgules_finales_pour_limport_dynamique) +- [Les virgules finales et la décomposition](#les_virgules_finales_et_la_décomposition) -```js -var arr = [1, 2, 3]; +Pour tous ces cas, la virgule finale est tout à fait optionnelle et ne modifie en rien la sémantique du programme. + +La virgule finale sert notamment pour ajouter, retirer ou réordonner les éléments d'une liste écrite sur plusieurs lignes, car elle réduit le nombre de lignes à modifier, ce qui facilite l'édition et la revue de différence de code. + +```diff + [ + "toto", ++ "bidule", + "truc", +- "bidule", + ] +``` + +## Exemples + +### Les virgules finales dans les littéraux + +#### Tableaux + +JavaScript ignore les virgules finales dans les tableaux : + +```js-nolint +const arr = [ + 1, + 2, + 3, +]; arr; // [1, 2, 3] arr.length; // 3 ``` -Si plusieurs virgules finales sont utilisées, cela crée un vide dans le tableau. Un tableau avec des vides est parfois qualifié de _parsemé_ (ou _sparse_ en anglais). Lorsqu'on parcourt un tableau avec les méthodes {{jsxref("Array.prototype.forEach()")}} ou {{jsxref("Array.prototype.map()")}}, par exemple, ces vides sont ignorés. +Si plusieurs virgules finales sont utilisées, cela crée un vide dans le tableau. Un tableau avec des vides est parfois qualifié de [_parsemé_](/fr/docs/Web/JavaScript/Guide/Indexed_collections#tableaux_parsemés) (ou sparse en anglais). Lorsqu'on parcourt un tableau avec les méthodes [`Array.prototype.forEach()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) ou [`Array.prototype.map()`](/fr/docs/Web/JavaScript/Reference/Global_Objects/Array/map), par exemple, ces vides sont ignorés. De façon générale, les tableaux parsemés possèdent d'autres inconvénients, et mieux vaudra éviter d'avoir plusieurs virgules finales à la suite. ```js -var arr = [1, 2, 3, , ,]; +const arr = [1, 2, 3, , ,]; arr.length; // 5 ``` -### Objets +#### Objets -À partir d'ECMAScript 5, on peut également utiliser les virgules finales dans les littéraux objets : +On peut également utiliser les virgules finales dans les littéraux objets : ```js -var objet = { +const objet = { toto: "truc", - bidule: "azerty", + bidule: "ergo-L", age: 42, }; ``` -## Les virgules finales dans les fonctions +### Les virgules finales dans les fonctions -ECMAScript 2017 permet d'utiliser les virgules finales dans la liste des paramètres d'une fonction. +Les virgules finales peuvent être utilisées dans la liste des paramètres d'une fonction. -### Définitions des paramètres +#### Définition des paramètres -Pour chacune des deux paires de définitions qui suivent, les deux définitions sont autorisées et équivalentes entre elles. Les virgules finales n'ont pas d'impact sur la propriété `length` de la fonction ni sur l'objet [arguments](/fr/docs/Web/JavaScript/Reference/Fonctions/arguments). +Pour chacune des deux paires de définitions qui suivent, les deux définitions sont autorisées et équivalentes entre elles. Les virgules finales n'ont pas d'impact sur la propriété [`length`](/fr/docs/Web/JavaScript/Reference/Global_Objects/Function/length) de la fonction ni sur l'objet [arguments](/fr/docs/Web/JavaScript/Reference/Functions/arguments). -```js -function f(p) {} +```js-nolint function f(p) {} +function f(p,) {} (p) => {}; -(p) => {}; +(p,) => {}; ``` -Les virgules finales peuvent également être utilisées lors [des définitions de méthodes](/fr/docs/Web/JavaScript/Reference/Fonctions/Définition_de_méthode) dans les objets et les classes : +Les virgules finales peuvent également être utilisées lors [des définitions de méthodes](/fr/docs/Web/JavaScript/Reference/Functions/Method_definitions) dans les objets et les classes : -```js +```js-nolint class C { - un(a,) {}, - deux(a, b,) {}, + un(a,) {} + deux(a, b,) {} } -var obj = { +const obj = { un(a,) {}, deux(a, b,) {}, }; ``` -### Appels de fonctions +#### Appels de fonction -Pour chacune des deux paires d'appels qui suivent, les deux appels sont équivalents entre eux : +Pour chacune des deux paires d'appels qui suivent, les deux appels sont équivalents : -```js -f(p); +```js-nolint f(p); +f(p,); Math.max(10, 20); -Math.max(10, 20); +Math.max(10, 20,); ``` -### Virgules finales non-autorisées +#### Virgules finales interdites -Les définitions de paramètres ou les appels de fonctions qui ne contiennent qu'une seule virgule lèveront une exception {{Jsxref("SyntaxError")}}. Par ailleurs, on ne peut pas utiliser de virgule finale avec [les paramètres du reste](/fr/docs/Web/JavaScript/Reference/Fonctions/paramètres_du_reste) : +Les définitions de paramètres ou les appels de fonctions qui ne contiennent qu'une seule virgule lèveront une exception [`SyntaxError`](/fr/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError). Par ailleurs, on ne peut pas utiliser de virgule finale avec [les paramètres du reste](/fr/docs/Web/JavaScript/Reference/Functions/rest_parameters) : -```js example-bad +```js-nolint example-bad function f(,) {} // SyntaxError: missing formal parameter (,) => {}; // SyntaxError: expected expression, got ',' f(,) // SyntaxError: expected expression, got ',' @@ -98,49 +132,104 @@ function f(...p,) {} // SyntaxError: parameter after rest parameter (...p,) => {} // SyntaxError: expected closing parenthesis, got ',' ``` -## Les virgules finales et la décomposition +### Les virgules finales et la décomposition -On peut aussi utiliser une virgule finale dans l'opérande gauche lorsqu'on utilise [l'affectation par décomposition](/fr/docs/Web/JavaScript/Reference/Opérateurs/Affecter_par_décomposition) : +On peut aussi utiliser une virgule finale dans l'opérande gauche lorsqu'on utilise [l'affectation par décomposition](/fr/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) : -```js +```js-nolint // Décomposition d'un tableau avec // une virgule finale -[a, b] = [1, 2]; +[a, b,] = [1, 2]; // Décomposition d'un objet avec une // virgule finale -var o = { +const o = { p: 42, q: true, }; -var { p, q } = o; +const { p, q, } = o; ``` -Là encore, si on utilise un élément du reste, une exception {{jsxref("SyntaxError")}} sera levée : +Là encore, si on utilise un élément du reste, une exception [`SyntaxError`](/fr/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) sera levée : -```js example-bad -var [a, ...b] = [1, 2, 3]; +```js-nolint example-bad +const [a, ...b,] = [1, 2, 3]; // SyntaxError: rest element may not have a trailing comma ``` ## Les virgules finales en JSON -L'utilisation des virgules finales dans les objets a été introduite avec ECMAScript 5. Toutefois, le format JSON est basé sur la syntaxe JavaScript antérieure à ES5 **et les virgules finales sont donc interdites en JSON**. +Le format JSON est basé sur un sous-ensemble restreint de la syntaxe JavaScript, **les virgules finales sont interdites en JSON**. -Les deux lignes suivantes lèveront une exception {{jsxref("SyntaxError")}} : +Les deux lignes suivantes lèveront une exception [`SyntaxError`](/fr/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) : ```js example-bad JSON.parse("[1, 2, 3, 4, ]"); -JSON.parse('{"foo" : 1, }'); +JSON.parse('{"toto" : 1, }'); // SyntaxError JSON.parse: unexpected character // at line 1 column 14 of the JSON data ``` -Pour analyser le JSON correctement, on évitera les virgules finales : +Pour analyser le JSON correctement, on évitera les virgules finales : ```js example-good JSON.parse("[1, 2, 3, 4 ]"); -JSON.parse('{"foo" : 1 }'); +JSON.parse('{"toto" : 1 }'); +``` + +### Virgules finales pour les imports et exports nommés + +Les virgules finales sont valides dans [les imports nommés](/fr/docs/Web/JavaScript/Reference/Statements/import#import_nommé) et [les exports nommés](/fr/docs/Web/JavaScript/Reference/Statements/export). + +#### Imports nommés + +```js-nolint +import { + A, + B, + C, +} from "D"; + +import { X, Y, Z, } from "W"; + +import { A as B, C as D, E as F, } from "Z"; +``` + +#### Exports nommés + +```js-nolint +export { + A, + B, + C, +}; + +export { A, B, C, }; + +export { A as B, C as D, E as F, }; +``` + +### Virgules finales pour l'import dynamique + +Les virgules finales sont uniquement autorisées pour [les imports dynamiques](/fr/docs/Web/JavaScript/Reference/Operators/import) si le moteur d'exécution implémente le second paramètre `options`. + +```js-nolint +import("D",); +import( + "D", + { with: { type: "json" } }, +); +``` + +### Quantificateur pour les expressions rationnelles + +> [!NOTE] +> Dans [un quantificateur](/fr/docs/Web/JavaScript/Guide/Regular_expressions/Quantifiers), une virgule finale change la sémantique et passe de « exactement `n` » à « au moins `n` ». + +```js +/x{2}/; // Exactement 2 occurrences de "x" ; équivalent à /xx/ +/x{2,}/; // Au moins 2 occurrences de "x" ; équivalent à /xx+/ +/x{2,4}/; // 2 à 4 occurrences de "x" ; équivalent à /xxx?x?/ ``` ## Spécifications @@ -153,4 +242,4 @@ JSON.parse('{"foo" : 1 }'); ## Voir aussi -- La proposition initiale pour ECMAScript, déposée par Jeff Morrison, afin d'utiliser [les virgules finales dans les fonctions](https://github.com/tc39/proposal-trailing-function-commas). +- [Le guide sur la grammaire et les types JavaScript](/fr/docs/Web/JavaScript/Guide/Grammar_and_types) From 4f1fa4d33f971cb5f093714c32e76e89963ea74c Mon Sep 17 00:00:00 2001 From: Alexander Date: Mon, 14 Oct 2024 11:44:04 -0600 Subject: [PATCH 026/221] es: Create contructor Date() (#24065) Co-authored-by: GrayWolf --- .../global_objects/date/date/index.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 files/es/web/javascript/reference/global_objects/date/date/index.md diff --git a/files/es/web/javascript/reference/global_objects/date/date/index.md b/files/es/web/javascript/reference/global_objects/date/date/index.md new file mode 100644 index 00000000000000..0739de5baa512e --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/date/date/index.md @@ -0,0 +1,161 @@ +--- +title: Constructor Date() +slug: Web/JavaScript/Reference/Global_Objects/Date/Date +l10n: + sourceCommit: 3b5a1c0dfd59257c0a51052a9efa7b0108f8ecca +--- + +{{JSRef}} + +El constructor **`Date()`** crea objetos de tipo {{jsxref("Date")}}. Cuando se llama como una función, devuelve una cadena que representa la hora actual. + +{{EmbedInteractiveExample("pages/js/date-constructor.html")}} + +## Sintaxis + +```js-nolint +new Date() +new Date(value) +new Date(dateString) +new Date(dateObject) + +new Date(year, monthIndex) +new Date(year, monthIndex, day) +new Date(year, monthIndex, day, hours) +new Date(year, monthIndex, day, hours, minutes) +new Date(year, monthIndex, day, hours, minutes, seconds) +new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds) + +Date() +``` + +> [!NOTE] > `Date()` se puede llamar con o sin [`new`](/es/docs/Web/JavaScript/Reference/Operators/new), pero con efectos diferentes. Ver el [valor de retorno](#valor_de_retorno). + +### Parámetros + +Hay cinco formas básicas para el constructor `Date()`: + +#### Sin parámetros + +Cuando no se proporcionan parámetros, el objeto `Date` recién creado representa la fecha y hora actuales al momento de la instanciación. La marca de tiempo ([timestamp](/es/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date)) de la fecha devuelta es la misma que el número devuelto por {{jsxref("Date.now()")}}. + +#### Valor de tiempo o número de marca de tiempo + +- `value` + - : Un valor entero que representa la [marca de tiempo](/es/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date) (el número de milisegundos desde la medianoche al comienzo del 1 de enero de 1970, UTC — también conocido como el [epoch](/es/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date)). + +#### Cadena de fecha + +- `dateString` + - : Un valor de cadena que representa una fecha, analizado e interpretado usando el mismo algoritmo implementado por {{jsxref("Date.parse()")}}. Ver el [formato de cadena de fecha y hora](/es/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format) para advertencias sobre el uso de diferentes formatos. + +#### Objeto fecha + +- `dateObject` + - : Un objeto `Date` existente. Esto efectivamente hace una copia del objeto `Date` existente con la misma fecha y hora. Esto es equivalente a `new Date(dateObject.valueOf())`, excepto que no se llama al método `valueOf()`. + +Cuando se pasa un parámetro al constructor `Date()`, las instancias de `Date` se tratan de manera especial. Todos los demás valores se [convierten a datos primitivos](/es/docs/Web/JavaScript/Data_structures#primitive_coercion). Si el resultado es una cadena, se analizará como una cadena de fecha. De lo contrario, el valor primitivo resultante se convierte en un número y se trata como una marca de tiempo. + +#### Valores individuales de componentes de fecha y hora + +Dado al menos un año y un mes, esta forma de `Date()` devuelve un objeto `Date` cuyos valores de componentes (año, mes, día, hora, minuto, segundo y milisegundo) provienen de los siguientes parámetros. Cualquier campo faltante se le da el valor más bajo posible (`1` para el día y `0` para todos los demás componentes). Los valores de los parámetros se evalúan en la zona horaria local, en lugar de UTC. {{jsxref("Date.UTC()")}} acepta parámetros similares pero interpreta los componentes como UTC y devuelve una marca de tiempo. + +Si algún parámetro excede sus límites definidos, se "arrastra". Por ejemplo, si se pasa un `monthIndex` mayor que `11`, esos meses harán que el año incremente; si se pasa un `minutes` mayor que `59`, `hours` se incrementará en consecuencia, etc. Por lo tanto, `new Date(1990, 12, 1)` devolverá el 1 de enero de 1991; `new Date(2020, 5, 19, 25, 65)` devolverá las 2:05 AM del 20 de junio de 2020. + +De manera similar, si algún parámetro esta por debajo, "toma prestado" de las posiciones superiores. Por ejemplo, `new Date(2020, 5, 0)` devolverá el 31 de mayo de 2020. + +- `year` + - : Valor entero que representa el año. Los valores de `0` a `99` se mapean a los años `1900` a `1999`. Todos los demás valores son el año real. Ver el [ejemplo](/es/docs/Web/JavaScript/Reference/Global_Objects/Date#interpretation_of_two-digit_years). +- `monthIndex` + - : Valor entero que representa el mes, comenzando con `0` para enero hasta `11` para diciembre. +- `day` {{optional_inline}} + - : Valor entero que representa el día del mes. Por defecto es `1`. +- `hours` {{optional_inline}} + - : Valor entero entre `0` y `23` que representa la hora del día. Por defecto es `0`. +- `minutes` {{optional_inline}} + - : Valor entero que representa el segmento de minutos de una hora. Por defecto es `0`. +- `seconds` {{optional_inline}} + - : Valor entero que representa el segmento de segundos de una hora. Por defecto es `0`. +- `milliseconds` {{optional_inline}} + - : Valor entero que representa el segmento de milisegundos de una hora. Por defecto es `0`. + +### Valor de retorno + +Llamar a `new Date()` (el constructor `Date()`) devuelve un objeto [`Date`](/es/docs/Web/JavaScript/Reference/Global_Objects/Date). Si se llama con una cadena de fecha no válida, o si la fecha que se va a construir tendrá una marca de tiempo menor a `-8,640,000,000,000,000` o mayor a `8,640,000,000,000,000` milisegundos, devuelve una [fecha no válida](/es/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date) (un objeto `Date` cuyo método {{jsxref("Date/toString", "toString()")}} devuelve `"Invalid Date"` y cuyo método {{jsxref("Date/valueOf", "valueOf()")}} devuelve `NaN`). + +Llamar a la función `Date()` (sin la palabra clave `new`) devuelve una representación en cadena de la fecha y hora actuales, exactamente como `new Date().toString()`. Cualquier argumento dado en una llamada a la función `Date()` (sin la palabra clave `new`) se ignora; independientemente de si se llama con una cadena de fecha no válida, o incluso se llama con cualquier objeto arbitrario u otro dato primitivo como argumento, siempre devuelve una representación en cadena de la fecha y hora actuales. + +## Descripción + +### Precisión de tiempo reducida + +Para ofrecer protección contra ataques de sincronización y [huellas digitales](/es/docs/Glossary/Fingerprinting), la precisión de `new Date()` puede redondearse según la configuración del navegador. En Firefox, la preferencia `privacy.reduceTimerPrecision` está habilitada de forma predeterminada y el valor predeterminado es 2ms. También puedes habilitar `privacy.resistFingerprinting`, en cuyo caso la precisión será de 100ms o el valor de `privacy.resistFingerprinting.reduceTimerPrecision.microseconds`, el que sea mayor. + +Por ejemplo, con precisión de tiempo reducida, el resultado de `new Date().getTime()` siempre será un múltiplo de 2, o un múltiplo de 100 (o `privacy.resistFingerprinting.reduceTimerPrecision.microseconds`) con `privacy.resistFingerprinting` habilitado. + +```js +// Precisión de tiempo reducida (2 ms) en Firefox 60 +new Date().getTime(); +// Podría ser: +// 1519211809934 +// 1519211810362 +// 1519211811670 +// … + +// Precisión de tiempo reducida con `privacy.resistFingerprinting` habilitado +new Date().getTime(); +// Podría ser: +// 1519129853500 +// 1519129858900 +// 1519129864400 +// … +``` + +## Ejemplos + +### Varias maneras de crear un objeto Date + +Los siguientes ejemplos muestran varias maneras de crear fechas en JavaScript: + +```js +const today = new Date(); +const birthday = new Date("December 17, 1995 03:24:00"); // DESACONSEJADO: puede no funcionar en todos los entornos +const birthday = new Date("1995-12-17T03:24:00"); // Esto está estandarizado y funcionará de manera confiable +const birthday = new Date(1995, 11, 17); // el mes es indexado desde 0 +const birthday = new Date(1995, 11, 17, 3, 24, 0); +const birthday = new Date(628021800000); // pasando marca de tiempo epoch +``` + +### Pasando un valor que no es Date, ni cadena, ni número + +Si el constructor `Date()` se llama con un parámetro que no es una instancia de `Date`, se convertirá a un dato primitivo y luego se verificará si es una cadena. Por ejemplo, `new Date(undefined)` es diferente de `new Date()`: + +```js +console.log(new Date(undefined)); // Fecha no válida +``` + +Esto se debe a que `undefined` ya es un dato primitivo pero no una cadena, por lo que se convertirá a un número, que es [`NaN`](/es/docs/Web/JavaScript/Reference/Global_Objects/NaN) y, por lo tanto, no es una marca de tiempo válida. Por otro lado, `null` se convertirá a 0. + +```js +console.log(new Date(null)); // 1970-01-01T00:00:00.000Z +``` + +Los [Arrays](/es/docs/Web/JavaScript/Reference/Global_Objects/Array) se convertirán en una cadena a través de [`Array.prototype.toString()`](/es/docs/Web/JavaScript/Reference/Global_Objects/Array/toString), que une los elementos con comas. Sin embargo, la cadena resultante para cualquier arreglo con más de un elemento no es una cadena de fecha ISO 8601 válida, por lo que su comportamiento de análisis será definido por la implementación. **No pases arreglos al constructor `Date()`**. + +```js +console.log(new Date(["2020-06-19", "17:13"])); +// 2020-06-19T17:13:00.000Z en Chrome, ya que reconoce "2020-06-19,17:13" +// "Fecha no válida" en Firefox +``` + +## Especificaciones + +{{Specifications}} + +## Compatibilidad con navegadores + +{{Compat}} + +## Véase también + +- {{jsxref("Date")}} From cd80e7951c00f27de258ecada8f608288aa01480 Mon Sep 17 00:00:00 2001 From: teo <78679830+woosung1223@users.noreply.github.com> Date: Tue, 15 Oct 2024 19:00:07 +0900 Subject: [PATCH 027/221] =?UTF-8?q?[ko]=20HTTP=20=EB=A6=AC=EC=86=8C?= =?UTF-8?q?=EC=8A=A4=EC=99=80=20=EB=AA=85=EC=84=B8=20=ED=85=8C=EC=9D=B4?= =?UTF-8?q?=EB=B8=94=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8=20(#23500)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * synchronize table with en document * fix minor code style details Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * append source commit data --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../resources_and_specifications/index.md | 93 ++++++++++--------- 1 file changed, 47 insertions(+), 46 deletions(-) diff --git a/files/ko/web/http/resources_and_specifications/index.md b/files/ko/web/http/resources_and_specifications/index.md index 61b19a21e267a2..ec7ab9f094206d 100644 --- a/files/ko/web/http/resources_and_specifications/index.md +++ b/files/ko/web/http/resources_and_specifications/index.md @@ -1,55 +1,56 @@ --- title: HTTP 리소스와 명세 slug: Web/HTTP/Resources_and_specifications +l10n: + sourceCommit: cb132bc83b660e51be8959de5336c00b08030104 --- {{HTTPSidebar}} HTTP는 1990년 초에 처음으로 명세되었습니다. 확장성을 염두에 두고 설계하였고, 해를 거듭하면서 더 많은 추가 사항들이 세상에 나왔습니다; 이런 일로 많은 명세서를 통해 세상에 뿌려진 명세들이 나오게 되었습니다(실험되다가 폐기된 확장들 가운데에서도). 이 페이지에서는 HTTP와 관련해 의미가 있는 리소스들을 나열하고 있습니다. -| 명세 | 제목 | 상태 | -| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -| {{rfc(7230)}} | Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing | Proposed Standard | -| {{rfc(7231)}} | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content | Proposed Standard | -| {{rfc(7232)}} | Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests | Proposed Standard | -| {{rfc(7233)}} | Hypertext Transfer Protocol (HTTP/1.1): Range Requests | Proposed Standard | -| {{rfc(7234)}} | Hypertext Transfer Protocol (HTTP/1.1): Caching | Proposed Standard | -| {{rfc(5861)}} | HTTP Cache-Control Extensions for Stale Content | Informational | -| {{rfc(7235)}} | Hypertext Transfer Protocol (HTTP/1.1): Authentication | Proposed Standard | -| {{rfc(6265)}} | HTTP State Management Mechanism _Defines Cookies_ | Proposed Standard | -| [Draft spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-prefixes-00) | Cookie Prefixes | IETF Draft | -| [Draft spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00) | Same-Site Cookies | IETF Draft | -| {{rfc(2145)}} | Use and Interpretation of HTTP Version Numbers | Informational | -| {{rfc(6585)}} | Additional HTTP Status Codes | Proposed Standard | -| {{rfc(7538)}} | The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect) | Proposed Standard | -| {{rfc(7725)}} | An HTTP Status Code to Report Legal Obstacles | On the standard track | -| {{rfc(2397)}} | The "data" URL scheme | Proposed Standard | -| {{rfc(3986)}} | Uniform Resource Identifier (URI): Generic Syntax | Internet Standard | -| {{rfc(5988)}} | Web Linking _Defines the {{HTTPHeader("Link")}} header_ | Proposed Standard | -| [Experimental spec](https://tools.ietf.org/id/draft-thomson-hybi-http-timeout-01.html) | Hypertext Transfer Protocol (HTTP) Keep-Alive Header | Informational (Expired) | -| [Draft spec](https://httpwg.org/http-extensions/client-hints.html) | HTTP Client Hints | IETF Draft | -| {{rfc(7578)}} | Returning Values from Forms: multipart/form-data | Proposed Standard | -| {{rfc(6266)}} | Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) | Proposed Standard | -| {{rfc(2183)}} | Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field _Only a subset of syntax of the {{HTTPHeader("Content-Disposition")}} header can be used in the context of HTTP messages._ | Proposed Standard | -| {{rfc(7239)}} | Forwarded HTTP Extension | Proposed Standard | -| {{rfc(6455)}} | The WebSocket Protocol | Proposed Standard | -| {{rfc(5246)}} | The Transport Layer Security (TLS) Protocol Version 1.2 _This specification has been modified by subsequent RFCs, but these modifications have no effect on the HTTP protocol._ | Proposed Standard | -| [Draft spec]() | The Transport Layer Security (TLS) Protocol Version 1.3 _Once ready, this protocol will supersede TLS 1.2._ | IETF Draft | -| {{rfc(2817)}} | Upgrading to TLS Within HTTP/1.1 | Proposed Standard | -| {{rfc(7540)}} | Hypertext Transfer Protocol Version 2 (HTTP/2) | Proposed Standard | -| {{rfc(7541)}} | HPACK: Header Compression for HTTP/2 | On the standard track | -| {{rfc(7838)}} | HTTP Alternative Services | On the standard track | -| {{rfc(7301)}} | Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension _Used to negotiate HTTP/2 at the transport to save an extra request/response round trip._ | Proposed Standard | -| {{rfc(6454)}} | The Web Origin Concept | Proposed Standard | -| [Fetch](https://fetch.spec.whatwg.org/#cors-protocol) | Cross-Origin Resource Sharing | Living Standard | -| {{rfc(7034)}} | HTTP Header Field X-Frame-Options | Informational | -| {{rfc(6797)}} | HTTP Strict Transport Security (HSTS) | Proposed Standard | -| Upgrade Insecure Requests | Upgrade Insecure Requests | Candidate Recommendation | -| [Content Security Policy 1.0](https://www.w3.org/TR/CSP1/) | Content Security Policy 1.0 _CSP 1.1 and CSP 3.0 doesn't extend the HTTP standard_ | Obsolete | -| [Microsoft document]() | Specifying legacy document modes\* _Defines X-UA-Compatible_ | Note | -| {{rfc(5689)}} | HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) _These extensions of the Web, as well as CardDAV and CalDAV, are out-of-scope for HTTP on the Web. Modern APIs for application are defines using the RESTful pattern nowadays._ | Proposed Standard | -| {{rfc(2324)}} | Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) | April 1st joke spec | -| {{rfc(7168)}} | The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA) | April 1st joke spec | -| [HTML Living Standard](https://html.spec.whatwg.org/multipage/) | HTML _Defines extensions of HTTP for Server-Sent Events_ | Living Standard | -| [Reporting API](https://wicg.github.io/reporting/) | `Report-To` header | Draft | -| [Draft spec](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-expect-ct-01) | Expect-CT Extension for HTTP | IETF Draft | +| 명세 | 제목 | 상태 | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | +| {{rfc(9110)}} | HTTP Semantics | Internet Standard | +| {{rfc(9111)}} | HTTP Caching | Internet Standard | +| {{rfc(9112)}} | HTTP/1.1 | Internet Standard | +| {{rfc(9113)}} | HTTP/2 | Proposed Standard | +| {{rfc(9114)}} | HTTP/3 | Proposed Standard | +| {{rfc(5861)}} | HTTP Cache-Control Extensions for Stale Content | Informational | +| {{rfc(8246)}} | HTTP Immutable Responses | Proposed Standard | +| {{rfc(6265)}} | HTTP State Management Mechanism _Defines Cookies_ | Proposed Standard | +| [Draft spec](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-prefixes-00) | Cookie Prefixes | IETF Draft | +| [Draft spec](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-same-site-00) | Same-Site Cookies | IETF Draft | +| [Draft spec](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01) | Deprecate modification of 'secure' cookies from non-secure origins | IETF Draft | +| {{rfc(2145)}} | Use and Interpretation of HTTP Version Numbers | Informational | +| {{rfc(6585)}} | Additional HTTP Status Codes | Proposed Standard | +| {{rfc(7725)}} | An HTTP Status Code to Report Legal Obstacles | On the standard track | +| {{rfc(2397)}} | The "data" URL scheme | Proposed Standard | +| {{rfc(3986)}} | Uniform Resource Identifier (URI): Generic Syntax | Internet Standard | +| {{rfc(5988)}} | Web Linking _Defines the {{HTTPHeader("Link")}} header_ | Proposed Standard | +| [Draft spec](https://wicg.github.io/client-hints-infrastructure/) | HTTP Client Hints | IETF Draft | +| {{rfc(7578)}} | Returning Values from Forms: multipart/form-data | Proposed Standard | +| {{rfc(6266)}} | Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) | Proposed Standard | +| {{rfc(2183)}} | Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field _Only a subset of syntax of the {{HTTPHeader("Content-Disposition")}} header can be used in the context of HTTP messages._ | Proposed Standard | +| {{rfc(7239)}} | Forwarded HTTP Extension | Proposed Standard | +| {{rfc(6455)}} | The WebSocket Protocol | Proposed Standard | +| {{rfc(5246)}} | The Transport Layer Security (TLS) Protocol Version 1.2 _This specification has been modified by subsequent RFCs, but these modifications have no effect on the HTTP protocol._ | Proposed Standard | +| {{rfc(8446)}} | The Transport Layer Security (TLS) Protocol Version 1.3 _Supersedes TLS 1.2._ | Proposed Standard | +| {{rfc(2817)}} | Upgrading to TLS Within HTTP/1.1 | Proposed Standard | +| {{rfc(7541)}} | HPACK: Header Compression for HTTP/2 | On the standard track | +| {{rfc(7838)}} | HTTP Alternative Services | On the standard track | +| {{rfc(7301)}} | Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension _Used to negotiate HTTP/2 at the transport to save an extra request/response round trip._ | Proposed Standard | +| {{rfc(6454)}} | The Web Origin Concept | Proposed Standard | +| [Fetch](https://fetch.spec.whatwg.org/#cors-protocol) | Cross-Origin Resource Sharing | Living Standard | +| {{rfc(7034)}} | HTTP Header Field X-Frame-Options | Informational | +| {{rfc(6797)}} | HTTP Strict Transport Security (HSTS) | Proposed Standard | +| [Upgrade Insecure Requests](https://w3c.github.io/webappsec-upgrade-insecure-requests/) | Upgrade Insecure Requests | Candidate Recommendation | +| [Content Security Policy 1.0](https://www.w3.org/TR/CSP1/) | Content Security Policy 1.0 _CSP 1.1 and CSP 3.0 doesn't extend the HTTP standard_ | Obsolete | +| [Microsoft document]() | Specifying legacy document modes\* _Defines X-UA-Compatible_ | Note | +| {{rfc(5689)}} | HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) _These extensions of the Web, as well as CardDAV and CalDAV, are out-of-scope for HTTP on the Web. Modern APIs for application are defines using the RESTful pattern nowadays._ | Proposed Standard | +| {{rfc(2324)}} | Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) | April 1st joke spec | +| {{rfc(7168)}} | The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA) | April 1st joke spec | +| [HTML Living Standard](https://html.spec.whatwg.org/multipage/) | HTML _Defines extensions of HTTP for Server-Sent Events_ | Living Standard | +| [Reporting API](https://wicg.github.io/reporting/) | `Report-To` header | Draft | +| [Draft spec](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-expect-ct-01) | Expect-CT Extension for HTTP | IETF Draft | +| {{rfc(7486)}} | HTTP Origin-Bound Auth (HOBA) | Experimental | From 945874b59f27a39aa73dff82bf971dcdeefd823c Mon Sep 17 00:00:00 2001 From: SphinxKnight Date: Tue, 15 Oct 2024 12:43:49 +0200 Subject: [PATCH 028/221] Fix #21014 (#24060) * Initial work * fixes #21014 with an update from en-US * Rewording per @tristantheb review Co-authored-by: tristantheb --------- Co-authored-by: tristantheb --- files/fr/web/css/easing-function/index.md | 270 +++++++++++----------- 1 file changed, 138 insertions(+), 132 deletions(-) diff --git a/files/fr/web/css/easing-function/index.md b/files/fr/web/css/easing-function/index.md index 40529a505c5e8e..f5c4416f9ef82a 100644 --- a/files/fr/web/css/easing-function/index.md +++ b/files/fr/web/css/easing-function/index.md @@ -1,167 +1,167 @@ --- title: slug: Web/CSS/easing-function +l10n: + sourceCommit: 803a7a460338dab4900fd44cf7ab569e3bf5799a --- {{CSSRef}} -Le [type de données](/fr/docs/Web/CSS/CSS_Types) CSS **``** indique une fonction mathématique qui décrit la façon dont une valeur numérique évolue. +Le [type de données](/fr/docs/Web/CSS/CSS_Types) [CSS](/fr/docs/Web/CSS) **``** représente une fonction mathématique décrivant la vitesse à laquelle la valeur change. -Cette transition entre deux valeurs peut être appliquées dans différentes situations. Elle peut être utilisée pour décrire la rapidité selon laquelle les valeurs évoluent durant les animations. Elle permet ainsi de faire varier la vitesse de l'animation au fur et à mesure de sa progression. Elle peut aussi être utilisée pour interpoler deux couleurs au sein d'un dégradé. - -Les fonctions d'évolution qui appartiennent au sous ensemble des courbes de Bézier cubiques sont souvent appelées des fonctions « douces » car elles permettent d'avoir des évolutions légères en début et en fin d'interpolation. Les fonctions d'évolution relient un ratio d'entrée à un ratio de sortie, tous les deux exprimés comme des nombres ([``](/fr/docs/Web/CSS/number)). Pour ces valeurs, `0.0` représente l'état initial et `1.0` représente l'état final. - -Selon la fonction utilisée, la sortie calculée peut parfois être supérieure à `1.0` ou être inférieure à `0.0` pendant le cours de l'animation. Cela placera la valeur plus loin que son état final puis la fera revenir. Pour les animations de certaines propriétés (comme [`left`](/fr/docs/Web/CSS/left) ou [`right`](/fr/docs/Web/CSS/right)), cela crée un effet de rebond. - -![](tf_with_output_gt_than_1.png) - -Toutefois, certaines propriétés restreindront la valeur de sortie au sein d'un intervalle acceptable. Ainsi, pour une valeur représentant la composante d'une couleur, celle-ci sera écrétée pour rester dans l'intervalle autorisé 0-255. Certaines courbes `cubic-bezier()` illustrent cette propriété. - -![](tf_with_output_gt_than_1_clipped.png) +Cette transition entre deux valeurs peut être appliquée dans différentes situations. Elle peut être utilisée pour décrire la rapidité selon laquelle les valeurs évoluent durant les animations. Elle permet ainsi de faire varier la vitesse de l'animation au fur et à mesure de sa progression. On peut utiliser une fonction d'évolution pour les [transitions](/fr/docs/Web/CSS/transition-timing-function) et [animations](/fr/docs/Web/CSS/animation-timing-function) CSS. ## Syntaxe -Il existe trois types de [fonctions de transition](#easing_functions) : linéaires, [courbes de Bézier cubiques](https://en.wikipedia.org/wiki/Bézier_curve#Cubic_B.C3.A9zier_curves) et les fonctions en escalier. Une valeur du type `` décrit la fonction de transition en utilisant l'un de ces trois types. - -### Fonctions de transition - -CSS prend en charge trois sortes de fonction de transition : les fonctions linéaires, le sous ensemble des courbes cubiques de Bézier qui sont des fonctions et les fonctions en escalier. Les fonctions les plus utiles peuvent être facilement utilisées grâce à des mots-clés. - -#### Les fonctions de transition linéaires - -##### linear - -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Une ligne diagonale droite par de l'origine 0 0 jusqu'à arriver à la position 1 1.](cubic-bezier-linear.png) - -L'interpolation se fait à évolution constante, du début jusqu'à la fin. Ce mot-clé représente la fonction de transition décrite par `cubic-bezier(0.0, 0.0, 1.0, 1.0)`. - -#### La classe des fonctions de transition cubic-bezier() +```css +/* fonction et mot-clé pour une évolution linéaire */ +/* linear() */ +linear(1, -0.5, 0) +linear + +/* fonction et mots-clés pour les courbes de Bézier cubiques */ +/* cubic-bezier(, , , ) */ +cubic-bezier(0.25, 0.1, 0.25, 1) +ease +ease-in +ease-out +ease-in-out + +/* fonctions et mots-clés pour les évolutions en escalier */ +/* steps(, ) */ +steps(4, end) +steps(10, jump-both) +step-start +step-end +``` -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Une ligne courbe par de l'origine jusqu'à atteindre la position 1 1. Le point à l'origine est appelé 'P₀ = (0, 0)'. En partant de l'origine, on a une poignée de Bézier intitulée 'P₁ = (0.075, 0.75)'. Le point aux coordonnées 1 1 est intitulé 'P₃ = (1, 1)'. En partant du point 1 1, on a une poignée de Bézier intitulée 'P₂ = (0.0875, 0.36)'.](cubic-bezier-example.png) +### Valeurs -La notation fonctionnelle `cubic-bezier()` définit [une courbe de Bézier cubique](https://fr.wikipedia.org/wiki/Courbe_de_Bézier#Courbes_de_Bézier_cubiques). Ces courbes étant continues, elles sont souvent utilisées afin de démarrer et de finir progressivement une interpolation. Elles sont parfois appelées _fonctions de transition_. +- `linear` -Une courbe de Bézier cubique est définie par quatre points P0, P1, P2 et P3. P0 et P3 représentent les points de début et de fin de la courbe. Pour les fonctions de transition CSS, ces points sont fixes, car les coordonnées représentent des ratios (sur les abscisses, le ratio en temps et sur les ordonnées, le ratio en sortie). P0 est donc situé en `(0, 0)` et représente l'état initial. P3 est en `(1, 1)` et réprésente l'état final. + - : Indique que l'évolution a lieu à vitesse constante pendant toute la durée. Ce mot-clé est à la fois équivalent à [`cubic-bezier(0, 0, 1, 1)`](#fonctions_dévolution_en_courbe_de_bézier_cubique) et à [`linear(0, 1)`](#fonctions_dévolution_linéaire). -Toutes les courbes de Bézier cubiques ne sont pas des fonctions de transition, car toutes ne sont pas [des fonctions mathématiques]() (c'est-à-dire des courbes qui, pour une abscisse donnée, ont une seule ou zéro valeur). Avec les contraintes imposées sur P0 et P3 en CSS, une courbe de Bézier cubique sera une fonction mathématique et pourra être utilisée comme fonction de transition, si et seulement si les abscisses de P1 et P2 appartiennent, tous les deux, à l'intervalle `[0, 1]`. +![Un graphique avec en abscisses la progression de l'entrée et en ordonnées la progression de la sortie, on voit une ligne droite entre l'origine et le point (1, 1).](linear.svg) -Les courbes de Bézier cubiques pour lesquelles les ordonnées des points P1 ou P2 sont en dehors de l'intervalle `[0, 1]` pourront générer un effet de rebond. +- `` -Si on utilise une déclaration `cubic-bezier` avec une fonction invalide, CSS ignorera l'ensemble de la propriété. + - : Définit une fonction `linear()` avec un ou plusieurs _arrêts linéaires_, chacun pouvant contenir jusqu'à deux _longueurs d'arrêt_ optionnelles afin de contrôler la progression de l'animation ou de la transition. -##### Syntaxe + La fonction `linear()` prend comme argument une liste d'arrêts linéaires séparés par des virgules qui indiquent les points par lesquels progressent l'animation ou la transition. Chaque point de la liste est indiqué par [un nombre (une valeur de type ``)](/fr/docs/Web/CSS/number) comprise entre `0` et `1` (inclus). Par défaut, chaque arrêt est équidistant des autres, mais on peut aussi préciser un à deux [pourcentages](/fr/docs/Web/CSS/percentage) qui précisent la longueur. -```css -cubic-bezier(x1, y1, x2, y2) -``` + - `` : représente un point dans le temps sur la durée de l'animation ou de la transition. La valeur `0` représente le début de l'itération et `1` la fin. Il est possible d'utiliser des valeurs en dehors de l'intervalle [0,1]. -avec : + - `` : indique la position de l'arrêt linéaire dans la durée. On peut avoir deux coefficients en pourcentages. Si une seule valeur est fournie, elle indique le départ de l'arrêt linéaire correspondant. Si deux valeurs sont fournies, elles définissent la longueur de l'arrêt : la première indiquant le point de départ et le second le point d'arrivée pour ce segment. Si aucun pourcentage n'est fourni (le comportement par défaut), les arrêts sont répartis à équidistance sur la ligne chronologique. -- **_x1_, _y1_, _x2_, _y2_** +- `` - - : Des valeurs numériques ([``](/fr/docs/Web/CSS/number)) qui représentent les abscisses et ordonnées des points P + - : Définit [une courbe de Bézier](/fr/docs/Glossary/Bezier_curve) cubique donnant la progression de l'animation ou de la transition dans le temps. En CSS, les courbes de Bézier sont définies par 4 points de contrôle qui décrivent mathématiquement la courbe : un point de départ, un point final, et deux points de contrôles. On peut définir une telle fonction de deux façons : en créant une courbe paramétrée sur mesure avec ces quatre points grâce à la fonction `cubic-bezier()` ou en utilisant un des mots-clés prédéfinis qui correspondent aux paramètres usuels utilisés pour les courbes de Bézier. Les valeurs des mots-clés prédéfinis sont : - 1 + `ease` : Ce mot-clé correspond à `cubic-bezier(0.25, 0.1, 0.25, 1)`. Il indique que l'interpolation démarre doucement, accélère vivement, puis ralentit progressivement. Le comportement est semblable à celui obtenu avec le mot-clé `ease-in-out`, mais accélère plus fortement au début. - et P + `ease-in` : Ce mot-clé correspond à `cubic-bezier(0.42, 0, 1, 1)`. Il indique que l'interpolation démarre doucement, puis accélère progressivement jusqu'à la fin, avant de s'arrêter brutalement. - 2 + `ease-out` : Ce mot-clé correspond à `cubic-bezier(0, 0, 0.58, 1)`. Il indique que l'interpolation démarre brutalement, puis ralentit progressivement jusqu'à la fin. - qui définissent la courbe de Bézier cubique. x + `ease-in-out` : Ce mot-clé correspond à `cubic-bezier(0.42, 0, 0.58, 1)`. Il indique que l'interpolation démarre doucement, accélère, puis ralentit à nouveau vers la fin. Au début, le comportement est proche de celui de `ease-in`, et à la fin, semblable à celui de `ease-out`. - 1 + ![4 graphes avec le temps en abscisses (de 0 à 1) et la progression en ordonnées, qui illustrent les 4 courbes obtenues respectivement avec ease, ease-in, ease-out, ease-in-out.](ease.svg) - et x + `cubic-bezier()` : Cette fonction prend quatre coefficients numériques (type [``](/fr/docs/Web/CSS/number)) pour construire la courbe. - 2 + - [``](/fr/docs/Web/CSS/number) : Quatre valeurs définissent les coordonnées [des points P1 et P2](#fonction_dévolution_en_courbe_de_bézier_cubique) de la courbe. `` et `` sont les coordonnées du point P1, et `` et `` celles du point P2. `` et `` doivent être comprises entre `0` et `1`. - doivent appartenir à l'intervalle \[0, 1] afin que la valeur soit valide. +- `` -#### Mots-clés pour les fonctions de transition communes + - : Définit une fonction en escalier qui divise l'animation en plusieurs paliers de même longueur. L'animation passe d'un palier à l'autre plutôt que de transitionner progressivement. Cette valeur sera l'un des deux mots-clés prédéfinis suivants ou une fonction `steps()` paramétrée sur mesure : -##### ease + `step-start` : Ce mot-clé est équivalent à `steps(1, jump-start)` ou `steps(1, start)`. Il indique que l'interpolation passe immédiatement à l'état final et reste ainsi jusqu'à la fin. -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Une ligne courbe part de l'origine jusqu'au point 1 1 en démarrant rapidement et finissant par un arc plat.](cubic-bezier-ease.png) + `step-end` : Ce mot-clé est équivalent à `steps(1, jump-end)` ou `steps(1, end)`. Il indique que l'interpolation reste dans l'état initial jusqu'au dernier moment où elle passe directement à l'état final. -L'interpolation démarre doucement puis accélère vivement avant de ralentir vers la fin. Ce mot-clé représente la fonction de transition `cubic-bezier(0.25, 0.1, 0.25, 1.0)`. Cette valeur est semblable à [`ease-in-out`](#ease-in-out), bien qu'elle accélère plus rapidement au début. + ![Deux graphes, avec le temps en abscisses et la progression de l'animation en ordonnées, illustrant step-start et step-end.](step.svg) -##### ease-in + `steps()` : Cette fonction prend en paramètre un [entier](/fr/docs/Web/CSS/integer) et un autre paramètre optionnel qui indique la position du saut. -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Une courbe part l'origine jusqu'au point 1 1 avec une bonne partie de la courbe proche de l'origine et qui s'élève en quasi-ligne droite afin d'atteindre le point d'arrivée 1 1.](cubic-bezier-ease-in.png) + - `` : Ce coefficient indique le nombre d'intervalles (ou marches) équidistants. Ce doit être un entier positif, supérieur à `0`, sauf si le deuxième paramètre vaut `jump-none`, auquel cas, le coefficient doit être un entier supérieur à `1`. + - `` : Cet argument optionnel définit [le moment du saut](#fonctions_dévolution_en_escalier) et précise s'il a lieu au début, à la fin, au début et à la fin ou ni à l'un ou l'autre. Les mots-clés qui peuvent être utilisés pour ce paramètre sont : -L'interpolation démarre lentement puis s'accélère progressivement jusqu'à la fin où elle s'arrête de façon abrutpe. Ce mot-clé représente la fonction de transition `cubic-bezier(0.42, 0.0, 1.0, 1.0)`. + - `jump-start` : Indique que le premier saut se produit tout au début, au point `0`. Aucun moment de l'animation ne se passe au point `0%`. + - `jump-end` : Indique que le dernier saut se produit tout à la fin, au point `1`. Aucun moment de l'animation ne se passe au point `100%`. Il s'agit de la valeur par défaut quand aucune valeur `` n'est précisée. + - `jump-none` : Indique qu'aucun saut n'a lieu au début ou à la fin, retirant ainsi un palier sur toute l'évolution. Dans ce cas, la durée de chaque palier est déterminée en divisant la durée totale par le nombre de paliers (1/n). + - `jump-both` :Indique que le saut a lieu à la fois au début et à la fin. En pratique, cela ajoute un palier à chaque extrémité. Aucun moment n'est passé aux points de progression `0%` et `100%`. + - `start` : Équivalent à `jump-start`. + - `end` : Équivalent à `jump-end`. -##### `ease-in-out` +## Description -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Une ligne courbe qui part de l'origine jusqu'à atteindre le point 1 1. La courbe est symétrique et ressemble à un S étiré](cubic-bezier-ease-in-out.png) +Il existe trois types de fonction d'évolution : -L'interpolation démarre lentement puis accélère avant de ralentir vers la fin. Ce mot-clé représente la fonction de transition `cubic-bezier(0.42, 0.0, 0.58, 1.0)`. Au début, elle se comporte comme [`ease-in`](#ease-in) et à la fin, elle se comporte comme [`ease-out`](#ease-out). +- [Les fonctions linéaires](#fonctions_dévolution_linéaire) +- [Les courbes de Bézier cubiques](#fonctions_dévolution_en_courbe_de_bézier_cubique) +- [Les fonctions en escalier](#fonctions_dévolution_en_escalier) -##### ease-out +### Fonctions d'évolution linéaire -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Une ligne courbe part de l'origine jusqu'à atteindre le point 1 1. Cette courbe démarre comme une ligne droite en diagonale puis se courbe progressivement à l'approche de 1 1.](cubic-bezer-ease-out.png) +La fonction `linear()` permet d'obtenir une progression linéaire par segments. L'interpolation a lieu à vitesse constante du début jusqu'à la fin. Généralement, on utilise la fonction `linear()` en lui fournissant de nombreux points afin de construire l'approximation d'une courbe. -L'interpolation démarre abruptement puis ralentit progressivement vers la fin. Ce mot-clé correspond à la fonction de transition `cubic-bezier(0.0, 0.0, 0.58, 1.0)`. +Par exemple, avec la fonction `linear(0, 0.25, 1)`, l'animation ou la transition démarre au point 0 et progresse linéairement jusqu'au quart de l'animation, puis progresse linéairement jusqu'au point `1`. Aucun pourcentage `` n'étant indiqué, la même durée s'applique (50%) pour le passage de `0` à `0.25` et celui de `0.25` à `1`. -#### Les fonctions de transition en escalier +![Deux graphes avec le temps en abscisses et la progression en ordonnées. Le graphe à gauche illustre linear(0, 0.25, 1) sur lequel on voit une ligne cassée partir de l'origine jusqu'au point (0.5, 0.25), puis repartir jusqu'à (1, 1). Le graphe à droite illustre linear(0, 0.25 75%, 1) et on y voit une ligne cassée partant de l'origine jusqu'au point de coordonnées (0.75, 0.25), puis repartir jusqu'au point (1, 1).](linear_function.svg) -La notation fonctionnelle `steps()` définit une fonction en escalier qui divise le domaine des valeurs de sorties en marches équidistantes. +Par défaut, les arrêts sont équidistants. Ainsi, s'il y a 5 arrêts, ils se situeront respectivement à 0%, 25%, 50%, 75%, et 100% de la durée. On peut utiliser des pourcentages pour spécifier des valeurs `` afin de contrôler plus précisément le début et/ou la fin de chaque segment. -##### Syntaxe +Prenons une animation qui dure 100 secondes et progresse sur 100 pixels. Si on spécifie l'évolution de l'animation avec `linear(0, 0.25 75%, 1)`, elle progressera de 25 pixels pendant les 75 premières secondes (75% de la durée) et les 75 derniers pixels seront parcourus pendant les 25 secondes restantes. Si on avait utilisé `linear(0, 0.5 25% 75%, 1)`, l'animation aurait atteint 50 en 25 secondes, serait restée ainsi pendant 50 secondes (75%-25% de 100s) et les 50 derniers pixels auraient été parcourus pendant les 25 secondes restantes. `linear(0, 0.5 25% 75%, 1)` est équivalent à `linear(0, 0.5 25%, 0.5 75%, 1)`. -```css -steps(nombre_de_marches, direction) -``` +> [!NOTE] +> Le mot-clé [`linear`](#linear) est équivalent à `linear(0, 1)`. Bien que le mot-clé `linear` soit toujours interprété tel quel, la fonction `linear(0, 1)` est interprétée comme `linear(0 0%, 1 100%)`. -avec : +### Fonctions d'évolution en courbe de Bézier cubique -- _nombre_de_marches_ - - : Un entier ([``](/fr/docs/Web/CSS/integer)) strictement positif qui représente le nombre de segments équidistants qui composent la fonction en escalier. -- _direction_ +La notation fonctionnelle `cubic-bezier()` permet de définir [une courbe de Bézier](/fr/docs/Glossary/Bezier_curve) cubique. Ces fonctions permettent d'avoir des progressions initiales et finales plus douces. - - : Un mot-clé qui indique si la fonction est continue à gauche ou continue à droite : +![Un graphe avec le temps en abscisses et la progression en ordonnées, affichant une courbe en forme de S allant de l'origine jusqu'au point (1, 1) en utilisant les points de contrôle P1(0.1, 0.6) et P2(0.7, 0.2).](cubic-bezier.svg) - - `jump-start` indique une fonction continue à gauche : le premier saut a lieu au début de l'interpolation ; - - `jump-end` indique une fonction continue à droite : le dernier saut a lieu à la fin de l'interpolation ; - - `jump-both` indique une fonction continue à droite et à gauche avec des pauses au début et à la fin, ce qui se traduit par l'ajout d'une étape lors de l'itération de l'interpolation ; - - `jump-none` indique qu'il n'y a pas de saut au début ou à la fin mais une temporisation de 1/n de la durée totale à chaque extrêmité. - - `start` est équivalent à `jump-start` - - `end` est équivalent à `jump-end` +Une courbe de Bézier cubique est définie par quatre points : P0, P1, P2, et P3. Les points P0 et P3 représentent le début et la fin de la courbe. Ces derniers sont fixés ici en CSS : P0 est en `(0, 0)` et représente l'instant et la progression initiaux, tandis que P3 est situé en `(1, 1)` et correspond à l'état final. - `end` est la valeur par défaut. +Toutes les courbes de Bézier cubiques ne peuvent pas être utilisées comme fonctions d'évolution, car toutes ne sont pas [des fonctions mathématiques]() (c'est-à-dire des courbes pour lesquelles une abscisse donnée possède au plus une valeur en ordonnée). En CSS, P0 et P3 sont fixes et dans ces conditions, pour qu'une courbe de Bézier cubique soit une fonction, il faut (et il suffit) que les abscisses de P1 et P2 appartiennent à l'intervalle `[0, 1]`. -##### steps( n, \ ) +Dans le cas de courbes de Bézier cubiques où les ordonnées de P1 ou P2 sont en dehors de l'intervalle `[0, 1]`, la valeur pourra aller plus loin que l'état final puis revenir. Pour les animations CSS et certaines propriétés comme [`left`](/fr/docs/Web/CSS/left) ou [`right`](/fr/docs/Web/CSS/right), cela pourra créer un effet de rebond. -- `steps(2, jump-start)` - `steps(2, start)` +![Deux graphes pour la fonction d'évolution cubic-bezier(0.3, 0.2, 0.2, 1.4). Le graphe de gauche montre la progression allant plus haut que 1 à droite à partir d'une certaine progression. Celui de droite montre que la progression atteint 1 puis plafonne ainsi jusqu'à la fin.](cubic-bezier_out_of_range.svg) - ![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Trois points sont affichés : le premier aux coordonnées 0 0, le deuxième aux coordonnées 0,5 0,5 et le troisième aux coordonnées 1 1. Les deuxième et troisième points sont le début de lignes horizontales qui partent vers la gauche sur 0,5 unités.](steps-2-start.png) +Toutefois, certaines propriétés écrêteront la valeur produit si elle dépasse un intervalle autorisé. Ainsi, si la composante d'une couleur devient supérieure à 255 ou inférieure à 0 pour [`rgb()`](/fr/docs/Web/CSS/color_value/rgb), ce sera la valeur la plus proche et dans l'intervalle autorisé qui sera utilisée. Selon les coefficients passés à `cubic-bezier()`, on pourra observer ce comportement. -- `steps(4, jump-end) steps(4, end)` +Quand une courbe de Bézier invalide est fournie, le moteur CSS ignore la propriété dans son ensemble. - ![Quatre marches avec un saut de la quatrième à la valeur située à la fin.](steps-4-end.png) +Les mots-clés `ease`, `ease-in`, `ease-out`, et `ease-in-out` sont équivalents à des valeurs spécifiques de `cubic-bezier()` (voir plus haut). -- `steps(5, jump-none)` +### Fonctions d'évolution en escalier - ![Cinq marches, sans saut : 20% de temps s'écoule à l'étape initiale et 20% de temps s'écoule à l'étape finale.](step5none.png) +La notation fonctionnelle `steps()` définit une fonction en escalier qui divise le segment des valeurs produites en paliers de même longueur. -- `steps(3, jump-both)` +Voici quelques exemples d'illustration avec `steps()` : - ![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Cinq points sont affichés, respectivement aux coordonnées 0 0, 0 0,25, 0,5 0,5, 0,75 0,75, 1 1. Les deuxième, troisième et quatrième points ont des lignes qui partent vers la droite sur 0,25 unités.](step3both.png) +```css +steps(2, jump-start) /* équivalent à steps(2, start) */ +steps(4, jump-end) /* équivalent à steps(4, end) */ +steps(5, jump-none) +steps(3, jump-both) +``` -##### step-start +![4 graphiques illustrant l'évolution de la sortie (en ordonnées) par rapport à l'entrée (en abscisses). Le graphe en haut à gauche, steps(2, jump-start), montre une évolution sur deux marches, la première au niveau y=0.5 et commençant en x=0 jusqu'en x=0.5 et la deuxième au niveau y=1 jusqu'à x=1. Le graphe en haut à droite, steps(4, jump-end), montre une évolution sur 4 marches dont la première commence en (0,0) jusqu'à (0.25,0) et ainsi de suite jusqu'à la dernière marche (0.75,0.75) à (1,0.75). Le graphe en bas à gauche, steps(5, jump-none), montre une évolution sur 5 marches, la première d'ordonnée 0 de x=0 jusqu'à x=0.20, jusqu'à la cinquième marche de (0.80,1) à (1,1). Le graphe en bas à droite, steps(3, jump-both), montre 3 marche, la première démarrant à (0,0.25) et allant jusqu'à (0.33,0.25), la seconde de (0.33,0.5) à (0.66,0.5), puis la troisième de (0.66,0.75) à (1,0.75).](jump.svg) -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Deux points sont présents, le premier situé aux coordonnées 0 0 et le second aux coordonnées 1 1. Une ligne horizontale part du deuxième point vers l'axe Y.](steps-1-start.png) L'interpolation saute directement à l'état final et reste ainsi jusqu'à la fin. Ce mot-clé correspond à la fonction de transition `steps(1, jump-start)` ou `steps(1, start)`. +Les mots-clés `step-start` et `step-end` sont équivalents à une valeur spécifique de `steps()`. -##### step-end +## Syntaxe formelle -![Un graphe où les axes X et Y vont de 0 à 1 et où l'axe X est intitulé « Time ratio » et où l'axe Y est intitulé « Output ratio ». Deux points sont présents, le premier situé aux coordonnées 0 0 et le second aux coordonnées 1 1. Une ligne horizontale part du premier point et reste sur l'axe des abscisses.](steps-1-end.png) L'interpolation reste dans son état initial jusqu'à la fin où elle saute directement à l'état final. Ce mot-clé représente la fonction de transition `steps(1, jump-end)` ou `steps(1, end)`. +{{csssyntax}} ## Exemples -### Comparaison des fonctions de transition +### Comparer les fonctions d'évolution -Dans cet exemple, on crée une animation qui peut être démarrée ou stoppée à l'aide du bouton fourni et un menu est affiché pour choisir la fonction de transition à utiliser : différents mots-clés sont disponibles ainsi que des exemples utilisant `cubic-bezier()` et `steps()`. L'idée est de fournir un outil de comparaison simple entre ces fonctions. +Cet exemple fournit un outil de comparaison entre les différentes fonctions d'évolution avec une animation. Vous pouvez sélectionner une des fonctions d'évolution depuis le menu déroulant parmi quelques mots-clés, certains exemples `cubic-bezier()` ou `steps()`. Après avoir sélectionné une option, vous pouvez lancer ou interrompre l'animation grâce au bouton correspondant. #### HTML @@ -174,9 +174,10 @@ Dans cet exemple, on crée une animation qui peut être démarrée ou stoppée
  • - +
    • La requête a un corpsNonLa requête possède un corpsElle peut
    Une réponse de succès a un corpsNonEn cas de réussite, la réponse contient un corpsElle peut
    {{Glossary("Sûre")}}La méthode est sûre Non
    {{Glossary("Idempotente")}}La méthode est idempotente Oui
    {{Glossary("Peut être mise en cache")}}La requête peut être mise en cache Non
    - Autorisée dans les - formulaires HTML + La méthode est autorisée pour les formulaires HTML Non