設定字典:首頁

$ 發布 2026-11-13 | | 更新 2026-11-14
上下文: 首頁設定欄位的型別、主題預設值、生效範圍、限制和可合併範例,並說明共享設定和目前沒有提供的開關。

查詢首頁標題、介紹、最新文章、提示文字、寬屏終端機和點選穿越的實際設定。


輸出
字數 2.8k 詞元 3.6k

返回設定字典總入口。本篇說明實際首頁使用的欄位,不改變主題程式碼,也不把展示站個人設定當成預設值。

下面 <locale> 換成專案實際啟用的語言代碼。範例使用 zh-hant;它只修改繁體中文設定,不會自動改變英文或啟用一種語言。所有片段都合併到 src/site.config.ts 現有的 defineThemeConfig 物件中,已有 theme、i18n 或 site 時保留其中其他欄位。

1. 首頁大標題、介紹和中繼描述

i18n.locales.<locale>.site.homeTitle

  • 型別:選用 string。
  • 主題預設值:未設定。各內建語言預設沒有單獨的 homeTitle,最終使用全站名稱(預設 My Blog)。
  • 作用:首頁可見大標題。
  • 狀態與限制:條件生效;依次尋找目前語言及其回退語言去除首尾空白後的非空標題,全部沒有才使用全站名稱。'' 或空白不能用來隱藏大標題。它不改變瀏覽器標題、導覽、頁尾、RSS 或 SEO 的全站名稱。

i18n.locales.<locale>.site.hero

  • 型別:選用 string。
  • 主題預設值:內建語言各有介紹;簡體中文為“在这里写一段站点简介,并告诉读者你将发布什么类型的内容。”,英文為“Write a short introduction for your site and what readers can expect from your posts.”。其他語言使用各自內建值。
  • 作用:首頁大標題下的可見介紹。
  • 狀態與限制:條件生效;查找目前語言及回退語言的已定義值。'' 是主動清空,不再繼續回退。這裡是文字,不解析 Markdown 或 HTML,也不改變頁面中繼描述。

i18n.locales.<locale>.messages.siteDescription

  • 型別:選用覆寫,值為 string。
  • 主題預設值:內建目前語言文字;簡體中文為“电影感网页界面与 AI 时代工程实践文章。”,英文為“Cinematic web interfaces and AI-era engineering essays.”。
  • 作用:首頁傳給頁面頭部的描述,不是可見介紹。
  • 狀態與限制:條件生效;先解析介面文字及回退,再使用該值,只有解析結果為空字串才回退到全站 description。空字串不是關閉全部頁面描述的開關;空白字串也不會自動 trim 為無描述。

三個欄位可以一起設定,彼此職責獨立:

i18n: {
  locales: {
    'zh-hant': {
      site: {
        homeTitle: '我的數字花園',
        hero: '記錄開發、閱讀和生活。',
      },
      messages: { siteDescription: '個人專案與學習筆記。' },
    },
  },
},

關聯通用欄位:site.title、site.description

本節只說明首頁關系:site.title 是沒有有效 homeTitle 時的最終標題回退,site.description 是首頁語言中繼描述為空時的備用值。兩者都不是首頁獨占欄位。型別、主題預設值、環境覆寫與完整範例統一見網站身分字典。

2. 最新文章數量

theme.homeLatestCount

  • 型別:number。
  • 主題預設值:3。
  • 作用:從目前語言按 pubDate 降序排列的文章中,取前 N 篇顯示在首頁。內容少于 N 時只顯示已有文章,旁邊計數顯示實際條數/該語言總條數。
  • 狀態與限制:生效;目前直接使用陣列 slice,沒有專門的正整數驗證。建議合理正整數,不要使用負數、小數、NaN 或 Infinity。0 會得到空列表,並顯示“没有文章”的提示,即使該語言已有文章;它不是隱藏整個最新文章區的開關。
  • 獨立範圍:不改變 Blog List 每頁數量,也不改變首頁碎片最多三條的預覽數量。
theme: { homeLatestCount: 5 },

文章標題、日期和摘要來自文章內容,不是這個欄位的子設定。首頁沒有「自動補上已翻譯文章以外的其他語言內容」的自動補齊邏輯。

3. 啟動提示和底部狀態

下列三個欄位型別均為 boolean,主題預設值均為 true,狀態均為生效。設為 false 只隱藏對應部分,省略則保留預設。

完整路徑 作用 限制
theme.home.showInitialize Initialize/done 啟動文欄位 只控制該段顯示,不控制首頁內文或背景載入
theme.home.showFollow Wake Up/Follow The White Rabbit 提示段 與上一段獨立,不是開啟頁面導覽的條件
theme.home.showTrace 首頁底部 PIRATE SIGNAL/TRACE PROGRAM 狀態區 不控制寬屏終端機;文字用於氛圍,不表示真實追蹤或網路狀態
theme: {
  home: {
    showInitialize: false,
    showFollow: true,
    showTrace: false,
  },
},

同時關閉前兩項會移除對應啟動文字組件。目前沒有 site.config 欄位修改這些固定啟動句、底部固定狀態文字或它們的時間參數;不要猜測 startupText、traceText 等設定名。

4. 首頁介面文字

以下均位於 i18n.locales.<locale>.messages.home,是選用的 string 覆寫,一般欄位按介面文字回退規則解析。這裡列簡體中文與英文內建預設值,其他內建語言有自己的文字。

完整路徑末段 簡體中文預設 / 英文預設 作用與限制
latest 最新 / Latest 最新文章區標題;只改文字,不改變排序或條數
viewAll 全部 / All 首頁文章歸檔入口文字,也用於碎片歸檔連結的無障礙說明;不會改變連結目的地
noPosts 该语言暂时没有文章。 / No posts available in this language yet. latestPosts 為空時的提示;不是草稿或發佈控制
openDoor 开门 / Open door 寬屏終端機鑰匙孔按鈕的無障礙名稱及預覽標籤;通常不是一直可見的內文標題

這些欄位是條件生效:對應區域存在時才有可見或無障礙效果。空字串可以清空文字,但不會刪除容器或關閉功能,也可能使按鈕失去有意義的名稱;需要控制顯示時使用相應功能開關。

i18n: {
  locales: {
    'zh-hant': {
      messages: {
        home: {
          latest: '最近更新',
          viewAll: '全部文章',
          noPosts: '這里還沒有文章。',
          openDoor: '打開走廊預覽',
        },
      },
    },
  },
},

i18n.locales.<locale>.messages.home.transmission

  • 型別:選用的 string 覆寫。
  • 主題預設值:'Knock, knock.',包括中文在內,沒有個人覆寫時共用這一句。
  • 作用:寬屏終端機中選用擇、滾動的文字。
  • 狀態與限制:條件生效;終端機在可視區域寬度至少 1440px 時顯示。取值順序單獨固定為目前語言個人設定 → 英文個人設定 → 預設句,不使用其他一般文字的完整回退鏈。'' 會清空文字,不隱藏終端機或關閉走廊。

例如設定所有沒有單獨覆寫的語言共用的文字:

i18n: {
  locales: {
    en: { messages: { home: { transmission: 'Leave a small trace here.' } } },
  },
},

在 zh-hant 的相同位置填寫則只覆寫繁體中文。修改文字不會查詢真實網路信號,也不改變鑰匙孔開啟走廊的行為。

i18n.locales.<locale>.messages.home.hero

  • 型別:選用的 string 覆寫。
  • 主題預設值:內建目前語言介紹,簡體中文和英文分別與上面的 site.hero 預設句相同。
  • 作用:只有 getSiteHero 沒有從目前語言和回退語言取得已定義值時,才作為首頁介紹的備用文字。
  • 狀態與限制:條件生效,不是廢棄欄位。但所有內建語言預設已有 site.hero,所以通常只改這個欄位看不到變化;把 site.hero 改成 '' 也不會觸發它。一般應直接修改 site.hero。
i18n: {
  locales: {
    'zh-hant': { messages: { home: { hero: '僅在沒有可用 site.hero 時使用的介紹。' } } },
  },
},

這個例子說明路徑與型別,不會繞過更高優先級的 site.hero。無需為了改首頁介紹刪除預設設定或修改相依原始碼。

5. 點選文章時的 Matrix 穿越

theme.effects.enableHomePassage

  • 型別:boolean。
  • 主題預設值:false。
  • 作用:在首頁,一般點選最新文章標題以及導覽中帶該效果的部落格入口時,先播放 Matrix 穿越,再導覽。正常時間軸約 8 秒,有完成/異常回退導覽處理。
  • 狀態與限制:條件生效;需要 JavaScript。減少動態效果、修飾鍵點選、非左鍵、下載連結、外站連結或新視窗目標等情況保留原生行為。它不延遲首頁內文出現,也不控制 About Oracle 或寬屏終端機預覽。
theme: { effects: { enableHomePassage: true } },

關閉時這些連結直接導覽。這個布林開關沒有提供時長、場景顏色或目標網址的設定;不要添加 homePassageDuration 等未公開欄位。

6. 首頁也會用到的共享設定

這些欄位不屬於首頁獨占功能;這裡保留首頁使用關系,完整定義在主字典中查閱。

完整路徑 首頁使用關系 主說明
theme.fragments.enabled 目前語言有碎片時顯示頭像入口,同時影響完整碎片列表;預覽固定最多三條 Fragments 開關
i18n.locales.<locale>.messages.blog.allPosts 最新文章數量的提示和歸檔入口的無障礙名稱 列表共享文字
i18n.locales.<locale>.messages.fragments.title 頭像入口的無障礙名稱,不是在頭像旁顯示標題 碎片文字
i18n.locales.<locale>.messages.fragments.close 首頁預覽關閉按鈕的無障礙名稱,不改變按鈕圖形 碎片文字

開啟後沒有頭像,先檢查目前語言是否確有碎片,不要為了顯示頭像複製已有碎片 ID。圖片、程式碼和限高規則見Fragments 字典,發佈步驟見發佈一條碎片。

7. 目前沒有提供的首頁設定

messages.siteTitle 目前不改變標準首頁或公共網站名稱;不要用它替代 homeTitle 或頂層 site.title。欄位的型別、預設值和範例統一見目前未使用的網站標題欄位。

程式碼雨密度和顏色、首頁鏡面按鈕、頭像素材、碎片預覽條數、固定啟動句,以及穿越時長目前沒有相應 site.config 欄位。它們屬於現有布局、樣式或腳本實作;不能因為 TypeScript 範例中隨意增加一個名字就讓它生效。Reduced Motion 會影響效果呈現,但不是本篇新增的設定開關。

首頁 / 與語言首頁的關系由 i18n.defaultLocale 和 i18n.routing.defaultLocalePrefix 控制,不在本篇重複完整定義,見語言與地址字典。公共導覽、頁尾、音樂和統計同樣不是首頁獨立設定。

修改後怎麼確認?

先在 dev 打開目標語言首頁,檢查修改的是標題、介紹、中繼描述還是無障礙說明。終端機文字要在至少 1440px 的可視區域驗證;中繼描述檢視頁面 head,按鈕名稱通過無障礙名稱或 title 確認,不能只看頁面有沒有大字。

環境覆寫值改動後重啟 dev;正式網站需要重新建置和部署。發佈前可停止 dev 後執行 npm run doctor,再執行 npm run preview;doctor 已含建置,不需要立即重複執行 check 和 build。操作步驟見安裝教學與部署教學。