项目代号 ｢Cerasus（第13都市）｣

KIRAKIRA 的前端

简体中文 | English

点击此处前往 Figma 设计文稿 >

标星历史

Nuxt 3

首先，Nuxt 读作 /nʌkst/（

查看 Nuxt 3 文档以了解更多信息。

安装

确保安装依赖项：

# pnpm
pnpm install

开发服务器

KIRAKIRA Cerasus 支持多种模式的开发服务器，请选择您需要的方式启动。

HTTPS 模式（默认）

启动一个带有 HTTPS 支持的开发服务器，并使用线上后端 API。

在 Visual Studio Code 中，按下 Ctrl + Shift + B，然后选择 npm: dev 来启动。

或者，按下 F5 键即可启动，如需停止服务器可以按下 Shift + F5。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev

启动后，您应该能够在这个地址访问：https://localhost:3000/

以上方式会开启 HTTPS，以便浏览器提供 HTTPS 特有的功能及安全性。

在首次访问时会弹出“此站点不安全”的警告，这是正常现象，选择“仍然访问”即可。

Warning

如果您的端口号 3000 已被其它应用程序或设备等占用了，此时会自动调整为端口号 3001，以此类推。请务必仔细观察开发服务器控制台声明的正确网址。

Important

通过此方式启动的开发服务器，连接的是线上的后端 API。您仍然在与线上环境交互。
这和通过我们的官方网站或 APP 使用 KIRAKIRA 服务没有区别，在这种情况下 KIRAKIRA 用户协议及免责条款仍然适用。

HTTPS 本地后端模式

启动一个带有 HTTPS 支持的开发服务器，并使用本地后端 API。

请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev local。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev-local

启动后，您应该能够在这个地址访问：https://localhost:3000/

以上方式会开启 HTTPS，以便浏览器提供 HTTPS 特有的功能及安全性。

在首次访问时会弹出“此站点不安全”的警告，这是正常现象，选择“仍然访问”即可。

Important

通过此方式启动的开发服务器，连接的是本地的后端 API。您与您本地的环境交互，数据将由您本地运行的后端程序管理，与 KIRAKIRA 无关。
您需要额外运行 KIRAKIRA-Rosales 后端服务，否则程序将不会如期工作。

HTTP 模式

尝试使用 HTTP 开发服务器，并使用线上后端 API。

请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev http。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev-http

启动后，您应该能够在这个地址访问：http://localhost:3000/

Warning

HTTP 开发服务器模式已经过测试，它一定不包含您预期中的某些功能。使用该模式运行开发服务器导致的任何后果对您没有任何好处。除非您已知晓您确实要使用该模式的意义所在之外，如无必要，任何情况下均不应使用该模式。

HTTP 本地后端模式

尝试使用 HTTP 开发服务器，并连接本地后端 API。

请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev http local。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev-http-local

启动后，您应该能够在这个地址访问：http://localhost:3000/

Warning

警告同 HTTP 模式。

在移动端网页测试和预览

请先使用以上几种模式开启前端开发服务器，您不应使用带有 localhost 字段的模式来启动。

确保手机/平板与您的电脑位于同一个无线局域网下（如果条件不允许请开热点），然后使用您移动设备中的二维码扫描器扫描控制台中显示的二维码即可访问。

您也可以使用移动端浏览器访问电脑所属 IP 地址。一般是：https://192.168.*.*:3000/ 。这会在启动开发服务器时的一开始将网址显示在控制台上。

Note

查询电脑 IP 的方法：按 Win + R，输入 cmd 打开命令提示符，输入 ipconfig 即可查询当前电脑的 IP 地址。

HTTPS 仅本地访问模式

启动一个带有 HTTPS 支持的开发服务器，并使用线上后端 API。该模式仅限开发服务器本机使用，同局域网下其它设备无法访问。用以解决某些不可名状的 SSR 错误。

请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev localhost。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev-localhost

启动后，您应该能够在这个地址访问：https://localhost:3000/

以上方式会开启 HTTPS，以便浏览器提供 HTTPS 特有的功能及安全性。

在首次访问时会弹出“此站点不安全”的警告，这是正常现象，选择“仍然访问”即可。

HTTPS 仅本地访问、本地后端模式

启动一个带有 HTTPS 支持的开发服务器，并连接本地后端 API。该模式仅限开发服务器本机使用，同局域网下其它设备无法访问。用以解决某些不可名状的 SSR 错误。

请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev local localhost。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev-local-localhost

启动后，您应该能够在这个地址访问：https://localhost:3000/

以上方式会开启 HTTPS，以便浏览器提供 HTTPS 特有的功能及安全性。

在首次访问时会弹出“此站点不安全”的警告，这是正常现象，选择“仍然访问”即可。

HTTP 仅本地访问模式

尝试使用 HTTP 开发服务器，并使用线上后端 API。该模式仅限开发服务器本机使用，同局域网下其它设备无法访问。用以解决某些不可名状的 SSR 错误。

请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev http localhost。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev-http-localhost

启动后，您应该能够在这个地址访问：http://localhost:3000/

Warning

警告同 HTTP 模式。

HTTP 仅本地访问、本地后端模式

尝试使用 HTTP 开发服务器，并连接本地后端 API。该模式仅限开发服务器本机使用，同局域网下其它设备无法访问。用以解决某些不可名状的 SSR 错误。

请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev http local localhost。

您也可以在程序根目录中执行以下命令来启动：

pnpm dev-http-local-localhost

启动后，您应该能够在这个地址访问：http://localhost:3000/

Warning

警告同 HTTP 模式。

生产

为生产生成应用程序

这将会完整地生成每一个静态路由页面。

按下键盘按键 Ctrl + Shift + B，然后选择 npm: generate。

pnpm generate

为生产构建应用程序

这只会构建最小的根路由页面。

按下键盘按键 Ctrl + Shift + B，然后选择 npm: build。

pnpm build

本地预览生产版本

pnpm preview

Important

以生产模式运行时，连接的后端服务接口是：https://rosales.kirakira.moe/
此时您将与线上环境交互。
这和通过我们的官方网站或 APP 使用 KIRAKIRA 服务没有区别，在这种情况下 KIRAKIRA 用户协议及免责条款仍然适用。

有关更多详细信息，请参阅部署文档。

其它脚本功能

依次选择菜单 终端(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, // 工具提示与元素之间的距离
}">

本地化

如果您想要为本项目的本地化提供建议，请发布一个议题来通知我们；如果您想要为本项目贡献本地化，请发布一个拉取请求。非常感谢！
Please post an Issue to let us know you would like to provide some localization suggestions to this project; Please post an Pull Request 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 {

    }
}

Note

除了 @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

建议使用以下任意平台进行开发：

不要使用

• Atom
• Dreamweaver
• SharePoint
• FrontPage
• Notepad++
• HBuilder
• HBuilderX
• Vim
• 记事本
• 写字板
• Word

使用技术

前端开发中所使用了的技术栈有：

测试用浏览器

格式规范

• 缩进：TAB
• 行尾：LF
• 引号：双引号
• 文件末尾加空行
• 语句末尾加分号
• Vue API 风格：组合式