mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-20 04:58:52 +00:00
docs: add zh-tw folder (#195)
Signed-off-by: appleboy <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/195 Reviewed-by: Lunny Xiao <[email protected]> Co-authored-by: appleboy <[email protected]> Co-committed-by: appleboy <[email protected]>
This commit is contained in:
appleboy
Lunny Xiao
+35
-26
@@ -6,7 +6,6 @@ sidebar_position: 20
|
||||
|
||||
aliases:
|
||||
- /zh-cn/guidelines-frontend
|
||||
|
||||
---
|
||||
|
||||
# 前端开发指南
|
||||
@@ -19,10 +18,10 @@ 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/`
|
||||
- **CSS 样式**： `web_src/css/`
|
||||
- **JavaScript 文件**： `web_src/js/`
|
||||
- **Vue 组件**： `web_src/js/components/`
|
||||
- **Go HTML 模板**： `templates/`
|
||||
|
||||
## 通用准则
|
||||
|
||||
@@ -31,9 +30,9 @@ HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
|
||||
## 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` 中。
|
||||
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)`。
|
||||
@@ -45,8 +44,8 @@ HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
|
||||
|
||||
### 可访问性 / ARIA
|
||||
|
||||
在历史上，Gitea大量使用了可访问性不友好的框架 Fomantic UI。
|
||||
Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`aria.md`），
|
||||
在历史上，Gitea 大量使用了可访问性不友好的框架 Fomantic UI。
|
||||
Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见`aria.js`和`aria.md`），
|
||||
但仍然存在许多问题需要大量的工作和时间来修复。
|
||||
|
||||
### 框架使用
|
||||
@@ -56,14 +55,14 @@ Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`ari
|
||||
|
||||
推荐的实现方式：
|
||||
|
||||
* Vue + Vanilla JS
|
||||
* Fomantic-UI（jQuery）
|
||||
* Vanilla JS
|
||||
- Vue + Vanilla JS
|
||||
- Fomantic-UI（jQuery）
|
||||
- Vanilla JS
|
||||
|
||||
不推荐的实现方式：
|
||||
|
||||
* Vue + Fomantic-UI（jQuery）
|
||||
* jQuery + Vanilla JS
|
||||
- Vue + Fomantic-UI（jQuery）
|
||||
- jQuery + Vanilla JS
|
||||
|
||||
为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
|
||||
尽管不建议混合使用不同的框架，
|
||||
@@ -82,7 +81,7 @@ Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`ari
|
||||
|
||||
如果我们想在非异步上下文中调用`async`函数，
|
||||
建议使用`const _promise = asyncFoo()`来告诉读者
|
||||
这是有意为之的，我们想调用异步函数并忽略Promise。
|
||||
这是有意为之的，我们想调用异步函数并忽略 Promise。
|
||||
一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
|
||||
|
||||
### HTML 属性和 dataset
|
||||
@@ -90,31 +89,41 @@ Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`ari
|
||||
禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
|
||||
然而，仍然存在一些特殊情况，因此当前的准则是：
|
||||
|
||||
* 对于旧代码：
|
||||
* 应将`$.data()`重构为`$.attr()`。
|
||||
* 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
|
||||
- 对于旧代码：
|
||||
|
||||
* 对于新代码：
|
||||
* 不应使用`node.dataset`，而应使用`node.getAttribute`。
|
||||
* 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
|
||||
- 应将`$.data()`重构为`$.attr()`。
|
||||
- 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
|
||||
|
||||
- 对于新代码：
|
||||
- 不应使用`node.dataset`，而应使用`node.getAttribute`。
|
||||
- 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
|
||||
|
||||
### 显示/隐藏元素
|
||||
|
||||
* 推荐在Vue组件中使用`v-if`和`v-show`来显示/隐藏元素。
|
||||
* Go 模板代码应使用 Gitea 的 `.gt-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.gt-hidden`的注释以获取更多详细信息。
|
||||
- 推荐在 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>
|
||||
<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>
|
||||
<div
|
||||
class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
|
||||
{{if
|
||||
.IsFoo}}
|
||||
data-foo{{end}}
|
||||
></div>
|
||||
```
|
||||
|
||||
以使代码更易读。
|
||||
|
||||
Reference in New Issue
Block a user