From 907c3d0c2067aa5e28defe75e36a155ca545b35a Mon Sep 17 00:00:00 2001 From: silverwind Date: Tue, 5 Mar 2024 06:29:32 +0100 Subject: [PATCH] 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 (cherry picked from commit 7e8c1c5ba18e1ac8861f429b825163b8210fd178) Conflicts: docs/content/contributing/guidelines-frontend.zh-cn.md Gitea docs --- .../contributing/guidelines-frontend.en-us.md | 2 +- .../contributing/guidelines-frontend.zh-cn.md | 20 ++++++++++++++++--- templates/admin/emails/list.tmpl | 4 ++-- templates/admin/packages/list.tmpl | 4 ++-- templates/admin/user/list.tmpl | 2 +- templates/base/head_navbar.tmpl | 6 +++--- templates/base/paginate.tmpl | 2 +- templates/repo/commit_page.tmpl | 2 +- templates/repo/diff/box.tmpl | 2 +- templates/repo/diff/options_dropdown.tmpl | 4 ++-- templates/repo/diff/section_split.tmpl | 8 ++++---- templates/repo/diff/section_unified.tmpl | 2 +- templates/repo/diff/whitespace_dropdown.tmpl | 16 +++++++-------- templates/repo/issue/card.tmpl | 2 +- .../issue/labels/labels_selector_field.tmpl | 4 ++-- templates/repo/issue/new_form.tmpl | 2 +- .../repo/issue/view_content/sidebar.tmpl | 6 +++--- templates/repo/settings/branches.tmpl | 2 +- templates/status/500.tmpl | 2 +- web_src/css/helpers.css | 9 --------- web_src/js/features/repo-diff.js | 4 ++-- web_src/js/features/repo-issue.js | 4 ++-- web_src/js/features/repo-legacy.js | 6 +++--- web_src/js/features/user-auth.js | 4 ++-- web_src/js/markup/mermaid.js | 4 ++-- 25 files changed, 64 insertions(+), 59 deletions(-) diff --git a/docs/content/contributing/guidelines-frontend.en-us.md b/docs/content/contributing/guidelines-frontend.en-us.md index edd89e1231..2637780718 100644 --- a/docs/content/contributing/guidelines-frontend.en-us.md +++ b/docs/content/contributing/guidelines-frontend.en-us.md @@ -47,7 +47,7 @@ We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/h 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. Gitea's tailwind-style CSS classes use `gt-` prefix (`gt-relative`), while Gitea's own private framework-level CSS classes use `g-` prefix (`g-modal-confirm`). +12. Prefer using Tailwind CSS which is available via `tw-` prefix, e.g. `tw-relative`. Gitea's helper CSS classes use `gt-` prefix (`gt-df`), 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. ### Accessibility / ARIA diff --git a/docs/content/contributing/guidelines-frontend.zh-cn.md b/docs/content/contributing/guidelines-frontend.zh-cn.md index 66a4d4b4d6..ace0d97f49 100644 --- a/docs/content/contributing/guidelines-frontend.zh-cn.md +++ b/docs/content/contributing/guidelines-frontend.zh-cn.md @@ -34,7 +34,7 @@ HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。 我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。 -## Gitea 特定准则： +## Gitea 特定准则 1. 每个功能（Fomantic-UI/jQuery 模块）应放在单独的文件/目录中。 2. HTML 的 id 和 class 应使用 kebab-case，最好包含2-3个与功能相关的关键词。 @@ -47,7 +47,8 @@ HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。 9. 避免在 CSS 中使用不必要的`!important`，如果无法避免，添加注释解释为什么需要它。 10. 避免在一个事件监听器中混合不同的事件，优先为每个事件使用独立的事件监听器。 11. 推荐使用自定义事件名称前缀`ce-`。 -12. Gitea 的 tailwind-style CSS 类使用`gt-`前缀（`gt-relative`），而 Gitea 自身的私有框架级 CSS 类使用`g-`前缀（`g-modal-confirm`）。 +12. 建议使用 Tailwind CSS，它可以通过 `tw-` 前缀获得，例如 `tw-relative`. Gitea 自身的助手类 CSS 使用 `gt-` 前缀（`gt-df`），Gitea 自身的私有框架级 CSS 类使用 `g-` 前缀（`g-modal-confirm`）。 +13. 尽量避免内联脚本和样式，建议将JS代码放入JS文件中并使用CSS类。如果内联脚本和样式不可避免，请解释无法避免的原因。 ### 可访问性 / ARIA @@ -64,18 +65,21 @@ Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`ari * Vue + Vanilla JS * Fomantic-UI（jQuery） +* htmx （部分页面重新加载其他静态组件） * Vanilla JS 不推荐的实现方式： * Vue + Fomantic-UI（jQuery） * 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 函数 +### `async` 函数 只有当函数内部存在`await`调用或返回`Promise`时，才将函数标记为`async`。 @@ -91,6 +95,12 @@ Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`ari 这是有意为之的，我们想调用异步函数并忽略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`，它的驼峰命名行为使得搜索属性变得困难。 @@ -132,3 +142,7 @@ Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`ari ### Vue3 和 JSX Gitea 现在正在使用 Vue3。我们决定不引入 JSX，以保持 HTML 代码和 JavaScript 代码分离。 + +### UI示例 + +Gitea 使用一些自制的 UI 元素并自定义其他元素，以将它们更好地集成到通用 UI 方法中。当在开发模式（`RUN_MODE=dev`）下运行 Gitea 时，在 `http(s)://your-gitea-url:port/devtest` 下会提供一个包含一些标准化 UI 示例的页面。 diff --git a/templates/admin/emails/list.tmpl b/templates/admin/emails/list.tmpl index bcd80368e6..29fbb5f039 100644 --- a/templates/admin/emails/list.tmpl +++ b/templates/admin/emails/list.tmpl @@ -47,8 +47,8 @@ {{range .Emails}} {{.Name}} - {{.FullName}} - {{.Email}} + {{.FullName}} + {{.Email}} {{if .IsPrimary}}{{svg "octicon-check"}}{{else}}{{svg "octicon-x"}}{{end}} {{if .CanChange}} diff --git a/templates/admin/packages/list.tmpl b/templates/admin/packages/list.tmpl index 1f86803d55..aef4815424 100644 --- a/templates/admin/packages/list.tmpl +++ b/templates/admin/packages/list.tmpl @@ -62,8 +62,8 @@ {{end}} {{.Package.Type.Name}} - {{.Package.Name}} - {{.Version.Version}} + {{.Package.Name}} + {{.Version.Version}} {{.Creator.Name}} {{if .Repository}} diff --git a/templates/admin/user/list.tmpl b/templates/admin/user/list.tmpl index 8fdc80fc70..e9ce17ac90 100644 --- a/templates/admin/user/list.tmpl +++ b/templates/admin/user/list.tmpl @@ -96,7 +96,7 @@ {{ctx.Locale.Tr "admin.users.remote"}} {{end}} - {{.Email}} + {{.Email}} {{if .IsActive}}{{svg "octicon-check"}}{{else}}{{svg "octicon-x"}}{{end}} {{if .IsRestricted}}{{svg "octicon-check"}}{{else}}{{svg "octicon-x"}}{{end}} {{if index $.UsersTwoFaStatus .ID}}{{svg "octicon-check"}}{{else}}{{svg "octicon-x"}}{{end}} diff --git a/templates/base/head_navbar.tmpl b/templates/base/head_navbar.tmpl index 06fc5913d0..e755775985 100644 --- a/templates/base/head_navbar.tmpl +++ b/templates/base/head_navbar.tmpl @@ -14,7 +14,7 @@
{{if .IsSigned}} -
+
{{svg "octicon-bell"}} {{$notificationUnreadCount}}
@@ -76,7 +76,7 @@ {{else if .IsSigned}} {{if EnableTimetracking}} -
+
{{svg "octicon-stopwatch"}}
@@ -112,7 +112,7 @@ {{end}} -
+
{{svg "octicon-bell"}} {{$notificationUnreadCount}}
diff --git a/templates/base/paginate.tmpl b/templates/base/paginate.tmpl index ef7d0b341b..8c2adc1f94 100644 --- a/templates/base/paginate.tmpl +++ b/templates/base/paginate.tmpl @@ -17,7 +17,7 @@ {{if eq .Num -1}} ... {{else}} - {{.Num}} + {{.Num}} {{end}} {{end}} diff --git a/templates/repo/commit_page.tmpl b/templates/repo/commit_page.tmpl index 1d900cdefb..80af73ce48 100644 --- a/templates/repo/commit_page.tmpl +++ b/templates/repo/commit_page.tmpl @@ -17,7 +17,7 @@ {{$class = (print $class " isWarning")}} {{end}} {{end}} -
+

{{RenderCommitMessage $.Context .Commit.Message ($.Repository.ComposeMetas ctx)}}{{template "repo/commit_statuses" dict "Status" .CommitStatus "Statuses" .CommitStatuses}}

{{if not $.PageIsWiki}} diff --git a/templates/repo/diff/box.tmpl b/templates/repo/diff/box.tmpl index 4cfe9034c8..40c163c555 100644 --- a/templates/repo/diff/box.tmpl +++ b/templates/repo/diff/box.tmpl @@ -112,7 +112,7 @@

- {{/* */}}{{end}}{{/* @@ -62,7 +62,7 @@ {{if $match.RightIdx}}{{end}} {{/* */}}{{if and $.root.SignedUserID $.root.PageIsPullFiles}}{{/* - */}}{{/* */}}{{end}}{{/* @@ -79,7 +79,7 @@ {{if $line.LeftIdx}}{{end}} {{/* */}}{{if and $.root.SignedUserID $.root.PageIsPullFiles (not (eq .GetType 2))}}{{/* - */}}{{/* */}}{{end}}{{/* @@ -94,7 +94,7 @@ {{if $line.RightIdx}}{{end}} {{/* */}}{{if and $.root.SignedUserID $.root.PageIsPullFiles (not (eq .GetType 3))}}{{/* - */}}{{/* */}}{{end}}{{/* diff --git a/templates/repo/diff/section_unified.tmpl b/templates/repo/diff/section_unified.tmpl index ae97dc6db6..e3249c26d5 100644 --- a/templates/repo/diff/section_unified.tmpl +++ b/templates/repo/diff/section_unified.tmpl @@ -52,7 +52,7 @@ {{else}} {{/* */}}{{if and $.root.SignedUserID $.root.PageIsPullFiles}}{{/* - */}}{{/* */}}{{end}}{{/* diff --git a/templates/repo/diff/whitespace_dropdown.tmpl b/templates/repo/diff/whitespace_dropdown.tmpl index 7bf2ac9aec..cfabf836d6 100644 --- a/templates/repo/diff/whitespace_dropdown.tmpl +++ b/templates/repo/diff/whitespace_dropdown.tmpl @@ -2,26 +2,26 @@ {{svg "gitea-whitespace"}}
- - - - diff --git a/templates/repo/issue/card.tmpl b/templates/repo/issue/card.tmpl index 5e524079c8..ff635c736a 100644 --- a/templates/repo/issue/card.tmpl +++ b/templates/repo/issue/card.tmpl @@ -7,7 +7,7 @@
{{end}}
-
+
{{template "shared/issueicon" .}}
diff --git a/templates/repo/issue/labels/labels_selector_field.tmpl b/templates/repo/issue/labels/labels_selector_field.tmpl index d24dac46eb..e42a1de895 100644 --- a/templates/repo/issue/labels/labels_selector_field.tmpl +++ b/templates/repo/issue/labels/labels_selector_field.tmpl @@ -21,7 +21,7 @@
{{end}} {{$previousExclusiveScope = $exclusiveScope}} - {{if $exclusiveScope}}{{svg "octicon-dot-fill"}}{{else}}{{svg "octicon-check"}}{{end}}  {{RenderLabel $.Context .}} + {{if $exclusiveScope}}{{svg "octicon-dot-fill"}}{{else}}{{svg "octicon-check"}}{{end}}  {{RenderLabel $.Context .}} {{if .Description}}
{{.Description | RenderEmoji $.Context}}{{end}}

{{template "repo/issue/labels/label_archived" .}}

 @@ -34,7 +34,7 @@
{{end}} {{$previousExclusiveScope = $exclusiveScope}} - {{if $exclusiveScope}}{{svg "octicon-dot-fill"}}{{else}}{{svg "octicon-check"}}{{end}}  {{RenderLabel $.Context .}} + {{if $exclusiveScope}}{{svg "octicon-dot-fill"}}{{else}}{{svg "octicon-check"}}{{end}}  {{RenderLabel $.Context .}} {{if .Description}}
{{.Description | RenderEmoji $.Context}}{{end}}

{{template "repo/issue/labels/label_archived" .}}

 diff --git a/templates/repo/issue/new_form.tmpl b/templates/repo/issue/new_form.tmpl index e67314bfd5..b2b9e308f5 100644 --- a/templates/repo/issue/new_form.tmpl +++ b/templates/repo/issue/new_form.tmpl @@ -156,7 +156,7 @@
{{ctx.Locale.Tr "repo.issues.new.clear_assignees"}}
{{range .Assignees}} - {{svg "octicon-check"}} + {{svg "octicon-check"}} {{ctx.AvatarUtils.Avatar . 28 "gt-mr-3"}}{{template "repo/search_name" .}} diff --git a/templates/repo/issue/view_content/sidebar.tmpl b/templates/repo/issue/view_content/sidebar.tmpl index f5b6751d6d..329a39dd69 100644 --- a/templates/repo/issue/view_content/sidebar.tmpl +++ b/templates/repo/issue/view_content/sidebar.tmpl @@ -20,7 +20,7 @@ {{range .Reviewers}} {{if .User}} - {{svg "octicon-check"}} + {{svg "octicon-check"}} {{ctx.AvatarUtils.Avatar .User 28 "gt-mr-3"}}{{template "repo/search_name" .User}} @@ -35,7 +35,7 @@ {{range .TeamReviewers}} {{if .Team}} - {{svg "octicon-check" 16}} + {{svg "octicon-check" 16}} {{svg "octicon-people" 16 "gt-ml-4 gt-mr-2"}}{{$.Issue.Repo.OwnerName}}/{{.Team.Name}} @@ -231,7 +231,7 @@ {{$checked = true}} {{end}} {{end}} - {{svg "octicon-check"}} + {{svg "octicon-check"}} {{ctx.AvatarUtils.Avatar . 20 "gt-mr-3"}}{{template "repo/search_name" .}} diff --git a/templates/repo/settings/branches.tmpl b/templates/repo/settings/branches.tmpl index f8896b504e..78421ec009 100644 --- a/templates/repo/settings/branches.tmpl +++ b/templates/repo/settings/branches.tmpl @@ -16,7 +16,7 @@ {{.CsrfTokenHtml}} {{if not .Repository.IsEmpty}} -
+
{{svg "octicon-triangle-down" 14 "dropdown icon"}}
{{.Repository.DefaultBranch}}
diff --git a/templates/status/500.tmpl b/templates/status/500.tmpl index fb159ea361..3825d9de4d 100644 --- a/templates/status/500.tmpl +++ b/templates/status/500.tmpl @@ -41,7 +41,7 @@
{{if .ErrorMsg}}

{{ctx.Locale.Tr "error.occurred"}}:

- 
{{.ErrorMsg}}
+ 
{{.ErrorMsg}}
{{end}}
{{if or .SignedUser.IsAdmin .ShowFooterVersion}}

{{ctx.Locale.Tr "admin.config.app_ver"}}: {{AppVer}}

{{end}} diff --git a/web_src/css/helpers.css b/web_src/css/helpers.css index 71f3a619b9..dad0f9b127 100644 --- a/web_src/css/helpers.css +++ b/web_src/css/helpers.css @@ -46,16 +46,7 @@ Gitea's private styles use `g-` prefix. text-overflow: ellipsis; } -.gt-max-width-12rem { max-width: 12rem !important; } -.gt-max-width-24rem { max-width: 24rem !important; } - /* below class names match Tailwind CSS */ -.gt-break-all { word-break: break-all !important; } -.gt-content-center { align-content: center !important; } -.gt-invisible { visibility: hidden !important; } -.gt-items-start { align-items: flex-start !important; } -.gt-pointer-events-none { pointer-events: none !important; } -.gt-relative { position: relative !important; } .gt-object-contain { object-fit: contain !important; } .gt-no-underline { text-decoration-line: none !important; } .gt-normal-case { text-transform: none !important; } diff --git a/web_src/js/features/repo-diff.js b/web_src/js/features/repo-diff.js index 85cb66c728..d1071a3b36 100644 --- a/web_src/js/features/repo-diff.js +++ b/web_src/js/features/repo-diff.js @@ -71,9 +71,9 @@ function initRepoDiffConversationForm() { $form.closest('.conversation-holder').replaceWith($newConversationHolder); if ($form.closest('tr').data('line-type') === 'same') { - $(`[data-path="${path}"] .add-code-comment[data-idx="${idx}"]`).addClass('gt-invisible'); + $(`[data-path="${path}"] .add-code-comment[data-idx="${idx}"]`).addClass('tw-invisible'); } else { - $(`[data-path="${path}"] .add-code-comment[data-side="${side}"][data-idx="${idx}"]`).addClass('gt-invisible'); + $(`[data-path="${path}"] .add-code-comment[data-side="${side}"][data-idx="${idx}"]`).addClass('tw-invisible'); } $newConversationHolder.find('.dropdown').dropdown(); initCompReactionSelector($newConversationHolder); diff --git a/web_src/js/features/repo-issue.js b/web_src/js/features/repo-issue.js index 10faeb135d..6fb13b0dda 100644 --- a/web_src/js/features/repo-issue.js +++ b/web_src/js/features/repo-issue.js @@ -180,9 +180,9 @@ export function initRepoIssueCommentDelete() { const idx = $conversationHolder.data('idx'); const lineType = $conversationHolder.closest('tr').data('line-type'); if (lineType === 'same') { - $(`[data-path="${path}"] .add-code-comment[data-idx="${idx}"]`).removeClass('gt-invisible'); + $(`[data-path="${path}"] .add-code-comment[data-idx="${idx}"]`).removeClass('tw-invisible'); } else { - $(`[data-path="${path}"] .add-code-comment[data-side="${side}"][data-idx="${idx}"]`).removeClass('gt-invisible'); + $(`[data-path="${path}"] .add-code-comment[data-side="${side}"][data-idx="${idx}"]`).removeClass('tw-invisible'); } $conversationHolder.remove(); } diff --git a/web_src/js/features/repo-legacy.js b/web_src/js/features/repo-legacy.js index 10ad836797..8fcc78c177 100644 --- a/web_src/js/features/repo-legacy.js +++ b/web_src/js/features/repo-legacy.js @@ -150,7 +150,7 @@ export function initRepoCommentForm() { if ($(this).hasClass('checked')) { $(this).removeClass('checked'); - $(this).find('.octicon-check').addClass('gt-invisible'); + $(this).find('.octicon-check').addClass('tw-invisible'); if (hasUpdateAction) { if (!($(this).data('id') in items)) { items[$(this).data('id')] = { @@ -164,7 +164,7 @@ export function initRepoCommentForm() { } } else { $(this).addClass('checked'); - $(this).find('.octicon-check').removeClass('gt-invisible'); + $(this).find('.octicon-check').removeClass('tw-invisible'); if (hasUpdateAction) { if (!($(this).data('id') in items)) { items[$(this).data('id')] = { @@ -218,7 +218,7 @@ export function initRepoCommentForm() { $(this).parent().find('.item').each(function () { $(this).removeClass('checked'); - $(this).find('.octicon-check').addClass('gt-invisible'); + $(this).find('.octicon-check').addClass('tw-invisible'); }); if (selector === 'select-reviewers-modify' || selector === 'select-assignees-modify') { diff --git a/web_src/js/features/user-auth.js b/web_src/js/features/user-auth.js index 60d186e699..a871ac471c 100644 --- a/web_src/js/features/user-auth.js +++ b/web_src/js/features/user-auth.js @@ -9,13 +9,13 @@ export function initUserAuthOauth2() { for (const link of outer.querySelectorAll('.oauth-login-link')) { link.addEventListener('click', () => { - inner.classList.add('gt-invisible'); + inner.classList.add('tw-invisible'); outer.classList.add('is-loading'); setTimeout(() => { // recover previous content to let user try again // usually redirection will be performed before this action outer.classList.remove('is-loading'); - inner.classList.remove('gt-invisible'); + inner.classList.remove('tw-invisible'); }, 5000); }); } diff --git a/web_src/js/markup/mermaid.js b/web_src/js/markup/mermaid.js index 84d88a94c3..82e9909fec 100644 --- a/web_src/js/markup/mermaid.js +++ b/web_src/js/markup/mermaid.js @@ -45,7 +45,7 @@ export async function renderMermaid() { const {svg} = await mermaid.render('mermaid', source); const iframe = document.createElement('iframe'); - iframe.classList.add('markup-render', 'gt-invisible'); + iframe.classList.add('markup-render', 'tw-invisible'); iframe.srcdoc = `${svg}`; const mermaidBlock = document.createElement('div'); @@ -62,7 +62,7 @@ export async function renderMermaid() { iframe.style.height = `${iframe.contentWindow.document.body.clientHeight}px`; setTimeout(() => { // avoid flash of iframe background mermaidBlock.classList.remove('is-loading'); - iframe.classList.remove('gt-invisible'); + iframe.classList.remove('tw-invisible'); }, 0); });