openeuler-frontend-tools

openEuler Portal frontend development tools

This skill provides a complete guide to all common development tools in the openEuler Portal project, including Vue Composables, SCSS Mixins, and utility functions.

Tool categories

1. Composables (composition functions)

Located in the openEuler-portal/app/.vitepress/src-new/composables/ directory, providing reusable Vue 3 Composition API features:

• useScreen - Responsive screen size detection and adaptation
• useLocale - Internationalization language switching
• useClipboard - Clipboard operations
• useDebounceSearch - Debounced search
• useCheckbox - Checkbox state management
• useScrollBottom - Scroll-to-bottom detection
• useInViewDuration - Element visibility duration tracking

For detailed usage, refer to Composables reference documentation

2. SCSS Mixins (style mixins)

Located in the openEuler-portal/app/.vitepress/src-new/assets/style/mixin/ directory, providing responsive styles and common style mixins:

• screen.scss - Responsive breakpoint mixin
• font.scss - Responsive font size mixin (display1-3, h1-h4, text1-2, tip1-2)
• common.scss - Common style mixins (dark mode, text truncation, scrollbar, hover effects, etc.)

For detailed usage, refer to Mixins reference documentation

3. Utils (utility functions)

Located in the openEuler-portal/app/.vitepress/src-new/utils/ directory, providing common utility functions:

• common.ts - URL parameters, Cookies, time formatting, Git platform detection, etc.
• locale.ts - Locale retrieval

For detailed usage, refer to Utils reference documentation

Quick start

Using a Composable

<script setup lang="ts">
import { useScreen } from '~@/composables/useScreen';
import { useLocale } from '~@/composables/useLocale';

const { isPhone, isPad, isLaptop, current } = useScreen();
const { t, locale, isZh, changeLocale } = useLocale();
</script>

Using an SCSS Mixin

<style lang="scss" scoped>
@use '~@/assets/style/mixin/font.scss' as *;
@use '~@/assets/style/mixin/screen.scss' as *;

.title {
  @include h1; // 使用响应式标题样式
}

.content {
  @include text1; // 使用响应式正文样式
  
  @include respond-to('phone') {
    padding: 16px;
  }
}
</style>

Using utility functions

import { getUrlParam, setCookie, changeTimeStamp } from '~@/utils/common';
import { getCurrentLocale } from '~@/utils/locale';

// 获取 URL 参数
const id = getUrlParam('id');

// 设置 Cookie
setCookie('theme', 'dark', 7);

// 时间戳格式化
const date = changeTimeStamp(Date.now());

// 获取当前语言
const lang = getCurrentLocale();

Usage scenarios

Scenario 1: Responsive page development

When you need to adjust layout or styles according to screen size:

1. Use the useScreen composable to get screen size state
2. Use the @include respond-to() mixin to write responsive styles
3. Use the mixin in font.scss to ensure responsive font adaptation

Scenario 2: Internationalization features

When you need to implement multi-language switching:

1. Use the useLocale composable for language switching
2. Use getCurrentLocale to get the current locale
3. Use the t() function in templates for text translation

Scenario 3: Forms and interactive features

When you need to implement forms, search, clipboard, and other features:

1. Use useCheckbox to manage checkbox state
2. Use useDebounceSearch to implement debounced search
3. Use useClipboard to implement copy functionality

Scenario 4: Style development

When you need to apply the project's standard styles:

1. Use the font mixin in font.scss to ensure font sizes comply with the specification
2. Use the common mixins in common.scss (text truncation, scrollbar styles, etc.)
3. Use the responsive breakpoints in screen.scss responsive breakpoints in

Reference resources

• Composables Complete Reference - Detailed usage of all composables
• Mixins Complete Reference - Detailed usage of all SCSS mixins
• Utils Complete Reference - Detailed usage of all utility functions

Notes

1. Path alias: the project uses ~@/ as the alias for the src-new directory; new projects usually use @/, and import paths should be adjusted accordingly
2. Responsive breakpoints: screen breakpoints are defined in screen.scss and kept consistent with the useScreen composable
3. Font specifications: use the mixin in font.scss to ensure font sizes conform to the design specifications
4. Type safety: all composables and utils provide complete TypeScript type definitions

Configuring the SCSS Mixin file in a new project

The SCSS mixin file is not distributed with the npm package and must be created manually in the project. Refer to the Mixins Reference documentation to create a file with the same name at the following path:

src/assets/style/mixin/
├── screen.scss   ← 响应式断点（respond-to mixin）
├── font.scss     ← 响应式字体（h1~h4, text1-2, tip1-2, display1-3 mixin）
└── common.scss   ← 通用样式（in-dark, text-truncate, scrollbar, hover mixin）

Breakpoint values(consistent with the opendesign token system):

Breakpoint name	Range
phone	0–600px
pad_v	601–840px
pad_h	841–1200px
laptop	1201–1440px
Desktop (no mixin)	>1440px (default styles)

vite.config.ts configuration(globally auto-injected, all SCSS files require no manual @use）：

css: {
  preprocessorOptions: {
    scss: {
      additionalData: `
@use "@/assets/style/mixin/screen.scss" as *;
@use "@/assets/style/mixin/font.scss" as *;
@use "@/assets/style/mixin/common.scss" as *;
`,
    },
  },
},

⚠️ After configuration, it is forbidden to manually .vue file or .scss file manually @use the above mixin file, otherwise a "cannot use module twice" error will be reported.

⚠️ screen.scss map values must be wrapped in quotes(strings), otherwise SCSS parses the parentheses as a list, causing a compilation error:

// ✅ 正确
$breakpoints: (
  '<=pad_v': '(max-width: 840px)',
  'laptop':  '(min-width: 1201px) and (max-width: 1440px)',
);

// ❌ 错误（括号被解析为 SCSS list）
$breakpoints: (
  '<=pad_v': (max-width: 840px),
);