Project Code Name ｢Cerasus（Plantation）｣

KIRAKIRA's Front-end

Star History

Architecture Diagram

flowchart TD
    %% Core Application
    NuxtApp["Nuxt Application"]:::frontend

    %% Presentation Layer
    subgraph "Presentation Layer"
        Pages["Pages & Routing"]:::presentation
        UIComponents["UI Components"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        ComposablesStores["Composables & Stores"]:::business
        Modules["Modules"]:::business
        PluginsProviders["Plugins & Providers"]:::business
    end

    %% Utilities & Internationalization
    subgraph "Utilities & Internationalization"
        AssetsStyling["Assets & Styling"]:::utilities
        Internationalization["Internationalization"]:::utilities
    end

    %% Server & Environment Setup
    subgraph "Server & Environment Setup"
        ServerEnv["Server & Config Files"]:::server
    end

    %% External Systems
    subgraph "External Systems"
        Backend["KIRAKIRA-Rosales Backend"]:::external
        CloudflareImages["Cloudflare Images"]:::external
        CloudflareStream["Cloudflare Stream"]:::external
    end

    %% Connections between layers
    NuxtApp -->|"routing"| Pages
    NuxtApp -->|"render"| UIComponents
    Modules -->|"affects"| NuxtApp
    PluginsProviders -->|"middleware"| NuxtApp
    ComposablesStores -->|"fetch_API"| Backend
    PluginsProviders -->|"integrates"| CloudflareImages
    PluginsProviders -->|"integrates"| CloudflareStream
    UIComponents -->|"directive_binding"| PluginsProviders
    AssetsStyling -->|"styles"| UIComponents
    Internationalization -->|"translations"| UIComponents
    ComposablesStores -->|"state_sync"| UIComponents
    Modules -->|"extends"| PluginsProviders
    ServerEnv -->|"configures"| NuxtApp

    %% Class definitions with colors
    classDef frontend fill:#f9c,stroke:#333,stroke-width:2px;
    classDef presentation fill:#bbf,stroke:#333,stroke-width:2px;
    classDef business fill:#bfb,stroke:#333,stroke-width:2px;
    classDef utilities fill:#ffb,stroke:#333,stroke-width:2px;
    classDef server fill:#fbb,stroke:#333,stroke-width:2px;
    classDef external fill:#bef,stroke:#333,stroke-width:2px;

    %% Click Events
    click NuxtApp "https://github.com/kirakira-douga/kirakira-cerasus/blob/develop/nuxt.config.ts"
    click NuxtApp "https://github.com/kirakira-douga/kirakira-cerasus/blob/develop/app.vue"
    click Pages "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/pages"
    click UIComponents "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/components"
    click Modules "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/modules"
    click ComposablesStores "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/composables"
    click ComposablesStores "https://github.com/kirakira-douga/kirakira-cerasus/blob/develop/stores/app-settings.ts"
    click AssetsStyling "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/assets"
    click AssetsStyling "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/helpers"
    click AssetsStyling "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/utils"
    click PluginsProviders "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/plugins"
    click PluginsProviders "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/providers/nuxt-image"
    click Internationalization "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/locales"
    click ServerEnv "https://github.com/kirakira-douga/kirakira-cerasus/tree/develop/server"
    click ServerEnv "https://github.com/kirakira-douga/kirakira-cerasus/blob/develop/tsconfig.json"
    click ServerEnv "https://github.com/kirakira-douga/kirakira-cerasus/blob/develop/.npmrc"
    click ServerEnv "https://github.com/kirakira-douga/kirakira-cerasus/blob/develop/pnpm-lock.yaml"

To learn more, read the wiki!

Nuxt

Turn to the Nuxt documentation to learn more.

Setup

Make sure to install the dependencies:

To clone this repository, you can use the following command, or other Git compatible tools.

git clone https://github.com/KIRAKIRA-DOUGA/KIRAKIRA-Cerasus.git

After cloning is complete, execute the following command in the program root directory to install the dependent packages.

# npm
pnpm install

Development Server

KIRAKIRA Cerasus supports multiple modes of development servers, please choose the method you need and start.
You can use shortcut commands to start commonly used development modes, or you can customize the startup command according to your preferences.

Important

Some features require HTTPS to work properly. KIRAKRIA Cerasus uses the self-signed certificate in this path by default. When you visit development server for the first time, the browser will pop up a "This site is not secure" warning. Just select "Visit anyway".
If your local port 3000 is already occupied by other applications or devices, the development server will automatically adjust the port number to 3001, and so on. Please be sure to carefully observe the correct URL output by the console.

Running with local backend

Start a development server with HTTPS support and use the local backend API.

The development server started this way connects to your local backend API. The data you generate is managed by you and is related to KIRAKIRA Developer Team.
You need to run the backend service KIRAKIRA-Rosales separately, otherwise the program will not work as expected.

Press Ctrl + Shift + B on your keyboard and select npm: dev local.

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

pnpm dev-local

Warning

Although you connect to the local backend, you will still request image asset files from the official staging environment Cloudflare Images service, and use the official staging environment Cloudflare Stream subdomain template when uploading videos. If you want to use your own Cloudflare Images and Cloudflare Stream services, please refer to the "Custom startup command" section below.

Warning

For developers with access to the production environment, you can also use the pnpm run dev-local-prod command to connect to the production environment Cloudflare Images and Cloudflare Stream services.

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

Running with online backend

You can run the front-end development server locally and use Nuxt's devProxy to connect to the staging online back-end API, and perform proxying and cookie domain rewriting without starting the back-end service locally.
KIRAKIRA has two online backends: staging environment and production environment. The staging environment contains test data and functions under development, and the production environment is the kirakira.moe official website you visit.

Anyway, read the usage restrictions below:

Warning

Restrictions on the use of the staging environment online backend mode:

In the staging environment online backend mode, any testing or tampering by anyone other than the development team members will still be considered abuse.
The data generated by the user in the staging environment is authorized for use by the KIRAKIRA development team and cannot be revoked.
KIRAKIRA is not responsible for any personal or property losses caused by the use of the staging environment.

Note

Currently, the online backend mode will directly use the address localhost:3000 to connect. If your local port number is not 3000, please refer to the custom startup command below to modify it yourself.

The command to start the staging environment mode is:

pnpm dev-stg

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

Custom startup command

Sometimes, the preset quick start command does not meet your needs. In this case, you can start the server through the original start command and use your customized parameters.

A typical custom startup command looks like:

# The following command is equivalent to 'pnpm dev-local'
pnpm cross-env VITE_BACKEND_URI=https://localhost:9999 VITE_CLOUDFLARE_IMAGES_PROVIDER=cloudflare-stg VITE_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN=https://customer-o9xrvgnj5fidyfm4.cloudflarestream.com/ nuxi dev --host --https --ssl-cert server/server.cer --ssl-key server/server.key

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

Parsing of the above command:

cross-env
Set cross-platform environment variables to ensure that the command can be executed normally under different operating systems (such as Windows and Linux).
VITE_BACKEND_URI=https://localhost:9999
Injects an environment variable named VITE_BACKEND_URI with the value https://localhost:9999, which is the URI of the backend API.
VITE_CLOUDFLARE_IMAGES_PROVIDER=cloudflare-stg
Injects an environment variable named VITE_CLOUDFLARE_IMAGES_PROVIDER with the value cloudflare-stg.
This indicates that you are using the NuxtImage Custom Provider named cloudflare-stg.
To modify the configuration of the NuxtImage Custom Provider, go to the image.providers section in file nuxt.config.ts in the root directory.
VITE_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN=https://custom...stream.com/
Inject an environment variable named VITE_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN with a value of https://custom...stream.com/.
This environment variable specifies the custom subdomain of the Cloudflare Stream service.
nuxi dev
Start Nuxt development server. Optional parameters can refer to this official document.
--host
No parameters are specified after --host, indicating that the development server listens to all hosts. For details, please refer to the "Mobile Webpage Testing & Preview" section below
--https --ssl-cert server/server.cer --ssl-key server/server.key
Among them, --https indicates that HTTPS is enabled. --ssl-cert XXX.cer --ssl-key YYY.key specifies the path of the certificate.

Mobile Webpage Testing & Preview

When starting the development server, make sure that one of the following is true: do not specify the --host parameter, do not give the --host parameter a value, or set the --host parameter's value to 0.0.0.0.

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 in Windows: 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
Fleet
Emacs
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Project Code Name ｢Cerasus（Plantation）｣

Star History

Architecture Diagram

Nuxt

Setup

Development Server

Running with local backend

Running with online backend

Custom startup command

Mobile Webpage Testing & Preview

Production

Generate the Application for Production:

Build the Application for Production

Locally Preview Production Build

其它脚本功能

检查 StyleLint

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

压缩 SVG

自定义指令（语法糖）

水波纹

依次动画优先级

工具提示

Localization

组件根节点

触摸屏禁用 `:hover` 伪类

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

与样式相关的组件 Prop

IDE

Technologies used

Test in Browser

Formats Specifications (Lint)

Contributors

FilesExpand file tree

README_en-US.md

Latest commit

History

README_en-US.md

File metadata and controls

Project Code Name ｢Cerasus（Plantation）｣

Star History

Architecture Diagram

Nuxt

Setup

Development Server

Running with local backend

Running with online backend

Custom startup command

Mobile Webpage Testing & Preview

Production

Generate the Application for Production:

Build the Application for Production

Locally Preview Production Build

其它脚本功能

检查 StyleLint

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

压缩 SVG

自定义指令（语法糖）

水波纹

依次动画优先级

工具提示

Localization

组件根节点

触摸屏禁用 :hover 伪类

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

与样式相关的组件 Prop

IDE

Technologies used

Test in Browser

Formats Specifications (Lint)

Contributors

触摸屏禁用 `:hover` 伪类