mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-20 04:58:52 +00:00
docs: update zh-tw (#197)
Signed-off-by: appleboy <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/197 Co-authored-by: appleboy <[email protected]> Co-committed-by: appleboy <[email protected]>
This commit is contained in:
appleboy
+86
-88
@@ -6,131 +6,129 @@ aliases:
|
||||
- /zh-tw/guidelines-frontend
|
||||
---
|
||||
|
||||
# Guidelines for Frontend Development
|
||||
# 前端開發指南
|
||||
|
||||
## Background
|
||||
## 背景
|
||||
|
||||
Gitea uses [Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html) (based on [jQuery](https://api.jquery.com)) and [Vue3](https://vuejs.org/) for its frontend.
|
||||
Gitea 使用 [Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基於 [jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/) 作為前端框架。
|
||||
|
||||
The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template).
|
||||
HTML 頁面由 [Go HTML Template](https://pkg.go.dev/html/template) 渲染。
|
||||
|
||||
The source files can be found in the following directories:
|
||||
源文件可以在以下目錄中找到：
|
||||
|
||||
- **CSS styles:** `web_src/css/`
|
||||
- **JavaScript files:** `web_src/js/`
|
||||
- **Vue components:** `web_src/js/components/`
|
||||
- **Go HTML templates:** `templates/`
|
||||
- **CSS 樣式：** `web_src/css/`
|
||||
- **JavaScript 文件：** `web_src/js/`
|
||||
- **Vue 組件：** `web_src/js/components/`
|
||||
- **Go HTML 模板：** `templates/`
|
||||
|
||||
## General Guidelines
|
||||
## 一般指南
|
||||
|
||||
We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) and [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
|
||||
我們推薦 [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) 和 [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
|
||||
|
||||
### Gitea specific guidelines
|
||||
### Gitea 特定指南
|
||||
|
||||
1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
|
||||
2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords.
|
||||
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
|
||||
4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful.
|
||||
5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data.
|
||||
6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
|
||||
7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`.
|
||||
8. Use semantic elements, prefer `<button class="ui button">` instead of `<div class="ui button">`.
|
||||
9. Avoid unnecessary `!important` in CSS, add comments to explain why it's necessary if it can't be avoided.
|
||||
10. Avoid mixing different events in one event listener, prefer to use individual event listeners for every event.
|
||||
11. Custom event names are recommended to use `ce-` prefix.
|
||||
12. Prefer using Tailwind CSS which is available via `tw-` prefix, e.g. `tw-relative`. Gitea's helper CSS classes use `gt-` prefix (`gt-ellipsis`), while Gitea's own private framework-level CSS classes use `g-` prefix (`g-modal-confirm`).
|
||||
13. Avoid inline scripts & styles as much as possible, it's recommended to put JS code into JS files and use CSS classes. If inline scripts & styles are unavoidable, explain the reason why it can't be avoided.
|
||||
1. 每個功能（Fomantic-UI/jQuery 模塊）應該放在單獨的文件/目錄中。
|
||||
2. HTML id 和 class 應該使用 kebab-case，最好包含 2-3 個與功能相關的關鍵詞。
|
||||
3. 在 JavaScript 中使用的 HTML id 和 class 應該在整個項目中是唯一的，並且應該包含 2-3 個與功能相關的關鍵詞。我們建議對僅在 JavaScript 中使用的 class 使用 `js-` 前綴。
|
||||
4. 不應覆蓋框架提供的 class 的 CSS 樣式。始終使用包含 2-3 個與功能相關的關鍵詞的新 class 名稱來覆蓋框架樣式。Gitea 的 `helpers.less` 中的輔助 CSS class 可能會有所幫助。
|
||||
5. 後端可以使用 `ctx.PageData["myModuleData"] = map[]{}` 將複雜數據傳遞給前端，但不要將整個模型暴露給前端，以避免洩露敏感數據。
|
||||
6. 簡單頁面和與 SEO 相關的頁面使用 Go HTML Template 渲染生成靜態 Fomantic-UI HTML 輸出。複雜頁面可以使用 Vue3。
|
||||
7. 明確變量類型，優先使用 `elem.disabled = true` 而不是 `elem.setAttribute('disabled', 'anything')`，優先使用 `$el.prop('checked', var === 'yes')` 而不是 `$el.prop('checked', var)`。
|
||||
8. 使用語義化元素，優先使用 `<button class="ui button">` 而不是 `<div class="ui button">`。
|
||||
9. 避免在 CSS 中不必要的 `!important`，如果無法避免，請添加註釋解釋為什麼是必要的。
|
||||
10. 避免在一個事件監聽器中混合不同的事件，優先為每個事件使用單獨的事件監聽器。
|
||||
11. 自定義事件名稱建議使用 `ce-` 前綴。
|
||||
12. 優先使用 Tailwind CSS，通過 `tw-` 前綴可用，例如 `tw-relative`。Gitea 的輔助 CSS class 使用 `gt-` 前綴（`gt-ellipsis`），而 Gitea 自己的私有框架級 CSS class 使用 `g-` 前綴（`g-modal-confirm`）。
|
||||
13. 盡可能避免內聯腳本和樣式，建議將 JS 代碼放入 JS 文件並使用 CSS class。如果內聯腳本和樣式是不可避免的，請解釋為什麼無法避免。
|
||||
|
||||
### Accessibility / ARIA
|
||||
### 無障礙 / ARIA
|
||||
|
||||
In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework.
|
||||
Gitea uses some patches to make Fomantic UI more accessible (see `aria.md` and related JS files),
|
||||
but there are still many problems which need a lot of work and time to fix.
|
||||
歷史上，Gitea 大量使用 Fomantic UI，這不是一個無障礙友好的框架。
|
||||
Gitea 使用一些補丁使 Fomantic UI 更加無障礙（見 `aria.md` 和相關的 JS 文件），
|
||||
但仍然存在許多問題，需要大量工作和時間來修復。
|
||||
|
||||
### Framework Usage
|
||||
### 框架使用
|
||||
|
||||
Mixing different frameworks together is discouraged, it makes the code difficult to be maintained.
|
||||
A JavaScript module should follow one major framework and follow the framework's best practice.
|
||||
不建議混合使用不同的框架，這會使代碼難以維護。
|
||||
JavaScript 模塊應該遵循一個主要框架並遵循該框架的最佳實踐。
|
||||
|
||||
Recommended implementations:
|
||||
推薦的實現：
|
||||
|
||||
- Vue + Vanilla JS
|
||||
- Vue + 原生 JS
|
||||
- Fomantic-UI (jQuery)
|
||||
- htmx (partial page reloads for otherwise static components)
|
||||
- Vanilla JS
|
||||
- htmx（部分頁面重新加載，適用於靜態組件）
|
||||
- 原生 JS
|
||||
|
||||
Discouraged implementations:
|
||||
不推薦的實現：
|
||||
|
||||
- Vue + Fomantic-UI (jQuery)
|
||||
- jQuery + Vanilla JS
|
||||
- htmx + any other framework which requires heavy JS code, or unnecessary features like htmx scripting (`hx-on`)
|
||||
- jQuery + 原生 JS
|
||||
- htmx + 任何需要大量 JS 代碼的框架，或不必要的功能如 htmx 腳本（`hx-on`）
|
||||
|
||||
To make UI consistent, Vue components can use Fomantic-UI CSS classes.
|
||||
We use htmx for simple interactions. You can see an example for simple interactions where htmx should be used in this [PR](https://github.com/go-gitea/gitea/pull/28908). Do not use htmx if you require more advanced reactivity, use another framework (Vue/Vanilla JS).
|
||||
Although mixing different frameworks is discouraged,
|
||||
it should also work if the mixing is necessary and the code is well-designed and maintainable.
|
||||
為了使 UI 一致，Vue 組件可以使用 Fomantic-UI CSS class。
|
||||
我們使用 htmx 進行簡單的交互。你可以在這個 [PR](https://github.com/go-gitea/gitea/pull/28908) 中看到一個使用 htmx 進行簡單交互的示例。如果你需要更高級的反應性，請使用其他框架（Vue/原生 JS）。
|
||||
雖然不建議混合使用不同的框架，
|
||||
但如果混合是必要的並且代碼設計良好且可維護，應該也是可行的。
|
||||
|
||||
### Typescript
|
||||
|
||||
Gitea is in the process of migrating to type-safe Typescript. Here are some specific guidelines regarding Typescript in the codebase:
|
||||
Gitea 正在遷移到類型安全的 Typescript。以下是一些關於 Typescript 在代碼庫中的具體指南：
|
||||
|
||||
#### Use type aliases instead of interfaces
|
||||
#### 使用類型別名而不是接口
|
||||
|
||||
Prefer to use type aliases because they can represent any type and are generally more flexible to use than interfaces.
|
||||
優先使用類型別名，因為它們可以表示任何類型，並且通常比接口更靈活。
|
||||
|
||||
#### Use separate type imports
|
||||
#### 使用單獨的類型導入
|
||||
|
||||
We use `verbatimModuleSyntax` so type and non-type imports from the same file must be split into two `import type` statements. This enables the typescript compiler to completely eliminate the type import statements during compilation.
|
||||
我們使用 `verbatimModuleSyntax`，因此來自同一文件的類型和非類型導入必須分成兩個 `import type` 語句。這使得 typescript 編譯器在編譯過程中可以完全消除類型導入語句。
|
||||
|
||||
#### Use `@ts-expect-error` instead of `@ts-ignore`
|
||||
#### 使用 `@ts-expect-error` 而不是 `@ts-ignore`
|
||||
|
||||
Both annotations should be avoided, but if you have to use them, use `@ts-expect-error` because it will not leave ineffective statements after the issue is fixed.
|
||||
應避免使用這兩個註釋，但如果必須使用，請使用 `@ts-expect-error`，因為在問題修復後它不會留下無效的語句。
|
||||
|
||||
### `async` Functions
|
||||
### `async` 函數
|
||||
|
||||
Only mark a function as `async` if and only if there are `await` calls
|
||||
or `Promise` returns inside the function.
|
||||
只有在函數內部有 `await` 調用或返回 `Promise` 時，才將函數標記為 `async`。
|
||||
|
||||
It's not recommended to use `async` event listeners, which may lead to problems.
|
||||
The reason is that the code after await is executed outside the event dispatch.
|
||||
Reference: https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
|
||||
不建議使用 `async` 事件監聽器，這可能會導致問題。
|
||||
原因是 `await` 之後的代碼在事件分派之外執行。
|
||||
參考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
|
||||
|
||||
If an event listener must be `async`, the `e.preventDefault()` should be before any `await`,
|
||||
it's recommended to put it at the beginning of the function.
|
||||
如果事件監聽器必須是 `async`，則 `e.preventDefault()` 應在任何 `await` 之前，
|
||||
建議將其放在函數的開頭。
|
||||
|
||||
If we want to call an `async` function in a non-async context,
|
||||
it's recommended to use `const _promise = asyncFoo()` to tell readers
|
||||
that this is done by purpose, we want to call the async function and ignore the Promise.
|
||||
Some lint rules and IDEs also have warnings if the returned Promise is not handled.
|
||||
如果我們想在非 `async` 上下文中調用 `async` 函數，
|
||||
建議使用 `const _promise = asyncFoo()` 來告訴讀者
|
||||
這是故意這樣做的，我們想調用 `async` 函數並忽略 Promise。
|
||||
一些 lint 規則和 IDE 也會在未處理返回的 Promise 時發出警告。
|
||||
|
||||
### Fetching data
|
||||
### 獲取數據
|
||||
|
||||
To fetch data, use the wrapper functions `GET`, `POST` etc. from `modules/fetch.js`. They
|
||||
accept a `data` option for the content, will automatically set CSRF token and return a
|
||||
Promise for a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).
|
||||
要獲取數據，請使用 `modules/fetch.js` 中的包裝函數 `GET`、`POST` 等。
|
||||
它們接受一個 `data` 選項作為內容，會自動設置 CSRF 令牌並返回一個 [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 的 Promise。
|
||||
|
||||
### HTML Attributes and `dataset`
|
||||
### HTML 屬性和 `dataset`
|
||||
|
||||
The usage of `dataset` is forbidden, its camel-casing behaviour makes it hard to grep for attributes.
|
||||
However, there are still some special cases, so the current guideline is:
|
||||
禁止使用 `dataset`，其駝峰命名行為使得很難 grep 屬性。
|
||||
然而，仍然存在一些特殊情況，所以目前的指南是：
|
||||
|
||||
- For legacy code:
|
||||
- 對於遺留代碼：
|
||||
|
||||
- `$.data()` should be refactored to `$.attr()`.
|
||||
- `$.data()` can be used to bind some non-string data to elements in rare cases, but it is highly discouraged.
|
||||
- `$.data()` 應重構為 `$.attr()`。
|
||||
- `$.data()` 可以在罕見情況下用於將一些非字符串數據綁定到元素，但這是高度不建議的。
|
||||
|
||||
- For new code:
|
||||
- `node.dataset` should not be used, use `node.getAttribute` instead.
|
||||
- never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.
|
||||
- 對於新代碼：
|
||||
- 不應使用 `node.dataset`，應使用 `node.getAttribute`。
|
||||
- 永遠不要將任何用戶數據綁定到 DOM 節點，應使用合適的設計模式來描述節點和數據之間的關係。
|
||||
|
||||
### Show/Hide Elements
|
||||
### 顯示/隱藏元素
|
||||
|
||||
- Vue components are recommended to use `v-if` and `v-show` to show/hide elements.
|
||||
- Go template code should use `.tw-hidden` and `showElem()/hideElem()/toggleElem()`, see more details in `.tw-hidden`'s comment.
|
||||
- Vue 組件建議使用 `v-if` 和 `v-show` 來顯示/隱藏元素。
|
||||
- Go 模板代碼應使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()`，詳情見 `.tw-hidden` 的註釋。
|
||||
|
||||
### Styles and Attributes in Go HTML Template
|
||||
### Go HTML 模板中的樣式和屬性
|
||||
|
||||
It's recommended to use:
|
||||
建議使用：
|
||||
|
||||
```html
|
||||
<div
|
||||
@@ -140,7 +138,7 @@ It's recommended to use:
|
||||
></div>
|
||||
```
|
||||
|
||||
instead of:
|
||||
而不是：
|
||||
|
||||
```html
|
||||
<div
|
||||
@@ -151,16 +149,16 @@ instead of:
|
||||
></div>
|
||||
```
|
||||
|
||||
to make the code more readable.
|
||||
以使代碼更具可讀性。
|
||||
|
||||
### Legacy Code
|
||||
### 遺留代碼
|
||||
|
||||
A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.
|
||||
在撰寫本文檔之前，已經存在許多遺留代碼。建議重構遺留代碼以遵循這些指南。
|
||||
|
||||
### Vue3 and JSX
|
||||
### Vue3 和 JSX
|
||||
|
||||
Gitea is using Vue3 now. We decided not to introduce JSX to keep the HTML and the JavaScript code separated.
|
||||
Gitea 現在使用 Vue3。我們決定不引入 JSX，以保持 HTML 和 JavaScript 代碼分離。
|
||||
|
||||
### UI Examples
|
||||
### UI 示例
|
||||
|
||||
Gitea uses some self-made UI elements and customizes others to integrate them better into the general UI approach. When running Gitea in development mode (`RUN_MODE=dev`), a page with some standardized UI examples is available under `http(s)://your-gitea-url:port/devtest`.
|
||||
Gitea 使用一些自製的 UI 元素並自定義其他元素，以更好地將它們集成到整體 UI 方法中。當 Gitea 在開發模式下運行時（`RUN_MODE=dev`），可以在 `http(s)://your-gitea-url:port/devtest` 下訪問一些標準化的 UI 示例頁面。
|
||||
|
||||
Reference in New Issue
Block a user