KIRAKIRA 的前端
简体中文 | English
flowchart TD
%% 核心应用
NuxtApp["Nuxt 应用"]:::frontend
%% 表现层
subgraph "表现层"
Pages["页面和路由"]:::presentation
UIComponents["界面组件"]:::presentation
end
%% 业务逻辑层
subgraph "业务逻辑层"
ComposablesStores["组合式函数和状态库"]:::business
Modules["模块"]:::business
PluginsProviders["插件和供给"]:::business
end
%% 工具类函数和国际化
subgraph "工具类函数和国际化"
AssetsStyling["资产和样式"]:::utilities
Internationalization["国际化"]:::utilities
end
%% 服务器和环境设置
subgraph "服务器和环境设置"
ServerEnv["服务器和配置文件"]:::server
end
%% 外部系统
subgraph "外部系统"
Backend["KIRAKIRA-Rosales 后端"]:::external
CloudflareImages["Cloudflare 图片"]:::external
CloudflareStream["Cloudflare 流媒体"]:::external
end
%% Connections between layers
NuxtApp -->|"路由"| Pages
NuxtApp -->|"渲染"| UIComponents
Modules -->|"影响"| NuxtApp
PluginsProviders -->|"中间件"| NuxtApp
ComposablesStores -->|"获取接口"| Backend
PluginsProviders -->|"整合"| CloudflareImages
PluginsProviders -->|"整合"| CloudflareStream
UIComponents -->|"指令绑定"| PluginsProviders
AssetsStyling -->|"妆饰"| UIComponents
Internationalization -->|"翻译"| UIComponents
ComposablesStores -->|"状态同步"| UIComponents
Modules -->|"扩展"| PluginsProviders
ServerEnv -->|"配置"| 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"
想了解更多？阅读 Wiki！
首先，Nuxt 读作 /nʌkst/（
查看 Nuxt 文档以了解更多信息。
克隆本存储库，您可以使用如下命令，或其他 Git 兼容工具。
git clone https://github.com/KIRAKIRA-DOUGA/KIRAKIRA-Cerasus.git
完成克隆后，在程序根目录执行以下命令安装依赖包。
pnpm installKIRAKIRA Cerasus 的开发服务器具有多种模式供您选择。
您可以使用快捷命令启动常用的开发模式，也可以根据偏好自定义启动命令。
Important
- 部分功能需要启用 HTTPS 方可正常工作，KIRAKRIA Cerasus 默认使用该路径中的自签名证书。在首次访问时浏览器会弹出“此站点不安全”警告，这是正常现象，选择“仍然访问”即可。
- 如果您本地的 3000 端口已被其它应用程序或设备占用，开发服务器会自动将端口号调整为 3001，以此类推。请务必仔细观察控制台输出的正确网址。
启动一个带有 HTTPS 支持的开发服务器，并使用本地后端 API。
通过此方式启动的开发服务器，连接的是您本地的后端 API。您产生的数据由您自行管理，与 KIRAKIRA 无关。
您需要额外运行 KIRAKIRA-Rosales 后端服务，否则程序将不会如期工作。
请按下键盘按键 Ctrl + Shift + B，然后选择 npm: dev local。
您也可以在程序根目录中执行以下命令来启动：
pnpm dev-localWarning
虽然您连接了本地后端，但仍会向官方提供的预生产环境 Cloudflare Images 服务请求图片资源文件，并在视频上传时使用官方预生产环境的 Cloudflare Stream 子域名模板。如果您想要使用您自己的 Cloudflare Images 和 Cloudflare Stream 服务，请参考下方的“自定义启动命令”章节。
Warning
对于有生产环境访问权限的开发者，您也可以使用 pnpm run dev-local-prod 命令来连接生产环境的 Cloudflare Images 和 Cloudflare Stream 服务。
启动后，您应该能够在这个地址访问：https://localhost:3000/
您可以在本地启动前端开发服务器，并使用 Nuxt 的 devProxy 连接预生产环境的线上后端 API，并进行代理和对 Cookie 域名进行重写，无需在本地启动后端服务。
KIRAKIRA 拥有预生产环境和生产环境两个线上后端，预生产环境包含测试数据和正在开发中的功能，而生产环境就是您访问的 kirakira.moe 官网。
无论如何，请务必阅读下方使用限制：
Warning
对于预生产环境线上后端模式的使用限制：
- 预生产环境线上后端模式，除开发团队成员外，任何测试、篡改行为仍将被视为滥用。
- 用户在预生产环境中产生的数据皆授权 KIRAKIRA 开发团队使用，不得撤销。
- 用户因使用预生产环境造成的任何人身及财产损失与 KIRAKIRA 无关。
Note
目前在线后端模式会直接使用 localhost:3000 的地址去连接，如果你的本地端口号不是 3000，请参考下方的自定义启动命令来自行修改。
启动预生产环境线上后端模式的命令为：
pnpm dev-stg启动后，您应该能够在这个地址访问：https://localhost:3000/
很多时候，预设的快速启动命令并不能满足您的需求。此时，您可以通过原始启动命令来启动服务器，并使用您的自定义参数。
一个典型的自定义启动命令看起来像：
# 以下命令等价于 '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启动后，您应该能够在这个地址访问：https://localhost:3000/
上述命令的解析：
cross-env
设置跨平台的环境变量，确保命令在不同操作系统（如 Windows 和 Linux）下都能正常执行。VITE_BACKEND_URI=https://localhost:9999
注入一个名为VITE_BACKEND_URI的环境变量，其值为https://localhost:9999，即后端 API 的 URI。VITE_CLOUDFLARE_IMAGES_PROVIDER=cloudflare-stg
注入一个名为VITE_CLOUDFLARE_IMAGES_PROVIDER的环境变量，其值为cloudflare-stg。
这代表您使用名为cloudflare-stg的 NuxtImage Custom Provider。
如需修改 NuxtImage Custom Provider 的配置，请前往根目录中的nuxt.config.ts中image.providers部分。VITE_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN=https://custom...stream.com/
注入一个名为VITE_CLOUDFLARE_STREAM_CUSTOMER_SUBDOMAIN的环境变量，其值为https://custom...stream.com/。
该环境变量指定了 Cloudflare Stream 服务的自定义子域名。nuxi dev
启动 Nuxt 的开发服务器。可选参数可以参考这篇官方文档。--host
在--host后没有指定参数，表示开发服务器监听所有主机。详情请参见下方”在移动端网页测试和预览“章节--https --ssl-cert server/server.cer --ssl-key server/server.key
其中，--https表明启动 HTTPS。--ssl-cert XXX.cer --ssl-key YYY.key指定了证书的路径。
在启动开发服务器时，请确保以下任意一种情况成立：未指定 --host 参数，未为 --host 参数赋值，或将 --host 参数的值设置为 0.0.0.0。
确保手机/平板与您的电脑位于同一个局域网下（如果条件不允许请开热点），然后使用您移动设备中的二维码扫描器扫描控制台中显示的二维码即可访问。
您也可以使用移动端浏览器访问开发服务器主机的 IP 地址，例如：https://192.168.*.*:3000/ 。通常该地址会在启动开发服务器后显示在控制台输出中。
Note
Windows 主机查询 IP 的方法：按 Win + R，输入 cmd 打开命令提示符，输入 ipconfig 即可查询当前电脑的 IP 地址。
这将会完整地生成每一个静态路由页面。
按下键盘按键 Ctrl + Shift + B，然后选择 npm: generate。
pnpm generate这只会构建最小的根路由页面。
按下键盘按键 Ctrl + Shift + B，然后选择 npm: build。
pnpm buildpnpm previewImportant
以生产模式运行时，连接的后端服务接口是：https://rosales.kirakira.moe/
此时您将与线上环境交互。
这和通过我们的官方网站或 APP 使用 KIRAKIRA 服务没有区别，在这种情况下 KIRAKIRA 用户协议及免责条款仍然适用。
有关更多详细信息，请参阅部署文档。
依次选择菜单 终端(T) > 运行任务...，然后即可访问其它脚本功能。
npm: lint:css这将会根据 _eases.scss 文件的更改自动更新 eases.module.scss、eases.module.scss.d.ts 额外两个文件。
npm: update-eases这将会压缩 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 伪类所表示的样式。然而触摸屏通过手指操作，并不存在“悬停”功能，而浏览器为了实现所谓的“悬停”功能，当触摸按钮时，浏览器会将一个无形的指针放置在该按钮上，以呈现“悬停”样式状态。当手指离开屏幕时，指针并不会消失，按钮仍然呈现为悬停样式。这会使用户觉得奇怪，用户必须点击其它空白处才能使该按钮的悬停样式消失。这并不是我们所期望的。
请在项目中使用 :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?]
- 对象写法：
以 <SoftButton> 组件为例，你可能会很好奇，该组件在 Prop 里居然不能自定义按钮大小，难道按钮的大小只能是固定的吗？
并不是，<LogoCover> 组件也是一样的，不能在 Prop 中设定封面的大小。
正确方法是在样式表中，使用以下方式（自定义属性）进行设置：
.soft-button {
--wrapper-size: 40px;
}这样就能完美应用样式了。
除此之外，它也可以支持布尔或枚举类型。
.logo-text {
--form: full;
}
.tab-bar {
--clipped: true;
}毕竟设定样式，在 CSS/SCSS 中批量设定不比在 HTML/template 中单独设定要更好么？
建议使用以下任意平台进行开发：
不要使用
- Atom
- Dreamweaver
- SharePoint
- FrontPage
- Notepad++
- HBuilder
- HBuilderX
- Fleet
- Emacs
- Vim
- 记事本
- 写字板
- Word
前端开发中所使用了的技术栈有：
- 缩进：TAB
- 行尾：LF
- 引号：双引号
- 文件末尾加空行
- 语句末尾加分号
- Vue API 风格：组合式