date: “2023-05-25T16:00:00+02:00” title: “前端开发指南” slug: “guidelines-frontend” sidebar_position: 20 toc: false draft: false aliases:
Gitea 在其前端中使用Fomantic-UI(基于jQuery)和 Vue3。
HTML 页面由Go HTML Template渲染。
源文件可以在以下目录中找到:
web_src/css/
web_src/js/
web_src/js/components/
templates/
我们推荐使用Google HTML/CSS Style Guide和Google JavaScript Style Guide。
js-
前缀。helpers.less
中。ctx.PageData["myModuleData"] = map[]{}
将复杂数据传递给前端,但不要将整个模型暴露给前端,以避免泄露敏感数据。elem.disabled = true
而不是elem.setAttribute('disabled', 'anything')
,优先使用$el.prop('checked', var === 'yes')
而不是$el.prop('checked', var)
。<button class="ui button">
而不是<div class="ui button">
。!important
,如果无法避免,添加注释解释为什么需要它。ce-
。tw-
前缀获得,例如 tw-relative
. Gitea 自身的助手类 CSS 使用 gt-
前缀(gt-word-break
),Gitea 自身的私有框架级 CSS 类使用 g-
前缀(g-modal-confirm
)。在历史上,Gitea大量使用了可访问性不友好的框架 Fomantic UI。
Gitea 使用一些补丁使 Fomantic UI 更具可访问性(参见 aria.md
),
但仍然存在许多问题需要大量的工作和时间来修复。
不建议混合使用不同的框架,这会使代码难以维护。 一个 JavaScript 模块应遵循一个主要框架,并遵循该框架的最佳实践。
推荐的实现方式:
不推荐的实现方式:
hx-on
)为了保持界面一致,Vue 组件可以使用 Fomantic-UI 的 CSS 类。 尽管不建议混合使用不同的框架, 我们使用 htmx 进行简单的交互。您可以在此 PR 中查看一个简单交互的示例,其中应使用 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。
禁止使用dataset
,它的驼峰命名行为使得搜索属性变得困难。
然而,仍然存在一些特殊情况,因此当前的准则是:
对于旧代码:
$.data()
重构为$.attr()
。$.data()
将一些非字符串数据绑定到元素上,但强烈不推荐使用。对于新代码:
node.dataset
,而应使用node.getAttribute
。v-if
和v-show
来显示/隐藏元素。.tw-hidden
和 showElem()/hideElem()/toggleElem()
来显示/隐藏元素,请参阅.tw-hidden
的注释以获取更多详细信息。建议使用以下方式:
<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>
以使代码更易读。
许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
Gitea 现在正在使用 Vue3。我们决定不引入 JSX,以保持 HTML 代码和 JavaScript 代码分离。
Gitea 使用一些自制的 UI 元素并自定义其他元素,以将它们更好地集成到通用 UI 方法中。当在开发模式(RUN_MODE=dev
)下运行 Gitea 时,在 http(s)://your-gitea-url:port/devtest
下会提供一个包含一些标准化 UI 示例的页面。