forgejo/docs/content/contributing/guidelines-frontend.zh-cn.md
silverwind 907c3d0c20
Replace more gt- with tw-, update frontend docs (#29595)
Tested a few things, all working fine. Not sure if the chinese machine
translation is good.

---------

Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
(cherry picked from commit 7e8c1c5ba18e1ac8861f429b825163b8210fd178)

Conflicts:
	docs/content/contributing/guidelines-frontend.zh-cn.md
	Gitea docs
2024-03-11 23:36:58 +07:00

149 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
date: "2023-05-25T16:00:00+02:00"
title: "前端开发指南"
slug: "guidelines-frontend"
sidebar_position: 20
toc: false
draft: false
aliases:
- /zh-cn/guidelines-frontend
menu:
sidebar:
parent: "contributing"
name: "前端开发指南"
sidebar_position: 20
identifier: "guidelines-frontend"
---
# 前端开发指南
## 背景
Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)(基于[jQuery](https://api.jquery.com))和 [Vue3](https://vuejs.org/)。
HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
源文件可以在以下目录中找到:
* **CSS 样式** `web_src/css/`
* **JavaScript 文件** `web_src/js/`
* **Vue 组件** `web_src/js/components/`
* **Go HTML 模板** `templates/`
## 通用准则
我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
## Gitea 特定准则
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 中的帮助 CSS 类在 `helpers.less` 中。
5. 后端可以通过使用`ctx.PageData["myModuleData"] = map[]{}`将复杂数据传递给前端,但不要将整个模型暴露给前端,以避免泄露敏感数据。
6. 简单页面和与 SEO 相关的页面使用 Go HTML 模板渲染生成静态的 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 使用 `gt-` 前缀(`gt-df`Gitea 自身的私有框架级 CSS 类使用 `g-` 前缀(`g-modal-confirm`)。
13. 尽量避免内联脚本和样式建议将JS代码放入JS文件中并使用CSS类。如果内联脚本和样式不可避免请解释无法避免的原因。
### 可访问性 / ARIA
在历史上Gitea大量使用了可访问性不友好的框架 Fomantic UI。
Gitea使用一些补丁使Fomantic UI更具可访问性参见`aria.js`和`aria.md`
但仍然存在许多问题需要大量的工作和时间来修复。
### 框架使用
不建议混合使用不同的框架,这会使代码难以维护。
一个 JavaScript 模块应遵循一个主要框架,并遵循该框架的最佳实践。
推荐的实现方式:
* Vue + Vanilla JS
* Fomantic-UIjQuery
* htmx (部分页面重新加载其他静态组件)
* Vanilla JS
不推荐的实现方式:
* Vue + Fomantic-UIjQuery
* jQuery + Vanilla JS
* htmx + 任何其他需要大量 JavaScript 代码或不必要的功能,如 htmx 脚本 (`hx-on`)
为了保持界面一致Vue 组件可以使用 Fomantic-UI 的 CSS 类。
尽管不建议混合使用不同的框架,
我们使用 htmx 进行简单的交互。您可以在此 [PR](https://github.com/go-gitea/gitea/pull/28908) 中查看一个简单交互的示例,其中应使用 htmx。如果您需要更高级的反应性请不要使用 htmx请使用其他框架Vue/Vanilla JS
但如果混合使用是必要的,并且代码设计良好且易于维护,也可以工作。
### `async` 函数
只有当函数内部存在`await`调用或返回`Promise`时,才将函数标记为`async`。
不建议使用`async`事件监听器,这可能会导致问题。
原因是`await`后的代码在事件分发之外执行。
参考https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
如果一个事件监听器必须是`async`,应在任何`await`之前使用`e.preventDefault()`
建议将其放在函数的开头。
如果我们想在非异步上下文中调用`async`函数,
建议使用`const _promise = asyncFoo()`来告诉读者
这是有意为之的我们想调用异步函数并忽略Promise。
一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
### 获取数据
要获取数据,请使用`modules/fetch.js`中的包装函数`GET`、`POST`等。他们
接受内容的`data`选项,将自动设置 CSRF 令牌并返回
[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)。
### HTML 属性和 dataset
禁止使用`dataset`,它的驼峰命名行为使得搜索属性变得困难。
然而,仍然存在一些特殊情况,因此当前的准则是:
* 对于旧代码:
* 应将`$.data()`重构为`$.attr()`。
* 在极少数情况下,可以使用`$.data()`将一些非字符串数据绑定到元素上,但强烈不推荐使用。
* 对于新代码:
* 不应使用`node.dataset`,而应使用`node.getAttribute`。
* 不要将任何用户数据绑定到 DOM 节点上,使用合适的设计模式描述节点和数据之间的关系。
### 显示/隐藏元素
* 推荐在Vue组件中使用`v-if`和`v-show`来显示/隐藏元素。
* Go 模板代码应使用 Gitea 的 `.gt-hidden``showElem()/hideElem()/toggleElem()` 来显示/隐藏元素,请参阅`.gt-hidden`的注释以获取更多详细信息。
### Go HTML 模板中的样式和属性
建议使用以下方式:
```html
<div class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}" {{if .IsFoo}}data-foo{{end}}></div>
```
而不是:
```html
<div class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"{{if .IsFoo}} data-foo{{end}}></div>
```
以使代码更易读。
### 旧代码
许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
### Vue3 和 JSX
Gitea 现在正在使用 Vue3。我们决定不引入 JSX以保持 HTML 代码和 JavaScript 代码分离。
### UI示例
Gitea 使用一些自制的 UI 元素并自定义其他元素,以将它们更好地集成到通用 UI 方法中。当在开发模式(`RUN_MODE=dev`)下运行 Gitea 时,在 `http(s)://your-gitea-url:port/devtest` 下会提供一个包含一些标准化 UI 示例的页面。