頁面

透過在 src/routes 目錄中新增一個新的 index.tsx 檔案來建立頁面。頁面會匯出一個預設的 Qwik 元件，該元件將會被渲染為頁面的內容。

src/routes/some/path/index.tsx

import { component$ } from '@builder.io/qwik';
 
// Notice the default export
export default component$(() => {
  return <h1>Hello World!</h1>;
});

頁面和端點的唯一區別在於，端點只會匯出 onRequest、onGet、onPost、onPut、onDelete、onPatch 或 onHead 函式，這些函式將用於處理傳入的請求。

`head` 匯出

每個頁面都可以匯出一個 head 屬性（或函式），該屬性會返回一個 DocumentHead 物件。 DocumentHead 物件用於解析頁面的標題，以及中繼資料、連結和樣式。

這個 API 允許您設定頁面的標題，以及中繼資料、開放圖形、Twitter 標籤和連結。這對於 SEO 和社群分享非常有用。

src/routes/about/index.tsx

import { component$ } from '@builder.io/qwik';
import type { DocumentHead } from '@builder.io/qwik-city';
 
export default component$(() => {
  return <h1>About page</h1>;
});
 
export const head: DocumentHead = {
  // This will be used to resolve the <title> of the page
  title: 'About page',
  meta: [
    {
      name: 'description',
      content: 'This is the about page',
    },
    // Open graph
    {
      property: 'og:title',
      content: 'About page',
    },
    {
      property: 'og:description',
      content: 'This is the about page',
    },
  ],
  links: [
    {
      rel: 'canonical',
      href: 'https://example.com/about',
    },
  ],
};

上面的範例設定了標題，以及一些開放圖形中繼資料和規範連結。

HTML 將 <head> 標籤放置在 <html> 內部的第一個元素（HTML 內容的最頂部）。 <head> 部分不是您的路由元件直接渲染的內容，因為它會破壞 HTML 串流。

請查看 useDocumentHead() 以從您的元件內部讀取和使用 DocumentHead 物件。

動態 Head

您也可以匯出一個返回 DocumentHead 物件的函式，讓您可以以程式設計的方式設定 <title>、<meta> 或 <link> 標籤。

這允許您使用來自 routeLoader$() 或 routeAction$() 的數據來配置 <head>，包括標題、中繼資料或連結。

我們可以使用 resolveValue 方法來取得 head 函式內部 routeLoader$() 或 routeAction$() 的值。

src/routes/jokes/[jokeId]/index.tsx

import { component$ } from '@builder.io/qwik';
import { routeLoader$ } from '@builder.io/qwik-city';
import type { DocumentHead } from '@builder.io/qwik-city';
 
export const useJoke = routeLoader$(async (requestEvent) => {
  // Fetch a joke from a public API
  const jokeId = requestEvent.params.jokeId;
  const response = await fetch(`https://api.chucknorris.io/jokes/${jokeId}`);
  const joke = await response.json();
  return joke;
});
 
// Now we can export a function that returns a DocumentHead object
export const head: DocumentHead = ({resolveValue, params}) => {
  const joke = resolveValue(useJoke);
  return {
    title: `Joke "${joke.title}"`,
    meta: [
      {
        name: 'description',
        content: joke.text,
      },
      {
        name: 'id',
        content: params.jokeId,
      },
    ],
  };
};

巢狀佈局和 Head

在進階情況下，佈局可能想要修改已解析的文件標題。在下面的範例中，頁面元件返回標題 Foo。包含的佈局元件可以讀取頁面的文件標題的值並修改它。在此範例中，佈局元件將 MyCompany - 添加到標題中，以便在渲染時，標題將為 MyCompany - Foo。堆疊中的每個佈局都有機會返回一個新值。

──src/
  └─routes/
    ├─index.tsx
    └─layout.tsx

src/routes/index.tsx

export const head: DocumentHead = {
  title: `Foo`,
};

src/routes/layout.tsx

export const head: DocumentHead = ({ head }) => {
  return {
    title: `MyCompany - ${head.title}`,
  };
};

Google 結構化資料

此範例整合了 Google 結構化資料，這有助於向 Google 提供有關頁面含義的明確線索。如果您想嵌入自訂 JavaScript 程式碼，理想情況下是使用 Partytown 延遲載入。但是，有時您必須立即載入它們。以下範例說明了這一點。

src/routes/about/index.tsx

import { component$ } from '@builder.io/qwik';
import type { DocumentHead } from '@builder.io/qwik-city';
 
export default component$(() => {
  return <h1>About page</h1>;
});
 
export const head: DocumentHead = {
  scripts: [
    {
      props: {
        type: "application/ld+json",
      },
      script: JSON.stringify({
        "@context": "https://schema.org",
        "@type": "ItemList",
      }),
    },
  ],
};

上面的範例設定了一些結構化資料標記。

注意：您需要更改 router-head 元件以渲染 head.scripts。

src\components\router-head\router-head.tsx

import { component$ } from "@builder.io/qwik";
import { useDocumentHead, useLocation } from "@builder.io/qwik-city";
 
export const RouterHead = component$(() => {
  const head = useDocumentHead();
  const loc = useLocation();
 
  return (
    <>
      <title>{head.title}</title>
 
      {/* add this  */}
      {head.scripts.map((s) => (
        <script key={s.key} {...s.props} dangerouslySetInnerHTML={s.script} />
      ))}
    </>
  );
});

貢獻者

感謝所有幫助改進此文件的貢獻者！

頁面

head 匯出

動態 Head

巢狀佈局和 Head

Google 結構化資料

貢獻者

`head` 匯出