型ホバー#
TypeScript のサンプルは、すでに codeBlockTypecheck
でビルド時に型検査できます。ただし、ここでオプトインしない限り、描画された
フェンス上で読者がその型を見ることはできません。
typedHover の既定はオフです。有効にすると、**twoslash が付いた
TypeScript / TSX フェンスだけ** がホバー用ペイロードを受け取ります。型は
Markdown 変換中に計算します。ページが送るのは JSON と小さなオーバーレイ
スクリプトだけです。TypeScript コンパイラはブラウザでは動きません。
| オプション | 型 | 既定 |
|---|---|---|
typedHover |
boolean / TypedHoverOptions |
false |
import { oxContent } from "@ox-content/vite-plugin";
export default {
plugins: [
oxContent({
typedHover: true,
}),
],
};
true と {} は同じデフォルトで有効になります。省略または false では
どのフェンスも変わりません。オブジェクト形式では機能を有効にしたうえで
languages（既定 ["ts", "tsx"]）だけ上書きできます。
このサイトでは typedHover を有効にしているので、次のブロックは実際の
オーバーレイです。value にホバーするか Tab でフォーカスしてください。
const value = 1;
フェンスのメタ#
著者はフェンスごとに twoslash メタでオプトインします。サイトオプションが
オンでも、そのトークンが無いフェンスはスキップされます。
```ts twoslash
const value = 1;
```
```ts
const skipped = 1;
```
| フェンス | オーバーレイ |
|---|---|
```ts twoslash |
あり |
```tsx twoslash |
あり |
```ts（メタなし） |
なし |
```js twoslash |
なし |
インライン `const value = 1` |
なし |
twoslash は codeBlockTypecheck がすでに認識する
メタと同じです。2 つ目のマーカーを付けなくても、同じフェンスを型検査しつつ
ホバーを付けられます。検査したくない未完成スニペットは typecheck を省略し、
オーバーレイだけ欲しい場合は twoslash を使えます。
ビルド時であり、ブラウザではない#
ペイロードはページ変換中に作る { start, end, type } の範囲です。プラグインは
既存の TypeScript フェンス経路を再利用します。extractCodeBlocks がスニペットを
書き出し、識別子オフセットの型を tsgo（@typescript/native-preview）に尋ねます。
ブラウザは typescript も tsgo も Language Service もダウンロードしません。
codeBlockTypecheck と同じコンパイラを入れてください。
vp install -D @typescript/native-previewpnpm add -D @typescript/native-previewbun add -D @typescript/native-previewnpm install -D @typescript/native-previewyarn add -D @typescript/native-previewオプトインした各フェンスには class="ox-typed-hover" が付きます。ペイロードは
隣の <script type="application/json"> に入り、< / > は \u003c /
\u003e にエスケープされるので、型文字列がスクリプトを破ったりマークアップを
注入したりできません。
キーボードとポインタ#
型がある識別子は次の要素になります。
<span class="ox-typed-hover-token" tabindex="0">
- ポインタ: トークンにホバーすると小さなオーバーレイが開きます。
- キーボード: トークンへ Tab 移動します。フォーカスで同じオーバーレイが
開き、
Escapeで閉じます。 - オーバーレイは
role="tooltip"で、中身はinnerHTMLではなくtextContentで入れます。
トークンには点線の下線が付くので、マウスが無くても見つけられます。
リテラルのまま残るもの#
次は書き換えません。
twoslashが無いフェンス- JavaScript、JSON、その他
ts/tsx以外のフェンス - インラインコード
- インデントコード
- 閉じられていないフェンス（ファイルの残りをホバー対象として飲み込みません）
<img onerror> や </script> のような敵対的な型文字列は、JSON ペイロード内で
エスケープされ、オーバーレイではテキストとして描画されます。