@quicktvui/ai 1.0.0

package/rules/.docs/zh-CN/guide/layout/adapter.md

@@ -0,0 +1,33 @@
+---
+title: 'Adapter'
+lang: zh-CN
+---
+
+# 适配
+
+## 开发尺寸
+
+::: warning 注意： 实际中根据 1920x1080 的开发尺寸进行设计、布局。
+:::
+
+框架本身会自动拉伸适配其他电视屏幕尺寸。
+
+## 长度单位
+
+::: warning 注意： 仅使用 px 来设定单位。暂不支持百分比等其它的长度值，只支持具体数值。
+:::
+
+例如：
+
+```css
+#div {
+  margin-left: 10px;
+  width: 100px;
+  height: 60px;
+}
+```
+
+``` vue
+<div style="{width: '100px',height:'60px'}">
+</div>
+```

package/rules/.docs/zh-CN/guide/layout/layout.md

@@ -0,0 +1,42 @@
+---
+title: 'Layout'
+lang: zh-CN
+---
+
+# 布局
+
+* [点击查看支持的布局](/zh-CN/css/overview)
+* [点击查看布局样式相关问题](/zh-CN/guide/faq/layout-style-faq)
+
+::: warning 注意：
+* ***布局中基础组件都需要明确指定组件的宽高尺寸***
+
+* ***仅使用 px 来设定单位。暂不支持百分比等其它的长度值，只支持具体数值。***
+:::
+
+## 盒子模型
+
+布局样式用`CSS`的盒模型构建。 绘制布局的时，引擎会根据 `CSS-Box` 模型将所有元素表示为一个矩形盒子，样式配置决定这些盒子的`大小`，`位置`以及`属性` （颜色，背景，边框尺寸...)。
+使用标准盒模型描述这些矩形盒子中的每一个元素。
+这个模型描述了元素所占空间的内容。每个盒子有四个边：`外边距边`, `边框边`, `内填充边` 与 `内容边`。
+
+[box-sizing参考文档](https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-sizing)
+
+
+<img src="/guide/layout/border-box.png">
+
+## 布局（Flex）
+
+默认采用现在移动端最流行的 `Flex` 布局。
+因为仅支持 `Flex` 布局，所以不需要手写 `display: flex` 即可使用。
+`Flex` 布局与 `Web` 的 `Flex` 类似，它们都旨在提供一个更加有效的方式制定、调整和分布一个容器里的项目布局，即使他们的大小是未知或者是动态的。
+`Flex` 规定了弹性元素如何伸长或缩短，以适应`flex容器`中的可用空间。
+
+[CSS教程文档参考](https://www.w3cplus.com/css3/a-visual-guide-to-css3-flexbox-properties.html)
+
+::: warning 注意：
+
+***1、默认使用 flex 布局***
+
+***2、flex 布局中`flex-direction`默认值为`column`***
+:::

package/rules/.docs/zh-CN/guide/layout/style.md

@@ -0,0 +1,64 @@
+---
+title: 'Style'
+lang: zh-CN
+---
+
+# 样式
+
+* [点击查看支持的样式](/zh-CN/css/overview)
+* [点击查看布局样式相关问题](/zh-CN/guide/faq/layout-style-faq)
+
+::: warning 注意：
+* ***布局中基础组件都需要明确指定组件的宽高尺寸***
+
+* ***仅使用 px 来设定单位。暂不支持百分比等其它的长度值，只支持具体数值。***
+  :::
+
+## 样式主要依靠 css、sass、less 样式来实现。
+
+::: warning 注意：目前仅支持基本的 ID、Class、Tag 选择器，而且可以支持基本的嵌套关系，其余选择器和 scoped 还未支持。
+:::
+
+```vue
+
+<div class="div" />
+```
+
+```css
+
+.div {
+  width: 100px;
+  height: 100px;
+  background-color: red;
+}
+```
+
+## 只支持部分CSS样式
+
+::: warning 注意：
+
+***1、不支持的 CSS 样式如下：***
+* `background`
+* `% 百分比尺寸`
+* `auto`
+* `!important`
+
+***2、不支持 CSS 自定义属性（变量）：***
+
+```css
+element {
+  background-color: var(--main-bg-color);
+}
+```
+
+***3、不支持 CSS 复合属性写法：***
+
+```css
+element {
+  margin: 5px 10px 20px 15px;
+  padding: 5px 10px;
+  font: oblique bold 16px Helvetica, Arial, Sans-Serif;
+  border: 2px 5px 10px 3px;
+}
+```
+:::

package/rules/.docs/zh-CN/guide/layout/theming.md

@@ -0,0 +1,154 @@
+---
+title: 'Theming'
+lang: zh-CN
+---
+
+# 自定义主题
+
+QuickTVUI 默认提供一套主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。 但是如果需要大规模替换样式，例如： 将主题颜色从蓝色改为橙色或绿色，也许一个个将其覆盖起来不是一个好主意。
+
+我们提供通过 SCSS 变量的方法来改变样式变量。
+
+`theme-chalk` 使用SCSS编写而成。
+你可以在 [`packages/theme-chalk/src/common/var.scss`](https://github.com/quicktvui/quicktvui/blob/dev/packages/theme-chalk/src/common/var.scss)
+文件中查找SCSS变量。
+
+:::warning
+
+我们使用 sass 模块 ([sass:map](https://sass-lang.com/documentation/values/maps)...) 和 `@use` 来重构所有的 SCSS 变量。 通过对所有 SCSS
+变量使用 `@use` ，解决了由 `@import` 造成的重复输出问题。
+
+> [介绍 Sass 模块 | CSS-TRICKS](https://css-tricks.com/introducing-sass-modules/)
+
+例如，我们使用 `$colors` 作为 map 来保存不同类型的颜色。
+
+今后，我们将为每个组件自定义的变量编写文档。
+你也可以直接查看源代码 [var.scss](https://github.com/element-plus/element-plus/blob/dev/packages/theme-chalk/src/common/var.scss)
+
+:::
+
+```scss
+$colors: () !default;
+$colors: map.deep-merge(
+    (
+      'white': #ffffff,
+      'black': #000000,
+      'primary': (
+        'base': #409eff,
+      ),
+      'success': (
+        'base': #67c23a,
+      ),
+      'warning': (
+        'base': #e6a23c,
+      ),
+      'danger': (
+        'base': #f56c6c,
+      ),
+      'error': (
+        'base': #f56c6c,
+      ),
+      'info': (
+        'base': #909399,
+      ),
+    ),
+    $colors
+);
+```
+
+### 如何覆盖它？
+
+如果您的项目也使用了 SCSS，可以直接修改 QuickTVUI 的样式变量。 新建一个样式文件，例如
+`./src/styles/quicktvui/index.scss`:
+
+:::warning
+
+您应该使用 `@use 'xxx.scss' as *;` 代替 `@import 'xxx.scss';`.
+
+因为 sass 团队说他们最终会删除 `@import` 语法。
+
+> [Sass: @use](https://sass-lang.com/documentation/at-rules/use) vs [Sass: @import](https://sass-lang.com/documentation/at-rules/import)
+
+:::
+
+```scss
+// styles/quicktvui/index.scss
+/* 只需要重写你需要的即可 */
+@forward 'quicktvui/theme-chalk/src/common/var.scss' with (
+    $bg-color: (
+      'normal': gold,
+      'focus': red,
+      'select': #ffffff,
+    ),
+);
+
+// 如果只是按需导入，则可以忽略以下内容。
+// 如果你想导入所有样式:
+// @use "quicktvui/theme-chalk/src/index.scss" as *;
+```
+
+然后在你的项目入口文件中，导入这个样式文件以替换 QuickTVUI 内置的 CSS：
+
+:::tip
+
+在 `quicktvui scss` 文件之前导入 quicktvui/index.scss 以避免 sass 混合变量的问题，因为我们需要通过你的自定义变量生成 light-x。
+
+:::
+
+创建一个 `quicktvui/index.scss`文件来合并你的变量和 quicktvui 的变量。 （如果你在 TypeScript 中导入了它们，他们将不会被合并）
+
+:::tip
+
+除此以外，你应该将你的 scss 文件与 quicktvui 变量的 scss 文件区分开来。 如果将它们混合在一起，`QuickTVUI` 每次热更新都需要编译大量的 scss 文件，这将会导致编译速度变慢。
+
+:::
+
+```ts
+import { createApp } from 'vue'
+import './src/styles/quicktvui/index.scss'
+import QuickTVUI from 'quicktvui'
+import App from './App.vue'
+
+const app: ESApp = createESApp(App, router)
+app.use(QuickTVUI)
+```
+
+如果您正在使用 webpack，并且需要在按需导入时自定义主题。
+
+```ts
+// webpack.config.ts
+// use unplugin-quicktvui
+
+import QuickTVUI from 'unplugin-quicktvui/webpack'
+
+export default defineConfig({
+  css: {
+    loaderOptions: {
+      scss: {
+        additionalData: `@use "~/styles/quicktvui/index.scss" as *;`,
+      },
+    },
+  },
+  plugins: [
+    QuickTVUI({
+      useSource: true,
+    }),
+  ],
+  module: {
+    rules: [
+      {
+        test: /\.(sc|c)ss$/,
+        use: [
+          cssLoader,
+          {
+            loader: 'sass-loader',
+            options: {
+              additionalData: `@use "./src/styles/quicktvui/index.scss" as *;`,
+            }
+          }
+        ]
+      },
+    ]
+  },
+})
+```

package/rules/.docs/zh-CN/guide/migration.md

@@ -0,0 +1,25 @@
+---
+title: Migration
+lang: zh-CN
+---
+
+# Migration
+
+[This guide](https://github.com/element-plus/element-plus/discussions/5658) will help you upgrade from Element 2.x to QuickTVUI.
+
+## Vue 3 migration build
+
+You may encounter some issues when using QuickTVUI with Vue 3 migration build. Some of the components rely on Vue 3 internal API's. It's worth trying to adjust compatConfig mode to 3, either globally or [per component in your project](https://v3-migration.vuejs.org/migration-build.html).
+
+## Migration Tool :hammer_and_wrench:
+
+We have made a migration tool for you to migrate your project from [Element UI](https://element.eleme.io) to QuickTVUI.
+You can find the [gogo code migration tool](https://github.com/thx/gogocode/tree/main/packages/gogocode-plugin-element) here.
+
+We have tested this on [Vue Element Admin](https://github.com/PanJiaChen/vue-element-admin) (Vue 2 + Element UI). You can find the transpiled code [here](https://github.com/gogocodeio/vue-element-admin).
+
+<style scoped>
+  details {
+    margin-top: 8px;
+  }
+</style>

package/rules/.docs/zh-CN/guide/namespace.md

@@ -0,0 +1,69 @@
+---
+title: Custom Namespace
+lang: zh-CN
+---
+
+## Custom namespace ^(2.2.0)
+
+:::tip
+
+We provide a example in [element-plus-vite-starter](https://github.com/element-plus/element-plus-vite-starter).
+Just check it.
+
+:::
+
+Default namespace is `el`.
+In special cases, we may need to customize its namespace.
+
+Since we use sass to write styles, if you want to customize all namespaces.
+We have to assume that you already use sass.
+
+You must set `ElConfigProvider` and scss `$namespace` at the same time.
+
+### Set `ElConfigProvider`
+
+Use `ElConfigProvider` wrap your root component.
+
+```vue
+<!-- App.vue -->
+<template>
+  <el-config-provider namespace="ep">
+    <!-- ... -->
+  </el-config-provider>
+</template>
+```
+
+### Set Scss & Css Vars
+
+Create `styles/element/index.scss`:
+
+```scss
+// styles/element/index.scss
+// we can add this to custom namespace, default is 'el'
+@forward 'element-plus/theme-chalk/src/mixins/config.scss' with (
+  $namespace: 'ep'
+);
+// ...
+```
+
+Import `styles/element/index.scss` in `vite.config.ts`:
+
+> The same is true for webpack, which needs to be set in `preprocessorOptions`.
+
+```ts
+import { defineConfig } from 'vite'
+// https://vitejs.dev/config/
+export default defineConfig({
+  // ...
+  css: {
+    preprocessorOptions: {
+      scss: {
+        additionalData: `@use "~/styles/element/index.scss" as *;`,
+      },
+    },
+  },
+  // ...
+})
+```
+
+That's all.

package/rules/.docs/zh-CN/guide/nav.md

@@ -0,0 +1,73 @@
+---
+title: Navigation
+lang: zh-CN
+---
+
+<style>
+:root {
+  --categories-c-bg: #F9FAFC;
+  --categories-c-page: #E5E9F2;
+  --categories-c-overlay: white;
+  --categories-c-text: #99A9BF;
+  --categories-c-icon: #E5E9F2;
+  --categories-c-line: #E5E9F2;
+}
+
+.dark {
+  --categories-c-bg: #1D1E1F;
+  --categories-c-page: #0A0A0A;
+  --categories-c-overlay: #141414;
+  --categories-c-text: #53637A;
+  --categories-c-icon: #2F333D;
+  --categories-c-line: #242529;
+}
+</style>
+
+# Navigation
+
+Navigation focuses on solving the users' problems of where to go and how to get
+there. Generally it can be categorized into 'sidebar navigation' and 'top navigation'.
+
+## Choose the right navigation
+
+An appropriate navigation gives users a smooth experience, while an inappropriate
+one leads to confusion. Here are the differences between sidebar navigation and
+top navigation
+
+## Side Navigation
+
+Affix the navigation at the left edge, thus improves its visibility, making it
+easier to switch between pages. In this case, the top area of the page holds
+commonly used tools, e.g. search bar, help button, notice button, etc. Suitable
+for background management or utility websites.
+
+### Level 1 categories
+
+Suitable for simply structured sites with only one level of pages. No breadcrumb is needed.
+
+<L1Categories />
+
+### Level 2 categories
+
+Sidebar displays up to two levels of navigation. Breadcrumbs are recommended in
+combination of second level navigation, making it easier for the users to locate
+and navigate.
+
+<L2Categories />
+
+### Level 3 categories
+
+Suitable for complicated utility websites. The left sidebar holds first level
+navigation, and the middle column displays second level navigation or other utility
+options.
+
+<L3Categories />
+
+## Top Navigation
+
+Conforms to the normal browsing order from top to bottom, which makes things more
+natural. The navigation amount and text length are limited to the width of the top.
+
+Suitable for sites with few navigation and large chunks.
+
+<TopNavigationExample />

package/rules/.docs/zh-CN/guide/network/axios.md

@@ -0,0 +1,47 @@
+---
+title: 'Fetch'
+lang: zh-CN
+---
+
+# Axios
+
+QuickTVUI 使用的是兼容官方`1.7.9`版本的 [`Axios`](https://axios-http.com)。
+
+::: warning 注意：
+
+* ***兼容官方`1.7.9`版本的 API，[`点击查看 Axios API`](https://axios-http.com/docs/api_intro)***
+* ***不支持`XMLHttpRequest`***
+* ***不支持使用`node`的`http` `https`库***
+:::
+
+## 集成
+
+### 第一步、`package.json`添加依赖库
+
+* `@extscreen/es3-axios`![NPM Version](https://img.shields.io/npm/v/@extscreen/es3-axios)
+
+### 第二步、引入`Axios`
+
+```ts
+import axios, {AxiosError} from '@extscreen/es3-axios';
+```
+
+## 示例
+
+````ts
+
+axios({
+        method: 'get',
+        url: 'https://quicktvui.com',
+      })
+        .then((response) => {
+          console.log(response);
+        })
+        .catch((error) => {
+          // handle error
+          console.log(error);
+        }).finally(() => {
+        // always executed
+      });
+
+````

package/rules/.docs/zh-CN/guide/network/fetch.md

@@ -0,0 +1,70 @@
+---
+title: 'Fetch'
+lang: zh-CN
+---
+
+# Fetch
+
+提供了跟 W3C 标准基本一致的 [fetch](https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API)
+方法，可以直接参考 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API)。
+
+::: warning 注意：
+* ***fetch 目前仅支持 JSON 对象的传输，别的格式暂时无法支持。***
+:::
+
+## 发起请求
+
+如果需要请求远程地址，只需要在 fetch 函数参数值传入地址即可，如下：
+
+```js
+fetch('//mywebsite.com/mydata.json');
+```
+
+fetch 函数也支持 HTTP 请求的配置。
+
+```js
+fetch('//mywebsite.com/endpoint/', {
+  method: 'POST',
+  headers: {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    firstParam: 'yourValue',
+    secondParam: 'yourOtherValue',
+  }),
+});
+```
+
+完整的 fetch 请求属性列表可以[点击此处查看](https://developer.mozilla.org/zh-CN/docs/Web/API/Request)。
+
+## 处理返回值
+
+返回数据将以 [Promise](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise) 的形式返回，示例如下：
+
+```js
+function getMoviesFromApi() {
+  return fetch('//mywebsite.com/demo.json')
+    .then(rsp => rsp.json())
+    .then(json => json.movies)
+    .catch(error => console.error(error));
+}
+```
+
+可以使用 [async/await](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/async_function) 处理 fetch
+返回的数据。
+
+```js
+async function getMoviesFromApi() {
+  try {
+    const rsp = await fetch('//mywebsite.com/demo.json');
+    const json = await rsp.json();
+    return responseJson.movies;
+  } catch (error) {
+    console.error(error);
+  }
+}
+```
+
+::: warning 注意：在使用 fetch 发起网络请求的时候，需要记得捕获错误，否则错误会被静默丢弃。
+:::

package/rules/.docs/zh-CN/guide/network/websocket.md

@@ -0,0 +1,107 @@
+---
+title: 'WebSocket'
+lang: zh-CN
+---
+
+# WebSocket
+
+`WebSocket` 协议可以在单个TCP连接上提供全双工的通信信道，是一种长连接的网络通道。
+
+## 方法
+
+### constructor
+
+`(url: string, protocals: array, extrasHeaders: object)`
+创建一个 WebSocket 对象，并开始向指定的 url 建立 Websocket 连接
+
+* `url`: string - WebSocket 的连接地址，以 ws:// 或 wss:// 开头的 url；
+* `protocals`: array - 可选字段，指定WebSocket希望采用的交流协议，array 内部的单个元素为必须为字符串类型，按优先级排序，该字段会最终组装到 WebSocket 的
+  Sec-WebSocket-Protocol 请求头中；
+* `extrasHeaders`: object - 可选字段，指定建立 WebSocket 时的一些额外请求头；
+
+### close
+
+`(code:  number, reason: string)`
+主动关闭一条WebSocket，并向对端返回指定的code和reason
+
+* `code`: number - 可选字段，WebSocket关闭时，返回给对端的状态码；
+* `reason`: string - 可选字段，WebSocket关闭时，返回给对端的原因描述字符串；
+
+### send
+
+`(data: string)`
+向对端发送一段数据，现阶段仅支持发送文本数据，注意，请在明确收到 onopen 事件后才能真正发送数据，在连接尚未建立或已关闭的情况下发送数据会导致错误；
+
+* `data`: string - 向WebSocket对端发送的字符串数据；
+
+## 属性
+
+### readyState
+
+`number，只读属性`
+当前WebSocket的状态，取值为以下4种：
+
+* `0` - WebSocket正在连接中（Connecting）；
+* `1` - WebSocket连接建立成功，当前可以收发数据（Open）；
+* `2` - WebSocket连接正在关闭（Closing）；
+* `3` - WebSocket连接已关闭（Closed）；
+
+### url
+
+`string，只读属性`
+当前 WebSocket 使用的 url
+
+### onopen
+
+`function，只写属性`
+设置当前 WebSocket 在连接建立成功后的回调函数
+
+### onclose
+
+`function，只写属性`
+设置当前WebSocket在连接关闭时的回调函数，回调函数带有一个参数（Object类型），参数属性说明如下：
+
+* `code` - number，连接关闭的状态码；
+* `reason` - string，连接关闭的原因描述；
+
+### onmessage
+
+`function，只写属性`
+设置当前 WebSocket 在收到数据时的回调函数，回调函数带有一个参数（Object类型），参数属性说明如下：
+
+* `data` - string，实际收到的数据，由于当前WebSocket仅支持字符串数据的收发，这里一定为string类型；
+* `type` - string，收到的数据的类型，当前恒定为‘text’；
+
+### onerror
+
+`function，只写属性`
+设置当前 WebSocket 在连接出现错误时的回调函数，回调函数带有一个参数（Object类型），参数属性说明如下：
+
+* `reason` - string，连接出现错误的的原因描述；
+
+## 示例
+
+```js
+this.ws = new WebSocket("ws://websocket.test.qq.com/websocket");
+this.ws.onopen = () => {
+  console.log("WebSocket onOpen");
+  this.ws.send("Hello WebSocket")
+};
+
+this.ws.onclose = (param) => {
+  console.log(`WebSocket onClose: code = ${  param.code  }, reason = ${  param.reason}`);
+};
+
+this.ws.onerror = (param) => {
+  console.log(`WebSocket onError: reason = ${  param.reason}`);
+};
+
+this.ws.onmessage = (message) => {
+  console.log(`WebSocket onMessage: data type = ${  message.type}`);
+
+  // text 类型的回包数据
+  if (message.type == 'text') {
+    console.log(`WebSocket onMessage: data type = ${  message.data}`);
+  }
+};
+```