README_en-US.md

Project Code Name ｢Cerasus（Plantation）｣

Front-end

简体中文 | English

Click here to go to the Figma design file >

Star History

Nuxt 3

Firstly, Nuxt is pronounced as /nʌkst/ *lol*

Look at the Nuxt 3 documentation to learn more.

Setup

Make sure to install the dependencies:

# npm
npm install

Only NPM allowed!!!

Development Server

KIRAKIRA Cerasus supports multiple modes of development servers, please choose the method you need and start.

HTTPS Development Mode (Default)

Start a development server with HTTPS and use the Product back-end API.

Press F5 in Visual Studio Code, and you can stop the server by press Shift + F5.
Or press Ctrl + Shift + B, and then select npm: dev.

You can also run the following command in the root directory to start:

npm run dev

After it started, you should be able to preview at this URL: https://localhost:3000/

The above ways will enable HTTPS so that the browser can provide HTTPS-specific functions and security.
When you visit for the first time, you can see a warning "This site is not secure". Well, Just click "Visit Anyway".

Important

The development server started in this way is connected to the product back-end API. You are still online.
This is no different from using KIRAKIRA services through our official website or APPs, in which case the KIRAKIRA User Agreement or ToS remains in effect.

HTTPS Localhost Development Mode

Start a development server with HTTPS and use the Local back-end API.

Run the following command in the root directory to start:

npm run dev-localhost

After it started, you should be able to preview at this URL: https://localhost:3000/

It will enable HTTPS so that the browser can provide HTTPS-specific functions and security.
When you visit for the first time, you can see a warning "This site is not secure". Well, Just click "Visit Anyway".

Important

The development server started in this way connects to the local back-end API. You interact with your local environment and the data will be managed by your locally running back-end program, independent of KIRAKIRA.
You need to run the KIRAKIRA-Rosales backend service additionally, otherwise the program will not work as expected.

HTTP Localhost Development Mode

Try to start a development server only with HTTP and use the Local back-end API.

Press the keyboard keys Ctrl + Shift + B, and then select npm: dev http.

You can also run the following command in the root directory to start:

npm run dev-http

After it started, you should be able to preview at this URL: http://localhost:3000/

Warning

This mode has not been tested in any way!
The HTTP development server may not contain the expected functionality. Any consequences of running a development server in this mode are at your own risk.

Mobile Webpage Testing & Preview

Ensure that the phone/tablet is located on the same WiFi as your computer (if conditions do not allow, turn on the mobile hotspot), and then use the mobile browser to access the IP address of the computer. Generally: https://192.168.*.*:3000/

Note

How to query the computer IP: Press Win + R, enter cmd to open a command prompt, and enter ipconfig to query the current IP address of the computer.

Production

Generate the Application for Production:

This will completely generate each static routing page.

Press the keyboard keys Ctrl + Shift + B, and then select npm: generate.

npm run generate

Build the Application for Production

This will only build the minimal root routing page.

Press the keyboard keys Ctrl + Shift + B, and then select npm: build.

npm run build

Locally Preview Production Build

npm run preview

Important

When running in production mode, we connect to the back-end API at: https://rosales.kirakira.moe/
You are online.
This is no different from using KIRAKIRA services through our official website or APPs, in which case the KIRAKIRA User Agreement or ToS remains in effect.

Checkout the deployment documentation for more information.

其它脚本功能

依次选择菜单 终端(T) > 运行任务...，然后即可访问其它脚本功能。

检查 StyleLint

npm: lint:css

更新缓动值样式 (_eases.scss) 声明文件

这将会根据 _eases.scss 文件的更改自动更新 eases.module.scss、eases.module.scss.d.ts 额外两个文件。

npm: update-eases

压缩 SVG

这将会压缩 SVG，删除 SVG 的多余部分，如裁切区域、填充颜色等。

Compact SVG

自定义指令（语法糖）

项目利用各种特性、冷知识、甚至修改底层代码等，添加了许多语法糖以方便开发人员使用。

水波纹

使用 v-ripple 自定义指令快速创建 Material 水波纹效果。其接受一个布尔类型的值，用于表示是否开启水波纹。如果留空则自动表示开启。

<!-- 直接开启 -->
<div v-ripple>
<!-- 显式开启 -->
<div v-ripple="true">
<!-- 根据 foo 变量的值而开启 -->
<div v-ripple="foo">

依次动画优先级

如果你希望实现各条目依次出现的动画（具体动画仍需自行手动实现），请使用 v-i 自定义指令。其接受一个数字类型的值，用于表示其优先级。其以 0 起始或以 1 起始具体表现根据你的动画实现而决定。

<div v-i="1">

这将会转变成如下效果：

• Vue SFC 语法

  <div :style="{ '--i': 1 }">

• JSX 语法

  <div style={{ '--i': 1 }}>

• HTML 语法

  <div style="--i: 1;">

工具提示

使用 v-tooltip 创建自定义的工具提示，旨在取代原生丑陋的 title 属性。

<!-- 自动决定工具提示的位置方向 -->
<div v-tooltip="'那只敏捷的棕毛狐狸跳过了一只懒惰的狗'">
<!-- 显式指定工具提示的位置方向 -->
<div v-tooltip:top="'那只敏捷的棕毛狐狸跳过了一只懒惰的狗'">
<!-- 高级设定工具提示 -->
<div v-tooltip="{
    title: '那只敏捷的棕毛狐狸跳过了一只懒惰的狗', // 工具提示文本
    placement: 'top', // 指定四个位置方向
    offset: 10, // 工具提示与元素之间的距离
}">

Localization

Please post an Issue to let us know you would like to contribute localization to this project, thank you.

Important

注意：翻译字典文件的每个标识符均应使用蛇形命名法（下划线命名法）；且多门语言若任意一门语言比其它语言多或少字符串声明，均会报错，这意味着必须为这些语言同时指定完整的字符串声明，以防遗漏。

项目强化了 Vue-i18n 的原生翻译函数，使其使用起来更方便。

功能	当前强化语法	原版语法
直接声明	t.welcome	$t("welcome")
变量声明	t[variable]	$t(variable)
位置参数	t.welcome("hello", "world")	$t("welcome", ["hello", "world"])
命名参数	t.welcome({ foo: "hello", bar: "world" })	$t("welcome", { foo: "hello", bar: "world" })
复数	t(2).car	$tc("car", 2)

组件根节点

为使各组件的元素界限更清晰明显，且避免样式泄露等麻烦问题。请在项目中使用 <Comp> 作为组件的根节点。

假设组件名为 TextBox.vue：

<Comp />

这将会自动编译为：

<kira-component class="text-box"></kira-component>

同时，在样式表中，可以使用 :comp 来更方便地指代组件的根节点。

:comp {

}

这将会自动编译为：

kira-component.text-box {

}

此外，在其它地方调用该组件时，亦可根据组件的名称而为该组件设定样式，而不必再额外添加多余的类名。

触摸屏禁用 :hover 伪类

众所周知鼠标才有悬停功能，将鼠标指针悬浮在按钮上，按钮就会响应为 :hover 伪类所表示的样式。然而触摸屏通过手指操作，并不存在“悬停”功能，而浏览器为了实现所谓的“悬停”功能，当触摸按钮时，浏览器会将一个无形的指针放置在该按钮上，以呈现“悬停”样式状态。当手指离开屏幕时，指针并不会消失，按钮仍然呈现为悬停样式。这会使用户觉得奇怪，用户必须点击其它空白处才能使该按钮的悬停样式消失。这并不是我们所期望的。

请在项目中使用 :any-hover 伪类替换掉原本的 :hover 伪类，这将会使用户通过鼠标指针进行操作时才会出现悬停样式，而触摸屏则不会触发悬停样式。此外由于触摸屏没有 :hover 样式，请务必设定 :active 样式以为触摸屏用户带来更好的体验。

button:any-hover {

}

这将会自动编译为：

@media (any-hover: hover) {
    button:hover {

    }
}

除了 @media (any-hover: hover) 规则之外，还有一个 @media (hover: hover) 规则。它们的区别是：hover 只检测主要输入设备是否支持悬停功能，而 any-hover 检测是否至少一个输入设备支持悬停功能。

菜单、浮窗等的双向绑定模型参数

• 通过向菜单组件的 v-model 传递鼠标/指针事件 MouseEvent / PointerEvent 来在对应位置显示菜单，传递 null 则表示显示占位菜单而非上下文菜单，传递 undefined 表示隐藏菜单。

• 通过向浮窗组件的 v-model 传递一个元组（推荐）或对象均可表示显示浮窗，传递 undefined 表示隐藏浮窗。

  • 对象写法：

    {
        target: MouseEvent | PointerEvent; // 鼠标/指针事件
        placement?: "top" | "bottom" | ...; // 指定四个位置方向
        offset?: number; // 工具提示与元素之间的距离
    }

  • 元组写法

    [target, placement?, offset?]

与样式相关的组件 Prop

以 <SoftButton> 组件为例，你可能会很好奇，该组件在 Prop 里居然不能自定义按钮大小，难道按钮的大小只能是固定的吗？

并不是，<LogoCover> 组件也是一样的，不能在 Prop 中设定封面的大小。

正确方法是在样式表中，使用以下方式（自定义属性）进行设置：

.soft-button {
    --wrapper-size: 40px;
}

这样就能完美应用样式了。

除此之外，它也可以支持布尔或枚举类型。

.logo-text {
    --form: full;
}

.tab-bar {
    --clipped: true;
}

毕竟设定样式，在 CSS/SCSS 中批量设定不比在 HTML/template 中单独设定要更好么？

IDE

It is recommended to use any of the following platforms for development:

Never use

• Atom
• Dreamweaver
• SharePoint
• FrontPage
• Notepad++
• HBuilder
• HBuilderX
• Vim
• Notepad
• Wordpad
• Word

Technologies used

The technology stacks used in front-end development include:

Test in Browser

Formats Specifications (Lint)

• Indent: TAB
• Line feed: LF
• Quotes: Double quotation marks
• Add blank lines at the end of the file
• Add a semicolon at the end of the statement
• Vue API Style: Composition API