diff options
Diffstat (limited to 'devdocs/html/element%2Fbdi.html')
| -rw-r--r-- | devdocs/html/element%2Fbdi.html | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/devdocs/html/element%2Fbdi.html b/devdocs/html/element%2Fbdi.html new file mode 100644 index 00000000..f18fe0c5 --- /dev/null +++ b/devdocs/html/element%2Fbdi.html @@ -0,0 +1,113 @@ +<header><h1><bdi>: The Bidirectional Isolate element</h1></header><div class="section-content"><p>The <code><bdi></code> <a href="../index">HTML</a> element tells the browser's bidirectional algorithm to treat the text it contains in isolation from its surrounding text. It's particularly useful when a website dynamically inserts some text and doesn't know the directionality of the text being inserted.</p></div> +<h2 id="try_it">Try it</h2> +<div class="section-content"> +<iframe class="interactive is-tabbed-standard-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/bdi.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe> <p>Bidirectional text is text that may contain both sequences of characters that are arranged left-to-right (LTR) and sequences of characters that are arranged right-to-left (RTL), such as an Arabic quotation embedded in an English string. Browsers implement the <a href="https://www.w3.org/International/articles/inline-bidi-markup/uba-basics" target="_blank">Unicode Bidirectional Algorithm</a> to handle this. In this algorithm, characters are given an implicit directionality: for example, Latin characters are treated as LTR while Arabic characters are treated as RTL. Some other characters (such as spaces and some punctuation) are treated as neutral and are assigned directionality based on that of their surrounding characters.</p> <p>Usually, the bidirectional algorithm will do the right thing without the author having to provide any special markup but, occasionally, the algorithm needs help. That's where <code><bdi></code> comes in.</p> <p>The <code><bdi></code> element is used to wrap a span of text and instructs the bidirectional algorithm to treat this text in isolation from its surroundings. This works in two ways:</p> <ul> <li>The directionality of text embedded in <code><bdi></code> <em>does not influence</em> the directionality of the surrounding text.</li> <li>The directionality of text embedded in <code><bdi></code> <em>is not influenced by</em> the directionality of the surrounding text.</li> </ul> <p>For example, consider some text like:</p> <pre data-language="plain">EMBEDDED-TEXT - 1st place +</pre> <p>If <code>EMBEDDED-TEXT</code> is LTR, this works fine. But if <code>EMBEDDED-TEXT</code> is RTL, then <code>- 1</code> will be treated as RTL text (because it consists of neutral and weak characters). The result will be garbled:</p> <pre data-language="plain">1 - EMBEDDED-TEXTst place +</pre> <p>If you know the directionality of <code>EMBEDDED-TEXT</code> in advance, you can fix this problem by wrapping <code>EMBEDDED-TEXT</code> in a <a href="span"><code><span></code></a> with the <a href="../global_attributes#dir"><code>dir</code></a> attribute set to the known directionality. But if you don't know the directionality - for example, because <code>EMBEDDED-TEXT</code> is being read from a database or entered by the user - you should use <code><bdi></code> to prevent the directionality of <code>EMBEDDED-TEXT</code> from affecting its surroundings.</p> <p>Though the same visual effect can be achieved using the CSS rule <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/unicode-bidi"><code>unicode-bidi</code></a><code>: isolate</code> on a <a href="span"><code><span></code></a> or another text-formatting element, HTML authors should not use this approach because it is not semantic and browsers are allowed to ignore CSS styling.</p> <p>Embedding the characters in <code><span dir="auto"></code> has the same effect as using <code><bdi></code>, but its semantics are less clear.</p> +</div> +<h2 id="attributes">Attributes</h2> +<div class="section-content"><p>Like all other HTML elements, this element supports the <a href="../global_attributes">global attributes</a>, except that the <a href="../global_attributes#dir"><code>dir</code></a> attribute behaves differently than normal: it defaults to <code>auto</code>, meaning its value is never inherited from the parent element. This means that unless you specify a value of either <code>rtl</code> or <code>ltr</code> for <code>dir</code>, the <a href="https://developer.mozilla.org/en-US/docs/Glossary/User_agent">user agent</a> will determine the correct directionality to use based on the contents of the <code><bdi></code>.</p></div> +<h2 id="examples">Examples</h2> + +<h3 id="no_bdi_with_only_ltr">No bdi with only LTR</h3> +<div class="section-content"> +<p>This example lists the winners of a competition using <a href="span"><code><span></code></a> elements only. When the names only contain LTR text the results look fine:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="73iNkMK9qFXp3QRjhWvpi4PWkSUN/c2RugYr7PwJyA0=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>ul</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>name<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Henrietta Boffin<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>span</span><span class="token punctuation">></span></span> - 1st place<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>name<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Jerry Cruncher<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>span</span><span class="token punctuation">></span></span> - 2nd place<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>ul</span><span class="token punctuation">></span></span> +</pre> +</div> +<div class="code-example" id="sect1"> + +<iframe class="bdi-example" title="No bdi with only LTR sample" id="frame_no_bdi_with_only_ltr" height="120" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/bdi/runner.html?id=no_bdi_with_only_ltr" loading="lazy"></iframe> +</div> +</div> +<h3 id="no_bdi_with_rtl_text">No bdi with RTL text</h3> +<div class="section-content"> +<p>This example lists the winners of a competition using <a href="span"><code><span></code></a> elements only, and one of the winners has a name consisting of RTL text. In this case the "<code>- 1</code>", which consists of characters with neutral or weak directionality, will adopt the directionality of the RTL text, and the result will be garbled:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="tvs5apW5E+dZ2zNiqG18Ie0kgyB71TdJq9HY6i3pBMk=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>ul</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>name<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>اَلأَعْشَى<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>span</span><span class="token punctuation">></span></span> - 1st place<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>name<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Jerry Cruncher<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>span</span><span class="token punctuation">></span></span> - 2nd place<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>ul</span><span class="token punctuation">></span></span> +</pre> +</div> +<div class="code-example" id="sect2"> + +<iframe class="bdi-example" title="No bdi with RTL text sample" id="frame_no_bdi_with_rtl_text" height="120" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/bdi/runner.html?id=no_bdi_with_rtl_text" loading="lazy"></iframe> +</div> +</div> +<h3 id="using_bdi_with_ltr_and_rtl_text">Using bdi with LTR and RTL text</h3> +<div class="section-content"> +<p>This example lists the winners of a competition using <code><bdi></code> elements. These elements instruct the browser to treat the name in isolation from its embedding context, so the example output is properly ordered:</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="trr15C0NOFwImByQQucSa4FUCesc++rCthXkEKU6rt0=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>ul</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>bdi</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>name<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>اَلأَعْشَى<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>bdi</span><span class="token punctuation">></span></span> - 1st place<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>li</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>bdi</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>name<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Jerry Cruncher<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>bdi</span><span class="token punctuation">></span></span> - 2nd place<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>li</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>ul</span><span class="token punctuation">></span></span> +</pre> +</div> +<div class="code-example" id="sect3"> + +<iframe class="bdi-example" title="Using bdi with LTR and RTL text sample" id="frame_using_bdi_with_ltr_and_rtl_text" height="120" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/bdi/runner.html?id=using_bdi_with_ltr_and_rtl_text" loading="lazy"></iframe> +</div> +</div> +<h2 id="technical_summary">Technical summary</h2> +<div class="section-content"><figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <th scope="row"><a href="../content_categories">Content categories</a></th> <td> <a href="../content_categories#flow_content">Flow content</a>, <a href="../content_categories#phrasing_content">phrasing content</a>, palpable content. </td> </tr> <tr> <th scope="row">Permitted content</th> <td> +<a href="../content_categories#phrasing_content">Phrasing content</a>.</td> </tr> <tr> <th scope="row">Tag omission</th> <td>None, both the starting and ending tag are mandatory.</td> </tr> <tr> <th scope="row">Permitted parents</th> <td> Any element that accepts <a href="../content_categories#phrasing_content">phrasing content</a>. </td> </tr> <tr> <th scope="row">Implicit ARIA role</th> <td><code><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role">generic</a></code></td> </tr> <tr> <th scope="row">Permitted ARIA roles</th> <td>Any</td> </tr> <tr> <th scope="row">DOM interface</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement"><code>HTMLElement</code></a></td> </tr> </tbody> </table></div></figure></div> +<h2 id="specifications">Specifications</h2> +<div class="_table"><table class="standard-table"> +<thead><tr><th scope="col">Specification</th></tr></thead> +<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-bdi-element">HTML Standard <br><small># the-bdi-element</small></a></td></tr></tbody> +</table></div> +<h2 id="browser_compatibility">Browser compatibility</h2> +<div class="_table"><table> +<thead> +<tr id="bct-browser-type"> +<th></th> +<th colspan="6">Desktop</th> +<th colspan="6">Mobile</th> +</tr> +<tr id="bct-browsers"> +<th></th> +<th>Chrome</th> +<th>Edge</th> +<th>Firefox</th> +<th>Internet Explorer</th> +<th>Opera</th> +<th>Safari</th> +<th>WebView Android</th> +<th>Chrome Android</th> +<th>Firefox for Android</th> +<th>Opera Android</th> +<th>Safari on IOS</th> +<th>Samsung Internet</th> +</tr> +</thead> +<tbody><tr> +<th><code>bdi</code></th> +<td class="bc-supports-yes">16</td> +<td class="bc-supports-yes">79</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">15</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">≤37</td> +<td class="bc-supports-yes">18</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">1.0</td> +</tr></tbody> +</table></div> +<h2 id="see_also">See also</h2> +<div class="section-content"><ul> <li><a href="https://www.w3.org/International/articles/inline-bidi-markup/" target="_blank">Inline markup and bidirectional text in HTML</a></li> <li><a href="https://www.w3.org/International/articles/inline-bidi-markup/uba-basics" target="_blank">Unicode Bidirectional Algorithm basics</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Glossary/Localization">Localization</a></li> <li>Related HTML element: <a href="bdo"><code><bdo></code></a> +</li> <li>Related CSS properties: <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/direction"><code>direction</code></a>, <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/unicode-bidi"><code>unicode-bidi</code></a> +</li> </ul></div><div class="_attribution"> + <p class="_attribution-p"> + © 2005–2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br> + <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdi" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdi</a> + </p> +</div> |