教學 1 - 您的第一個應用程式¶

我們已準備好創建我們的第一個應用程式。

安裝 BeeWare 工具¶

首先，我們需要安裝 Briefcase。它是一個 BeeWare 工具，可用於打包應用程式以分發給最終用戶 - 但它也可用於引導新專案。確保您位於教學 0 中建立的 beeware-tutorial 目錄中，啟動 beeware-venv 虛擬環境，然後執行：

macOSLinuxWindows

(beeware-venv) $ python -m pip install briefcase

(beeware-venv) $ python -m pip install briefcase

安裝時可能發生的錯誤

如果您在安裝過程中看到錯誤，幾乎可以肯定是因為某些系統需求尚未安裝。請確定您已安裝所有平台先決條件。

(beeware-venv) C:\...>python -m pip install briefcase

安裝時可能發生的錯誤

使用 python -m pip ，而不是只有 pip ，這一點很重要。 Briefcase需要確保它有最新版本的 pip 和 setuptools ，並且單純調用 pip 無法自我更新。如果您想了解更多信息，Brett Cannon 有一篇關於該問題的詳細博客文章。

開始一個新項目¶

讓我們開始第一個 BeeWare 專案！我們要使用 Briefcase new 指令來建立一個名為 Hello World 的應用程式。從您的命令提示符執行以下指令：

macOSLinuxWindows

(beeware-venv) $ briefcase new

(beeware-venv) $ briefcase new

(beeware-venv) C:\...>briefcase new

Briefcase 將詢問我們新應用程式的一些詳細資訊。出於本教學的目的，請使用以下內容：

正式名稱 - 接受預設值： Hello World 。
應用程式名稱 - 接受預設值： helloworld 。
封裝名稱 - 如果您擁有自己的網域，請以相反的順序輸入該網域。（例如，如果您擁有網域名稱 cupcakes.com ，請輸入 com.cupcakes 作為捆綁包）。如果您不擁有自己的網域，請接受預設捆綁包（ com.example ）。
項目名稱 - 接受預設值： Hello World 。
描述 - 接受預設值（或者，如果您想真正發揮創意，請提出您自己的描述！）
作者 - 在此輸入您自己的姓名。
作者的電子郵件 - 輸入您自己的電子郵件地址。這將用在設定檔、說明文字以及將應用程式提交到應用程式商店時需要電子郵件的任何地方。
URL - 您的應用程式的登入頁面的 URL。同樣，如果您擁有自己的網域，請輸入該網域的 URL（包括 https:// ）。否則，只需接受預設 URL (https://example.com/helloworld)。該 URL 不需要實際存在（目前）；只有當您將應用程式發佈到應用程式商店時才會使用它。
許可證 - 接受預設許可證 (BSD)。不過，這不會影響本教學的操作 - 因此，如果您對許可證選擇有特別強烈的感覺，請隨意選擇其他許可證。
GUI 框架 - 接受預設選項 Toga（BeeWare 自己的 GUI 工具）。

然後，Briefcase 將產生一個專案框架供您使用。如果您到目前為止已經遵循了本教學，並接受了所描述的預設設置，您的資料夾應該類似於：

beeware-tutorial/
├── beeware-venv/
│   └── ...
└── helloworld/
    ├── CHANGELOG
    ├── LICENSE
    ├── pyproject.toml
    ├── README.rst
    ├── src/
    │   └── helloworld/
    │       ├── app.py
    │       ├── __init__.py
    │       ├── __main__.py
    │       └── resources/
    │           └── README
    └── tests/
        ├── helloworld.py
        ├── __init__.py
        └── test_app.py

這個框架實際上是一個功能齊全的應用程式，無需添加任何其他內容。 src 資料夾包含應用程式的所有程式碼， tests 資料夾包含初始測試套件， pyproject.toml 檔案描述如何打包應用程式以進行分發。如果您在編輯器中開啟 pyproject.toml ，您將看到剛剛提供給 Briefcase 的設定詳細資訊。

現在我們有了一個未打包的應用程式，我們可以使用 Briefcase 來運行該應用程式。

在開發者模式下運行應用程式¶

進入 helloworld 專案目錄並告訴公事包以開發人員（或 dev ）模式啟動專案：

macOSLinuxWindows

(beeware-venv) $ cd helloworld
(beeware-venv) $ briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cpython-313-darwin)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

(beeware-venv) $ cd helloworld
(beeware-venv) $ briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cpython-313-x86_64-linux-gnu)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

(beeware-venv) C:\...>cd helloworld
(beeware-venv) C:\...>briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cp313-win_amd64)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

這應該打開一個 GUI 視窗：

macOSLinuxWindows

執行 briefcase dev 時可能發生的錯誤

若執行 briefcase dev 時出現錯誤，幾乎可確定是某些系統需求尚未安裝。請確認您已安裝所有平台先決條件；您收到的錯誤訊息應會告知哪些套件缺失。

無效需求或 pip 無法連線

如果遇到錯誤：

Unable to install requirements. This may be because one of your
requirements is invalid, or because pip was unable to connect
to the PyPI server.

確認您正在執行本教學支援的 python 版本。

如果您的 python 版本不是**支援的版本，您必須重新啟動教學。

按下關閉按鈕（或從應用程式的選單中選擇退出），就完成了！恭喜 - 您剛剛用 Python 編寫了一個獨立的本機應用程式！

下一步¶

我們現在有了一個可以運行的應用程序，在開發人員模式下運行。現在我們可以添加一些我們自己的邏輯，使我們的應用程式做一些更有趣的事情。在 :doc:教程 2 中<tutorial-2>，我們將在我們的應用程式中放置一個更有用的使用者介面。