🔧 阿川の電商水電行

Shopify 顧問、維護與客製化

💡

小任務 / 單次支援方案

單次處理 Shopify 修正／微調

⭐️

維護方案

每月 Shopify 技術支援 + 小修改 + 諮詢

🚀

專案建置

Shopify 功能導入、培訓 + 分階段交付

👉 瞭解詳情 / 免費諮詢

小編精選 - 技術文章翻譯 · 11月10日

【新手完全指南】從零開始掌握 React 開發基礎的終極教學：音樂生成應用版【圖解指南】

前言

你好，我是Watanabe jin。
隨著AI技術的興起，越來越多人希望學習React。

我自己過去也做了很多React的教材，但真正讓我覺得值得的教材幾乎沒有。
選擇的教材會極大影響學習React的速度，因為React的教材需要基於JavaScript的非同步處理和map等概念來進行解釋。

本教程旨在為當時還是菜鳥的我提供一份「只需學習這一篇就足夠掌握基礎」的完整教材。即使您對JavaScript僅有一些皮毛的了解，也能透過本教程完成整個過程。

完成本教程後，您將能夠製作出像Spotify一樣的應用。

名稱未設定的設計 (5).gif

我們提供視頻教材

這裡的教材還配合了更詳細解說的視頻。
如果在文本教材中遇到不清楚的細節，請務必查看視頻。

這篇文章的目標讀者

想要最快學會React
想從零開始學習React
希望以輸出為主的學習方式
想要扎實提高實力
想要學習現代化開發

只要懂得HTML/CSS，您就能在2小時內完成這篇教程

1. 設置React環境

這一章能學到的內容

React開發環境的基本設置
React的基本運作原理
提高開發效率的機制

本章將解釋如何設置React環境。
我希望您能按照步驟完成環境設置，從而能夠以可重複的方式開始學習React。

1. 生的React代碼無法直接執行

React使用了一種名為JSX的特殊語法，因此瀏覽器不能直接解釋（理解）它。

JSX是JavaScriptXML的縮寫，作為一種語法糖，讓您可以在JavaScript代碼中直接編寫HTML。

function Greeting() {
  return <div>你好，世界！</div>
}

即使這樣寫，瀏覽器也無法識別。
這是因為為了使JavaScript更易於理解，我們使用JSX這種直觀的寫法。

實際上，JSX會在內部被編譯並轉換為JavaScript。

function Greeting() {
  return React.createElement(
    'div',
    null,
    '你好，世界！'
  );
}

JSX最終會被轉換為對React.createElement的調用。
不過這樣寫不便於開發，所以我們用JSX這種易於理解的形式來編寫。（當然，這種格式寫在.js檔案中React也能使用）

將JSX轉換為JavaScript的工具是Vite。
這種將代碼轉換的工具稱為構建工具。

JSX是在使用JavaScript的情況下的形式，本教程將使用TypeScript來進行，所以將使用 TSX 格式。除檔案副檔名從hoge.jsx更改為hoge.tsx之外，只要記住名稱不同即可。

2. 提供高速開發環境

透過使用Vite，當您變更代碼後，無需刷新畫面，變更會立即反映出來。

例如，在畫面內更改文字時，使用Vite會立即構建（將JSX轉換為JavaScript），使開發流程更加順暢。

雖然市場上有許多構建工具，如Webpack，但Vite是其中速度特別快的工具。

因此，我們可以輕鬆地設置一個包含不可或缺的Vite的React開發環境。

首先，我們來檢查是否安裝了Node.js。

$ node -v
v24.3.0

如果您還未安裝Node.js，請從以下網站下載適合您操作系統的版本。

Node.js為您的PC提供執行JavaScript的環境。
那麼，讓我們根據官方文檔使用Vite構建React環境。

npm create vite@latest

在過程中會出現選項，您依序選擇「y」->「music-creator-app」->「React」->「TypeScript」。
雖然這是針對初學者的選擇，但考慮到目前的時代，選擇TypeScript是必要的，因此我們會逐步熟悉它。這部分會有詳細的解釋。

創建專案後，讓我們啟動Vite伺服器。

cd music-creator-app
npm install
npm run dev

 VITE v6.3.5  ready in 115 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

這樣伺服器就啟動了。
打開http://localhost:5173，如果看到以下畫面，則表示啟動成功。

npm是一個命令，這裡需要說明一下。

npm install

此命令會從互聯網上下載並安裝專案所需的所有套件（部件）。所需的套件清單會寫在目錄中的package.json中。

{
  "name": "movie-app",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.1.0",
    "react-dom": "^19.1.0"
  },
  "devDependencies": {
    "@eslint/js": "^9.25.0",
    "@types/react": "^19.1.2",
    "@types/react-dom": "^19.1.2",
    "@vitejs/plugin-react": "^4.4.1",
    "eslint": "^9.25.0",
    "eslint-plugin-react-hooks": "^5.2.0",
    "eslint-plugin-react-refresh": "^0.4.19",
    "globals": "^16.0.0",
    "typescript": "~5.8.3",
    "typescript-eslint": "^8.30.1",
    "vite": "^6.3.5"
  }
}

這裡的dependencies和devDependencies中列出的套件將被下載到node_modules目錄中。試著查看node_modules，您可以發現裡面有很多目錄。

這樣，您可以事先定義並下載開發React所需的所有內容，因此無需逐一下載每個部件即可使用install命令建立相同的環境。

npm run dev

此命令會啟動開發用的本地伺服器並執行應用。
伺服器啟動後，它會監控代碼變更，如果有變更，會立即反映，這就是使用Vite的優勢。

讓我們嘗試修改代碼。（在這裡，即使不完全理解也沒關係）

請將src/App.tsx修改為以下內容：

import './App.css';

function App() {
  return (
    <div>
      <h1>Hello World</h1>
    </div>
  );
}

export default App;

然後伺服器會立即更新並輸出日誌。

7:49:20 PM [vite] (client) hmr update /src/App.tsx
7:49:26 PM [vite] (client) hmr update /src/App.tsx (x2)
7:49:34 PM [vite] (client) hmr update /src/App.tsx (x3)
7:49:36 PM [vite] (client) hmr update /src/App.tsx (x4)

而在畫面中，您會看到代碼一保存後，變更便立即反映出來。

這就是使用Vite進行React開發的優勢！

2. 理解JSX

這一章能學到的內容

理解JSX的寫法
JavaScript的map概念
之後的進一步學習

接下來我們將進入真正的React開發。
首先，我們應該看看如何編寫React代碼。

現在請打開src/App.tsx。

import './App.css';

function App() {
  return (
    <div>
      <h1>Hello World</h1>
    </div>
  );
}

export default App;

tsx可以用以下結構來編寫。

function App() {
  // 在此編寫JavaScript代碼

  return (
    /* 在這裡編寫HTML來設計界面 */
  );
}

export default App;

大概理解到這裡就可以繼續進行了。

例如剛才的修改是為了在HTML中顯示Hello World，所以我們把它寫在return的內容中：

  return (
    <div>
      <h1>Hello World</h1>
    </div>
  );

現在讓我們試著編寫一些JavaScript代碼。我們來實現一個警示框。

import './App.css';

function App() {
  alert('執行JavaScript');

  return (
    <div>
      <h1>Hello World</h1>
    </div>
  );
}

export default App;

當打開http://localhost:5173時，將會顯示警示框。
JavaScript會在內部執行，然後進行畫面顯示處理。（由於React的特性，因此會出現兩次警示框的情況，所以先不必在意）

這段代碼是用來使App.tsx同級的App.css可用的設置。（這是用來設置CSS的文件）
現在我們來試試將其內容改為以下內容：

h1 {
  color: red;
}

由於警示框太過煩人，讓我們把它刪除。

import './App.css';

function App() {
  return (
    <div>
      <h1>Hello World</h1>
    </div>
  );
}

export default App;

當打開畫面後，您會看到h1元素變為紅色，這表明CSS文件被成功加載。

※ 當確認CSS有效後，請將其恢復到原狀，然後繼續進行後面的步驟。

3. 嘗試導入樣式庫

這一章能學到的內容

TailwindCSS是什麼？
如何導入到Vite專案中

雖然可以繼續編寫CSS文件，但通過導入樣式庫tailwindCSS可以更輕鬆地進行樣式設置。

TailwindCSS是一種CSS框架，它通過組合事先準備的小類名來進行樣式設置。這樣一來，您不必考慮自己創建獨特的類名，而是可以高效地使用事先準備好的類名進行樣式設置。

例如，當您嘗試設置這樣的樣式時：

.title {
  font-size: 24px;
  font-weight: bold;
  color: #1f2937;
  margin-bottom: 16px;
}

如果使用TailwindCSS，只需添加一個類名即可設定相同的樣式：

<h1 className="text-2xl font-bold text-gray-800 mb-4">音樂生成應用</h1>

在JSX中設置類名時，需要使用className這個屬性。
關於TailwindCSS的詳細信息，類名與樣式可參考官方文檔。

例如，text-2xl對應於font-size的設置。

這次因為樣式不是本教程的核心，因此詳細說明就不贅述了，感興趣的部分可以自行查找。

現在讓我們導入TailwindCSS。
只需按照官方文檔的步驟進行設置即可。

npm install tailwindcss @tailwindcss/vite

在vite.config.ts中進行TailwindCSS的配置。

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss()],
});

接下來在indx.css中加載樣式。

@import "tailwindcss";

請將App.css中的所有樣式刪除。

由於希望在整個專案中使用TailwindCSS，因此我們在index.css中添加了設置。
如果在App.css中添加，則只有JSX中引入的App.css才會使用。

在React中，根本有一個名為main.tsx的文件，從中創建各種頁面。
在這個根本中，我們引入了

import './index.css'

作為可以全局使用的CSS，並在此中渲染了App組件。

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

這個App就是我們之前修改的代碼。

組件是構建React用戶界面的部件，就像樂高積木一樣，通過組合可以創建一個頁面。此次的App組件也是一個比較大的組件。

組件的寫法有「函數組件」和「類組件」，而目前函數組件已經成為主流。同樣，App組件也是寫成這樣的。

組件是可重用的，因此像Greeting這樣多次使用，便能輕鬆顯示「你好，React！」。

那麼讓我們來檢查是否成功導入TailwindCSS。

import './App.css';

function App() {
  return (
    <div>
      <h1 className="text-2xl font-bold text-gray-800 mb-4">音樂生成應用</h1>
    </div>
  );
}

export default App;

如果這樣顯示就表明樣式設置成功。

4. 在Shadcn/UI中輕鬆實現精美UI

這一章能學到的內容

Shadcn/UI是什麼，為什麼要使用它
如何導入Shadcn/UI
實現按鈕組件

雖然透過TailwindCSS已經設置了樣式的基礎，但在實際的應用開發中，像按鈕、卡片、模態框等複雜的組件從零開始開發會佔用大量時間。

這時候便需要用到Shadcn/UI。
Shadcn/UI是一個「可以直接複製使用的高品質React組件集」。

傳統開發的艱辛

例如，想要製作音樂應用中常見的「播放按鈕」，其代碼可能如下：

<button className="bg-green-500 hover:bg-green-600 text-white font-bold py-2 px-4 rounded-full shadow-lg transition-all duration-200 hover:shadow-xl hover:scale-105 active:scale-95 flex items-center gap-2">
  <PlayIcon className="w-4 h-4" />
  播放
</button>

這段代碼就能長得像這樣，並且除了基本樣式外，還需要考慮：

鼠標懸停時的動畫
點擊時的效果
圖標的排列
無障礙性支持

因此，僅僅製作一個按鈕就需要耗費相當多的時間。

使用Shadcn/UI的情況

import { Button } from "@/components/ui/button";

<Button variant="default" size="lg">
  播放
</Button>

如此簡單的幾行代碼，就能完成一個精美的按鈕。

Shadcn/UI是在前面導入的TailwindCSS的基礎上創建的，因此必須事先導入TailwindCSS。（由於我們已經導入，這部分沒問題）

導入Shadcn/UI的方法

現在讓我們實際參考官方文檔進行導入。

npx shadcn@latest init

Ok to proceed? (y) y

✔ Preflight checks.
✔ Verifying framework. Found Vite.
✔ Validating Tailwind CSS config. Found v4.
✔ Validating import alias.
✔ Which color would you like to use as the base color? › Neutral

在這裡完全按照官方文檔的步驟進行，將不再贅述。
現在，讓我們將按鈕組件添加到應用中。

npx shadcn@latest add button

這樣會創建一個名為src/components/ui/button.tsx的文件。

這就是Shadcn/UI為您創建的組件。
現在讓我們按照之前學到的將其在App.tsx中使用一下。

import './App.css';
import { Button } from './components/ui/button';

function App() {
  return (
    <div>
      <h1>Hello World</h1>
      <Button>播放</Button>
    </div>
  );
}

export default App;

首先要從外部導入（引用）組件。

import { Button } from './components/ui/button';

然後使用Button組件。

<Button>播放</Button>

Button組件的用法可以參考文檔。

當富有特色的按鈕顯示時，則表示導入成功。

5. 使用React Router設置頁面

這一章能學到的內容

React Router是什麼，為什麼要使用它
如何設置多個頁面

為了製作音樂應用，您需要多個頁面。

音樂列表頁
音樂創建頁

這時候我們將使用名為React Router的路由庫。

為什麼需要React Router？

在一般的網站中，每當您移動頁面時，系統需要從伺服器下載新的HTML文件。

對於普通網站而言
首頁 → 下載index.html
聯繫我們頁 → 下載contact.html
商品頁 → 下載product.html

但React應用只能使用一個HTML文件。
無論您在查看哪個頁面，系統始終使用相同的HTML文件（通常是index.html），並使用JavaScript僅更改畫面的內容。

這種機制稱為單頁應用程序（SPA）。

SPA的問題

SPA存在一個根本性的問題。
無論您在查看哪個頁面，URL都將保持為 http://localhost:5173/。

URL不變會引發以下問題。

無法將收藏頁面添加到書籤
無法將特定頁面URL告訴朋友以展示內容
瀏覽器的「返回」按鈕無法正常工作

使用React Router解決

透過React Router，可以將URL與顯示的內容進行連動。

http://localhost:5173/ → 顯示音樂列表頁
http://localhost:5173/create → 顯示音樂創建頁

React Router的工作原理是當URL改變時，顯示的組件會切換，讓頁面看起來像有多個頁面。

接下來，讓我們實際導入React Router。

導入React Router

我們也按照官方文檔進行設定。
※ React Router有兩種模式，但這次我們使用的是資料模式（不是框架模式）。

npm i react-router

現在讓我們設置路由。

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";
import { createBrowserRouter, RouterProvider } from "react-router";
import CreatePage from "./CreatePage.tsx";

const router = createBrowserRouter([
  {
    path: "/",
    element: <App />,
  },
  {
    path: "/create",
    element: <CreatePage />,
  },
]);

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <RouterProvider router={router} />
  </StrictMode>,
);

從React Router中導入所需的功能。

import { createBrowserRouter, RouterProvider } from "react-router";

然後設置路由。

const router = createBrowserRouter([
  {
    path: "/",
    element: <App />,
  },
  {
    path: "/create",
    element: <CreatePage />,
  },
]);

本次設置了兩個頁面（列表與創建），path是URL，element則指定顯示的組件。

path: "/" → 當URL是 http://localhost:5173/ 時
element: → 顯示App組件

將設置的路由應用於React應用。

<RouterProvider router={router} />

現在創建頁面(CreatePage組件)是必須的，所以我們來創建它。

touch src/CreatePage.tsx

function CreatePage() {
  return <div>音樂創建頁</div>;
}

export default CreatePage;

讓我們檢查是否正常運行。
訪問以下URL並確認頁面切換是否有效：
顯示頂頁 http://localhost:5173/
顯示創建頁 http://localhost:5173/create

6. 創建音樂列表頁

現在我們將實際創建音樂應用。
首先將事先準備的音樂數據顯示在列表中。

這一章能學到的內容

顯示數組數據的方法
map方法的使用
音樂播放功能的實現
事件處理程序的基礎

準備音樂數據

首先，讓我們準備要顯示的音樂數據。
將src/App.tsx修改如下：

import './App.css';

function App() {
  const musicList = [
    {
      id: 1,
      title: "Synthwave Dreams",
      artist: "AI Composer",
      audioUrl: "https://commondatastorage.googleapis.com/codeskulptor-demos/DDR_assets/Kangaroo_MusiQue_-_The_Neverwritten_Role_Playing_Game.mp3",
      coverUrl: "https://images.unsplash.com/photo-1493225457124-a3eb161ffa5f?w=400&h=400&fit=crop&crop

原文出處：https://qiita.com/Sicut_study/items/c0096caf21eefcd5c85f