CSS text-shadow 宣告是一行包含四個值的語法 — 水平偏移、垂直偏移、模糊半徑和顏色 — 而最簡單的撰寫方式就是使用一個產生器,它能預覽與複製到剪貼簿的完全相同字串。文字陰影產生器 API 替代方案回答了許多開發者私下會問的問題:我真的需要一個 HTTP 端點、一個 SDK 金鑰和一個版本管理政策,才能產生一行 CSS 嗎?對於一次性的設計調整、行銷頁面和小型元件編輯,答案是不需要。一個在目前分頁中執行的純瀏覽器本地工具,能驗證自己的輸入,並輸出一個與預覽相同的值,會更快、更容易稽核,而且不可能因為使用過時的用戶端程式庫而被誤用。這就是文字陰影產生器 API 替代方案的實際樣貌:有限的輸入、完全相同的預覽、可複製的輸出,以及無需上傳。
API 驅動的產生器仍然有用武之地,當陰影是在伺服器端渲染、預設值必須跨裝置同步、或需要在迴圈中產生大量變化時。它們是錯誤的工具,當目標是在真實字體、真實背景、真實元件中測試單一陰影時。本地方式也消除了一整類整合 bug,這些 bug 會在視覺樣本與匯出的 CSS 偏離時出現 — 這是舊式產生器中常見的缺陷,它們從一個程式路徑組合預覽,卻從另一個程式路徑組合剪貼簿字串。
為什麼 API 來回呼叫對單一陰影而言是錯誤的形式
text-shadow 屬性是一個基本元素。根據 W3C CSS Text Decoration 規範 與 MDN text-shadow 參考文件,其語法是一個以逗號分隔的陰影圖層清單,其中每個圖層包含兩個表示偏移的長度、一個可選的第三個表示模糊的長度,以及一個顏色。這就是整個問題領域。將它包裝在 API 中,意味著要付出網路延遲、驗證握手和 SDK 版本漂移的代價,才能收到瀏覽器已經知道如何產生的相同字串。
還有一些值得點出的資安與隱私角度。API 呼叫會洩露正在進行 UI 設計的事實、在傳輸過程中暴露範例文字,並將設計迭代與服務正常運行時間綁在一起。本地產生器反轉了這種關係:相同的值在目前分頁中處理、永不上傳,即使關閉網路也能產生輸出。對於設計權杖、無障礙稽核和 CI 快照而言,一個總是顯示將複製內容的產生器,其可稽核性是比請求與回應來回呼叫更強的保證。
從請求到宣告:本地產生器的運作方式
實作方法刻意保持精簡。該工具會驗證預覽文字、有界的有限帶正負號偏移、非負的模糊值,以及三組六位數十六進制顏色。從這些經過驗證的輸入中,它會序列化出恰好一個 text-shadow 圖層,並將該精確值套用於螢幕上的預覽。共享的計算避免了舊式產生器中常見的缺陷,也就是視覺樣本與剪貼簿輸出因為透過不同的程式路徑運算而偏離。
這個單一共享的值是核心保證。如果陰影在預覽中可見,那麼複製到剪貼簿的 CSS 字串會產生相同的像素。產生字串的相同輸入契約也會渲染預覽,因此不存在第二個翻譯步驟,讓數字被四捨五入、單位被加入,或顏色被改寫。
精簡的範圍也讓輸出易於審查。單一陰影行小到足以進行比對、貼到設計權杖的 pull request 中,以及在程式碼審查中朗讀出來。多圖層堆疊雖然感覺很強大,但經常會產生模糊不清的字型、動畫繪製成本,以及在小文字上無法通過無障礙檢查的偏移。對於一個清晰可讀的陰影,單一層是正確的答案。
用四個步驟建立一個清晰可讀的文字陰影
- 輸入簡短的預覽文字。輸入一個簡短字串,類似於最終的標題或標籤 — 例如你打算實際發布的一個或兩個單字。該工具會限制預覽長度以保持範圍有限且反應靈敏,因此過長的字串會被截斷,而不是允許破壞版面配置。
- 調整水平與垂直偏移以及模糊半徑。先使用滑桿或輸入框設定水平偏移,然後是垂直偏移,再來是模糊。水平正值將陰影向右移動,負值將其向左移動;垂直正值將陰影向下移動,負值將其向上移動。根據 CSS 語法,模糊不能為負,因此零是下限,較大的數值會擴散出更柔和的輪廓。
- 選擇陰影顏色、文字顏色和背景顏色。為三者都挑選完整的六位數十六進制值。陰影顏色是會被偏移和模糊的圖層;文字顏色和背景顏色則設定圍繞它的可讀性框架。請在所選背景下觀察預覽 — 同一個陰影在平坦的表面上可能看起來銳利,在飽和的表面上卻可能難以辨識。
- 複製宣告並在實際元件中驗證。將 CSS Text Shadow Generator 所產生的單一行複製到實際的樣式表中,然後針對真實的字體、粗細、大小以及文字在正式環境中會跨越的表面進行測試。請在網頁字型載入後重新檢查,因為後備字型指標和最終字型形狀會改變任何陰影的視覺邊緣、間距和粗細感受。
該工具接受與不接受的精確輸入
下方的契約就是完整的範圍。任何超出它的內容都會被拒絕,而不是被默默強制轉換,這正是讓預覽保持誠實的原因。
| 輸入 | 接受的範圍或格式 | 無效輸入時的行為 |
|---|---|---|
| 預覽文字 | 類似最終標籤的簡短字串;長度有上限 | 空白輸入會被拒絕 |
| 水平偏移 | −100 到 100 px,整數或有限小數 | 空白或非有限值會被拒絕,而不是歸零 |
| 垂直偏移 | −100 到 100 px,整數或有限小數 | 空白或非有限值會被拒絕,而不是歸零 |
| 模糊半徑 | 0 到 100 px,非負 | 負值、空白或非有限值會被拒絕 |
| 陰影顏色 | 六位數十六進制(例如 #1a1a1a) | 不接受簡寫、命名或 rgba 輸入 |
| 文字顏色 | 六位數十六進制 | 與陰影顏色相同的規則 |
| 背景顏色 | 六位數十六進制 | 與陰影顏色相同的規則 |
請注意,模糊半徑是唯一嚴格非負的欄位。偏移可以是負值,因為 CSS 語法允許,並且該工具反映了這個限制,而非自創規則。六位數十六進制格式也是經過深思熟慮的 — 它繞過了跨瀏覽器在簡寫展開、Alpha 通道位置和命名顏色對應上的歧義。
對於跨 CSS 系列比較陰影效果的讀者,box-shadow 屬性中的參數與 text-shadow 重疊,但適用於矩形邊框框而非字型邊緣。Box Shadow Generator 速查表 針對方塊介紹了相同的偏移、模糊和擴散語言,當兩種效果存在於同一個設計系統中時,是個實用的交叉參考。
同一個陰影,可讀性大不相同
單一宣告可能在一個表面上通過無障礙稽核,卻在另一個表面上失敗。陰影、文字和背景顏色之所以是必要輸入,正因為相同的偏移和模糊在淺色、深色、飽和或有圖案的表面上的閱讀效果不同。請將下表視為方向性指引,而非測量的替代品。
| 背景類型 | 通常能站得住腳的陰影方向 | 為什麼相同的數字可能會出問題 |
|---|---|---|
| 平坦淺色表面(接近白色) | 微小的向下偏移、低模糊、較深的陰影顏色 | 大偏移會產生雙重視覺;高模糊會降低小文字的清晰度 |
| 平坦深色表面(接近黑色) | 帶小偏移的柔和低透明度淺色陰影 | 深色背景中的硬黑陰影會消失;大模糊會將字型融入表面 |
| 飽和或品牌色表面 | 中性化的陰影顏色、溫和的模糊、小心的對比檢查 | 陰影會帶上背景的色相,可能無法與文字區分開來 |
| 有圖案或照片的表面 | 較低模糊搭配與中間背景色調更強的顏色對比 | 模糊會擴散到圖案中,並與字型形狀競爭 |
質性的重點是,任何在一個背景上的可見改進,在另一個背景上可能是一個退步。請務必針對實際背景測量前景文字,而非針對陰影,並且永遠不要將裝飾性陰影視為文字對比的替代品。
將一個經過稽核的圖層整合到你的權杖系統中
一旦宣告看起來正確,就以現有的顏色權杖取代字面值,而不是在元件庫中散布十六進制代碼。單一陰影行能乾淨地融入排版或高度權杖,而精簡的輸入契約意味著每個欄位恰好只有一個決定:哪個權杖提供偏移、哪個提供模糊、哪個提供顏色。這個對應比多圖層堆疊容易審查得多,在重構開始時,後者的圖層順序會變得舉足輕重。
它也避免了陰影堆疊傾向引入的警告信號。堆疊許多圖層會讓文字變得模糊、增加繪製工作,並掩蓋原始字型。如果真正的輪廓效果是目標,分層陰影有時可以達成,但描邊、SVG 或不同的設計處理方式可能會更清楚地表達。單層產生器是一個刻意的限制,而不是一個缺失的功能。
What the generator cannot certify
Validated bounds are not the same as a production guarantee. The tool cannot certify accessibility, performance, or compatibility for a particular product, and it intentionally omits font family, weight, size, line height, transitions, and animation because those properties belong to the host typography system. The shadow that looks crisp at 16 px on a laptop may shimmer on a phone, and the shadow that holds contrast at zoom 100 percent may collapse at zoom 200 percent or in forced-color mode.
Strong offsets create double vision, and large blur can reduce clarity for small type. Text shadows also affect rendering cost when applied to large text, many repeated nodes, or animated values, so keep layers limited and avoid continuously animating blur. Check zoom, high-contrast and forced-color modes, dark themes, screenshots, printing, and every background the text can cross.
Avoid using shadow direction or color as the only cue for state. Headings, buttons, and links still require semantic structure and visible focus treatment. The grammar is fully documented in the W3C CSS Text Decoration specification and the MDN text-shadow reference; turning one audited line into accessible, performant markup belongs to the component that hosts it.