forked from withastro/docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
i18n(zh-tw): update
astro-pages.mdx translation (withastro#6980)
* i18n(zh-tw): update `astro-pages.mdx` translation * Fix Markdown formatting --------- Co-authored-by: Yan Thomas <[email protected]>
- Loading branch information
1 parent
60682ac
commit efc8847
Showing
1 changed file
with
108 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,35 +1,47 @@ | ||
| --- | ||
| title: 頁面 | ||
| description: Astro 頁面的介紹 | ||
| description: Astro 頁面簡介 | ||
| i18nReady: true | ||
| --- | ||
|
|
||
| **頁面** 是在你 Astro 專案的 `src/pages/` 子目錄下的檔案。他們用來處理路由、資料載入以及所有你網站內的頁面版面。 | ||
| import ReadMore from '~/components/ReadMore.astro'; | ||
| import Since from '~/components/Since.astro' | ||
|
|
||
| **頁面** 是 Astro 專案 `src/pages/` 子目錄下的檔案，用來處理路由、資料載入以及網站內所有頁面的版面。 | ||
|
|
||
| ## 支援的頁面檔案類型 | ||
|
|
||
| Astro 支援下列在 `src/pages/` 目錄裡的檔案類型： | ||
| - [`.astro`](#astro-頁面) | ||
| - [`.md`](#markdownmdx-頁面) | ||
| - `.mdx` （在安裝 [MDX 整合](/zh-tw/guides/integrations-guide/mdx/#installation)的情況下） | ||
| - `.mdx`（在安裝 [MDX 整合](/zh-tw/guides/integrations-guide/mdx/#installation)的情況下） | ||
| - [`.html`](#html-頁面) | ||
| - `.js`/`.ts` （作為 [endpoints](/zh-tw/guides/endpoints/)） | ||
| - `.js`/`.ts`（作為[端點](/zh-tw/guides/endpoints/)） | ||
|
|
||
| ## 基於檔案的路由 | ||
|
|
||
| Astro 使用了一個路由策略叫 **基於檔案的路由（file-based routing）** 。每個在你 `src/pages/` 目錄下的檔案都會變成你網站的 endpoint，而其會根據檔案自己的路徑而定。 | ||
| Astro 使用**基於檔案的路由**策略（file-based routing）。每個 `src/pages/` 目錄下的檔案，都會根據檔案的路徑，變成網站的端點。 | ||
|
|
||
| 如果你的內容位於[內容合集](/zh-tw/guides/content-collections/)或 [CMS](/zh-tw/guides/cms/)，也能透過[動態路由](/zh-tw/guides/routing/#dynamic-routes)功能，讓單一路由檔案產生多個頁面。 | ||
|
|
||
| <ReadMore>進一步了解 [Astro 的路由](/zh-tw/guides/routing/)。</ReadMore> | ||
|
|
||
| ### 連結至頁面 | ||
|
|
||
| 你可以用一般的 HTML [`<a>` 元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)連結到你網站的其他頁面。記得使用**相對於根網域的網址**，而非檔案相對路徑。 | ||
|
|
||
| 你可以寫一個標準 HTML [`<a>` 元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)到你的 component 範本來連結頁面彼此。 | ||
| 舉例來說，如果要從 `example.com` 的其他頁面連到 `https://example.com/authors/sonali/`： | ||
|
|
||
| 📚 閱讀更多關於 [Astro 的路由](/zh-tw/guides/routing/)。 | ||
| ```astro title="src/pages/index.astro" | ||
| Read more <a href="/authors/sonali/">about Sonali</a>. | ||
| ``` | ||
|
|
||
| ## Astro 頁面 | ||
|
|
||
| Astro 頁面使用了 `.astro` 的副檔名，且其和 [Astro components](/zh-tw/basics/astro-components/) 支援相同的功能。 | ||
| Astro 頁面使用 `.astro` 副檔名，支援的功能同 [Astro 元件](/zh-tw/basics/astro-components/)。 | ||
|
|
||
| ```astro | ||
| ```astro title="src/pages/index.astro" | ||
| --- | ||
| // Example: src/pages/index.astro | ||
| --- | ||
| <html lang="en"> | ||
| <head> | ||
|
|
@@ -41,25 +53,29 @@ Astro 頁面使用了 `.astro` 的副檔名，且其和 [Astro components](/zh-t | |
| </html> | ||
| ``` | ||
|
|
||
| 為了在每個頁面避免重複使用到相同的 HTML 元素，你可以將一般的 `<head>` 和 `<body>` 移到你自己的[版面 components](/zh-tw/basics/layouts/)。你可以隨自己喜歡或多或少使用這些版面 components。 | ||
| Astro 頁面必須產生完整的 HTML 文件，因此 Astro 預設會替 `src/pages/` 的 Astro 元件加上必要的 `<!DOCTYPE html>` 和 `<head>` 標籤（除非檔案已包含這些標籤）。如果不想要這個行為，可以將 Astro 元件標記為[局部](#局部頁面)頁面。 | ||
|
|
||
| 為了避免在每個頁面避免寫相同的 HTML 元素，你可以將常用到的 `<head>` 和 `<body>` 移到你自己的[版面元件](/zh-tw/basics/layouts/)，數量不限。 | ||
|
|
||
| ```astro {3} /</?MySiteLayout>/ | ||
| --- | ||
| // Example: src/pages/index.astro | ||
| // src/pages/index.astro | ||
| import MySiteLayout from '../layouts/MySiteLayout.astro'; | ||
| --- | ||
| <MySiteLayout> | ||
| <p>我的頁面內容包在一層版面裡！</p> | ||
| </MySiteLayout> | ||
| ``` | ||
|
|
||
| 📚 閱讀更多關於 Astro 內的 [版面 components](/zh-tw/basics/layouts/)。 | ||
| <ReadMore>進一步了解[版面元件](/zh-tw/basics/layouts/)。</ReadMore> | ||
|
|
||
| ## Markdown/MDX 頁面 | ||
|
|
||
| Astro 也會將任何 `src/pages/` 內的 Markdown（`.md`）檔作為你最後網站的頁面。如果你有[安裝 MDX 整合](/zh-tw/guides/integrations-guide/mdx/#installation)的話，它也會將 MDX（`.mdx`）檔做同樣的事。這普遍用來做成大量文字的頁面，像是部落格文章和文件。 | ||
| Astro 也會將任何 `src/pages/` 內的 Markdown（`.md`）檔作為你最後網站的頁面。如果你有[安裝 MDX 整合](/zh-tw/guides/integrations-guide/mdx/#installation)的話，它也會對 MDX（`.mdx`）檔做同樣的事。這普遍用於以文字為主的頁面，像是部落格文章和文件。 | ||
|
|
||
| 此外，`src/content/` 的 [Markdown 或 MDX 頁面內容合集](/zh-tw/guides/content-collections/)可以[動態產生頁面](/zh-tw/guides/routing/#dynamic-routes)。 | ||
|
|
||
| 頁面版面在 [Markdown 檔](#markdownmdx-頁面)特別地有用。Markdown 檔可以使用特殊的 `layout` frontmatter 屬性去指定一個 [版面 component](/zh-tw/basics/layouts/)，其會將他們的 Markdown 內容包進一個完整的 `<html>...</html>` 的頁面檔案裡。 | ||
| 頁面版面在 [Markdown 檔](#markdownmdx-頁面)特別地有用。Markdown 檔可以使用特殊的 `layout` frontmatter 屬性指定 [版面元件](/zh-tw/basics/layouts/)，進而將 Markdown 內容包進完整的 `<html>...</html>` 頁面檔案裡。 | ||
|
|
||
| ```md {3} | ||
| --- | ||
|
|
@@ -72,15 +88,88 @@ title: '我的 Markdown 頁面' | |
| 這是我的網頁，用 **Markdown** 寫的喔！ | ||
| ``` | ||
|
|
||
| 📚 閱讀更多關於 Astro 內的 [Markdown](/zh-tw/guides/markdown-content/)。 | ||
| <ReadMore>進一步了解如何在 Astro 使用 [Markdown](/zh-tw/guides/markdown-content/)。</ReadMore> | ||
|
|
||
| ## HTML 頁面 | ||
|
|
||
| 擁有 `.html` 副檔名的檔案可以放置在 `src/pages/` 內，並直接作為你網站的頁面。但要注意的是，有些關鍵的 Astro 功能在 [HTML Components](/zh-tw/basics/astro-components/#html-components) 中是不被支援的。 | ||
| 擁有 `.html` 副檔名的檔案可以放置在 `src/pages/` 內，直接作為網站的頁面，但要注意 [HTML 元件](/zh-tw/basics/astro-components/#html-components) 不支援部分 Astro 功能。 | ||
|
|
||
| ## 自訂 404 錯誤頁面 | ||
|
|
||
| 你可以新增一個 `404.astro` 或 `404.md` 檔案到 `/src/pages` 裡來自定義一個 404 錯誤網站。 | ||
| 如要自訂 404 錯誤頁面，可以在 `/src/pages` 新增 `404.astro` 或 `404.md`。 | ||
|
|
||
| 構建時會產生 `404.html` 頁面，大多數的[部署服務](/zh-tw/guides/deploy/)會找到並使用該檔案。 | ||
|
|
||
| ## 局部頁面 | ||
|
|
||
| <p><Since v="3.4.0" /></p> | ||
|
|
||
| :::caution | ||
| 局部頁面應該搭配 [htmx](https://htmx.org/) 或 [Unpoly](https://unpoly.com/) 這種前端套件一起使用。如果不介意寫低階前端 JavaScript 的話，你也可以使用它。考量到這點，它算是進階功能。 | ||
|
|
||
| 除此之外，如果元件包含 scoped styles 或 scripts，則不應使用局部頁面，因為那些元素不會包含在最終輸出的 HTML。如果需要 scoped styles，最好使用一般非局部的頁面，再搭配知道如何把內容合併到 head 的前端套件。 | ||
| ::: | ||
|
|
||
| 局部頁面是位於 `src/pages/` 的頁面元件，但不是用來渲染完整的頁面。 | ||
|
|
||
| 和位於該目錄之外的其他元件一樣，這些檔案不會自動包含 `<!DOCTYPE html>`、`<head>`、scoped styles 和 scripts。 | ||
|
|
||
| 由於它們位於 `src/pages/` 目錄，產生的 HTML 仍然可透過對應到檔案路徑的網址存取。因此渲染套件（例：htmx、Stimulus、jQuery）能夠在不重新整理或前往新頁面的前提下，於客戶端存取並動態載入 HTML 片段。 | ||
|
|
||
| 局部頁面搭配渲染套件同樣能夠開發動態內容，是不使用 [Astro 群島](/zh-tw/concepts/islands/) 和 [`<script>` 標籤](/zh-tw/guides/client-side-scripts/) 時的替代方案。 | ||
|
|
||
| 能夠匯出值（例：`.astro`、`.mdx`）的頁面檔案即可標記為局部頁面。 | ||
|
|
||
| 在 `src/pages/` 目錄下的檔案內匯出以下指定值，便可將檔案設定為局部頁面： | ||
|
|
||
| 這將會建立出一個 `404.html` 頁面。大多數的[部署服務](/zh-tw/guides/deploy/)會找到並使用它。 | ||
| ```astro title="src/pages/partial.astro" ins={2} | ||
| --- | ||
| export const partial = true; | ||
| --- | ||
| <li>I'm a partial!</li> | ||
| ``` | ||
|
|
||
| `export const partial` 要能夠靜態識別。合法的值為： | ||
|
|
||
| - 布林值 __`true`__。 | ||
| - 透過 import.meta.env 存取的環境變數，例如 `import.meta.env.USE_PARTIALS`。 | ||
|
|
||
| ### 與套件搭配使用 | ||
|
|
||
| 搭配 [htmx](https://htmx.org/) 這種套件，局部頁面可用來動態更新頁面部分區域。 | ||
|
|
||
| 以下範例中，`hx-post` 屬性對應到局部頁面的網址，該頁面的內容將會用來更新這個頁面特定的 HTML 元素。 | ||
|
|
||
| ```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"' | ||
| <html> | ||
| <head> | ||
| <title>My page</title> | ||
| <script src="https://unpkg.com/[email protected]" | ||
| integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" | ||
| crossorigin="anonymous"></script> | ||
| </head> | ||
| </html> | ||
| <section> | ||
| <div id="parent-div">Target here</div> | ||
| <button hx-post="/partials/clicked/" | ||
| hx-trigger="click" | ||
| hx-target="#parent-div" | ||
| hx-swap="innerHTML" | ||
| > | ||
| Click Me! | ||
| </button> | ||
| </section> | ||
| ``` | ||
|
|
||
| 對應到檔案路徑的 `.astro` 局部頁面必須存在，且要明確匯出值，將頁面標記為局部頁面。 | ||
|
|
||
| ```astro title="src/pages/partials/clicked.astro" {2} | ||
| --- | ||
| export const partial = true; | ||
| --- | ||
| <div>I was clicked!</div> | ||
| ``` | ||
|
|
||
| 細節請見 [htmx 文件](https://htmx.org/docs/)。 | ||