@fjyueke/bify-mcp 1.0.0

package/metaData/components/list/doc.md

@@ -0,0 +1,317 @@
+# List 列表
+
+### 介绍
+
+瀑布流滚动加载，用于展示长列表，当列表即将滚动到底部时，会触发事件并加载更多列表项。
+
+### 引入
+
+```tsx
+import { List } from "@fjyueke/bify-core"
+```
+
+## 代码演示
+
+### 基础用法
+
+List 组件通过 `loading` 和 `hasMore` 两个变量控制加载状态，当组件滚动到底部时，会触发 `load` 事件并将 `loading` 设置成 `true`
+。此时可以发起异步操作并更新数据，数据更新完毕后，将 `loading` 设置成 `false` 即可。若数据已全部加载完毕，则直接将 `hasMore` 设置成 `false` 即可。
+
+```tsx
+function BasicList() {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  return (
+    <List
+      loading={loading}
+      hasMore={hasMore}
+      onLoad={() => {
+        setLoading(true)
+        setTimeout(() => {
+          for (let i = 0; i < 10; i++) {
+            const text = list.length + 1
+            list.push(text < 10 ? "0" + text : String(text))
+          }
+          setList([...list])
+          setHasMore(list.length < 40)
+          setLoading(false)
+        }, 1000)
+      }}
+    >
+      {
+        //
+        list.map((item) => (
+          <Cell key={item}>{item}</Cell>
+        ))
+      }
+      <List.Placeholder>
+        {loading && <Loading>加载中...</Loading>}
+        {!hasMore && "没有更多了"}
+      </List.Placeholder>
+    </List>
+  )
+}
+```
+
+> Tips: 在 Tabs 里使用，通过设置 disabled={tabKey !== activeTabKey}，避免其他 tab 里的 List 也触发了滑动
+
+### 固定高度
+
+设置 fixedHeight，通过 class 或者 style 指定容器高度
+
+```tsx
+function FixedHeightList() {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const ref = useRef<ListInstance>(null)
+
+  return (
+    <>
+      <List
+        ref={ref}
+        loading={loading}
+        hasMore={hasMore}
+        fixedHeight
+        style={{ height: "300px" }}
+        onLoad={() => {
+          setLoading(true)
+          setTimeout(() => {
+            for (let i = 0; i < 10; i++) {
+              const text = list.length + 1
+              list.push(text < 10 ? "0" + text : String(text))
+            }
+            setList([...list])
+            setHasMore(list.length < 40)
+            setLoading(false)
+          }, 1000)
+        }}
+      >
+        {
+          //
+          list.map((item) => (
+            <Cell key={item}>{item}</Cell>
+          ))
+        }
+        <List.Placeholder>
+          {loading && <Loading>加载中...</Loading>}
+          {!hasMore && "没有更多了"}
+        </List.Placeholder>
+      </List>
+    </>
+  )
+}
+```
+
+### 错误提示
+
+若列表数据加载失败，将 `error` 设置成 `true` 即可显示错误提示，用户点击错误提示后会重新触发 load 事件。
+
+```tsx
+function ErrorList() {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(false)
+
+  return (
+    <List
+      loading={loading}
+      hasMore={hasMore}
+      onLoad={() => {
+        setLoading(true)
+        setTimeout(() => {
+          for (let i = 0; i < 10; i++) {
+            const text = list.length + 1
+            list.push(text < 10 ? "0" + text : String(text))
+          }
+          const newList = [...list]
+
+          setHasMore(!(newList.length <= 10 || newList.length >= 40))
+          setError(newList.length <= 10)
+          setList(newList)
+          setLoading(false)
+        }, 1000)
+      }}
+    >
+      {list.map((item) => (
+        <Cell key={item}>{item}</Cell>
+      ))}
+      <List.Placeholder
+        onClick={() => {
+          if (error) {
+            setHasMore(true)
+            setError(false)
+          }
+        }}
+      >
+        {loading && <Loading>加载中...</Loading>}
+        {error && "请求失败，点击重新加载"}
+        {!error && !hasMore && "没有更多了"}
+      </List.Placeholder>
+    </List>
+  )
+}
+```
+
+### 下拉刷新
+
+List 组件可以与 [PullRefresh](/components/pull-refresh/) 组件结合使用，实现下拉刷新的效果。固定高度时，scrollTop可以从onScroll中获取`(e.detail.scrollTop)`
+
+```tsx
+function PullRefreshList() {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const refreshingRef = useRef(false)
+  const [reachTop, setReachTop] = useState(true)
+
+  usePageScroll(({ scrollTop: aScrollTop }) => {
+    setReachTop(aScrollTop === 0)
+  })
+
+  const onLoad = () => {
+    setLoading(true)
+    const newList = refreshingRef.current ? [] : list
+    setTimeout(() => {
+      refreshingRef.current = false
+      for (let i = 0; i < 10; i++) {
+        const text = newList.length + 1
+        newList.push(text < 10 ? "0" + text : String(text))
+      }
+      setList(newList)
+      setLoading(false)
+      setHasMore(newList.length < 40)
+    }, 1000)
+  }
+
+  function onRefresh() {
+    refreshingRef.current = true
+    setLoading(false)
+    onLoad()
+  }
+
+  return (
+    <List loading={loading} hasMore={hasMore} onLoad={onLoad}>
+      <PullRefresh loading={refreshingRef.current} reachTop={reachTop} onRefresh={onRefresh}>
+        {list.map((item) => (
+          <Cell key={item}>{item}</Cell>
+        ))}
+        {!refreshingRef.current && (
+          <List.Placeholder>
+            {loading && <Loading>加载中...</Loading>}
+            {!hasMore && "没有更多了"}
+          </List.Placeholder>
+        )}
+      </PullRefresh>
+    </List>
+  )
+}
+```
+
+## API
+
+### Props
+
+| 参数                                                                    | 说明                                             | 类型      | 默认值  |
+| ----------------------------------------------------------------------- | ------------------------------------------------ | --------- | ------- |
+| fixedHeight <br>`v0.1.1-alpha.2`                                        | 是否固定高度                                     | _boolean_ | `false` |
+| loading                                                                 | 是否处于加载状态，加载过程中不触发 `onLoad` 事件 | _boolean_ | `false` |
+| hasMore                                                                 | 是否已加载完成，加载完成后不再触发 `onLoad` 事件 | _boolean_ | `false` |
+| offset                                                                  | 滚动条与底部距离小于 offset 时触发 `onLoad` 事件 | _number_  | `100`   |
+| immediateCheck <br>`v0.1.1-alpha.2`                                     | 是否在初始化时立即执行滚动位置检查               | _boolean_ | `true`  |
+| disabled <br>`v0.1.1-alpha.2`                                           | 是否禁用滚动加载                                 | _boolean_ | `false` |
+| direction                                                               | 滚动触发加载的方向，可选值为 `up`                | _string_  | `down`  |
+| <span style="color: red">~~scrollTop~~ <br>`v0.1.1-alpha.2 移除`</span> | 距离顶部的滚动距离                               | _number_  | `0`     |
+
+### Events
+
+| 事件名                                                                 | 说明                               | 回调参数 |
+| ---------------------------------------------------------------------- | ---------------------------------- | -------- |
+| onLoad                                                                 | 滚动条与底部距离小于 offset 时触发 | -        |
+| <span style="color: red">~~onLoading~~ <br>`v0.1.1-alpha.2移除`</span> | 内部 loading 改变时触发            | -        |
+| onScroll  | 滚动时触发      | e      |
+
+### 方法
+
+通过 ref 可以获取到 List 实例并调用实例方法
+
+| 方法名                 | 说明                                                   | 参数 | 返回值 |
+| ---------------------- | ------------------------------------------------------ | ---- | ------ |
+| check `v0.1.1-alpha.2` | 检查当前的滚动位置，若已滚动至底部，则会触发 load 事件 | -    | -      |
+
+## 主题定制
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/) 组件。
+
+| 名称                       | 默认值                          | 描述 |
+| -------------------------- | ------------------------------- | ---- |
+| --list-text-color          | _var(--gray-6)_                 | -    |
+| --list-text-font-size      | _var(--font-size-md)_           | -    |
+| --list-text-line-height    | _50px \* $hd_                   | -    |
+| --list-loading-icon-size   | _16px \* $hd_                   | -    |
+| --list-loading-icon-width  | _var(--list-loading-icon-size)_ | -    |
+| --list-loading-icon-height | _var(--list-loading-icon-size)_ | -    |
+
+## 常见问题
+
+### List 的运行机制是什么？
+
+- 当设置 fixedHeight 为 false 时会监听页面滚动事件(usePageScroll)
+- 当设置 fixedHeight 为 true 时会监听滚动容器的滚动事件(onScroll)
+  当列表底部与可视区域的距离小于 `offset` 时，List 会触发一次 load 事件。
+
+### 为什么 List 初始化后会立即触发 load 事件？
+
+List 初始化后会触发一次 load 事件，用于加载第一屏的数据，这个特性可以通过 `hasMore={false}` 属性关闭。
+
+### 为什么会连续触发 load 事件？
+
+如果一次请求加载的数据条数较少，导致列表内容无法铺满当前屏幕，List 会继续触发 load 事件，直到内容铺满屏幕或数据全部加载完成。因此你需要调整每次获取的数据条数，理想情况下每次请求获取的数据条数应能够填满一屏高度。
+
+### loading 和 hasMore 分别是什么含义？
+
+`List` 有以下三种状态，理解这些状态有助于你正确地使用 `List` 组件：
+
+- 非加载中，`loading` 为 `false`，此时会根据列表滚动位置判断是否触发 `onLoad` 事件（列表内容不足一屏幕时，会直接触发）
+- 加载中，`loading` 为 `true`，表示正在发送异步请求，此时不会触发 `onLoad` 事件
+- 加载完成，`hasMore` 为 `false`，此时不会触发 `onLoad` 事件
+
+在每次请求完毕后，需要手动将 `loading` 设置为 `false`，表示加载结束
+
+### 使用 float 布局后一直触发加载？
+
+若 List 的内容使用了 float 布局，可以在容器上添加 `taroify-clearfix` 类名来清除浮动，使得 List 能正确判断元素位置
+
+```tsx
+<List>
+  <View class="taroify-clearfix">
+    <View class="float-item" />
+    <View class="float-item" />
+    <View class="float-item" />
+  </View>
+</List>
+```
+
+### 在 html、body 上设置 overflow 后一直触发加载？
+
+如果在 html 和 body 标签上设置了 `overflow-x: hidden` 样式，会导致 List 一直触发加载。
+
+```css
+html,
+body {
+  overflow-x: hidden;
+}
+```
+
+这个问题的原因是当元素设置了 `overflow-x: hidden` 样式时，该元素的 `overflow-y` 会被浏览器设置为 `auto`，而不是默认值 `visible`，导致 List
+无法正确地判断滚动容器。解决方法是去除该样式，或者在 html 和 body 标签上添加 `height: 100%` 样式。
+
+### direction 属性设置为 up 后一直触发加载？
+
+设置 `direction` 属性为 up 后，当滚动条处于页面顶部时，就会触发 List 组件的加载。
+
+因此在使用该属性时，建议在每次数据加载完成后，将滚动条滚动至页面底部或非顶部的位置。

package/metaData/components/list/example/index.tsx

@@ -0,0 +1,218 @@
+import { Cell, List, ListInstance, Loading, PullRefresh, Tabs, Button, Flex } from "@fjyueke/bify-core"
+import { usePageScroll } from "@tarojs/taro"
+import { useRef, useState } from "react"
+import Page from "../../../components/page"
+import "./index.scss"
+
+function BasicList({ disabled }) {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  return (
+    <List
+      loading={loading}
+      hasMore={hasMore}
+      disabled={disabled}
+      onLoad={() => {
+        setLoading(true)
+        setTimeout(() => {
+          for (let i = 0; i < 10; i++) {
+            const text = list.length + 1
+            list.push(text < 10 ? "0" + text : String(text))
+          }
+          setList([...list])
+          setHasMore(list.length < 40)
+          setLoading(false)
+        }, 1000)
+      }}
+    >
+      {
+        //
+        list.map((item) => (
+          <Cell key={item}>{item}</Cell>
+        ))
+      }
+      <List.Placeholder>
+        {loading && <Loading>加载中...</Loading>}
+        {!hasMore && "没有更多了"}
+      </List.Placeholder>
+    </List>
+  )
+}
+
+function FixedHeightList({ disabled }) {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const ref = useRef<ListInstance>(null)
+
+  return (
+    <>
+      <List
+        ref={ref}
+        loading={loading}
+        hasMore={hasMore}
+        fixedHeight
+        style={{ height: "300px" }}
+        disabled={disabled}
+        immediateCheck={false}
+        onLoad={() => {
+          setLoading(true)
+          setTimeout(() => {
+            for (let i = 0; i < 10; i++) {
+              const text = list.length + 1
+              list.push(text < 10 ? "0" + text : String(text))
+            }
+            setList([...list])
+            setHasMore(list.length < 40)
+            setLoading(false)
+          }, 1000)
+        }}
+      >
+        {
+          //
+          list.map((item) => (
+            <Cell key={item}>{item}</Cell>
+          ))
+        }
+        <List.Placeholder>
+          {loading && <Loading>加载中...</Loading>}
+          {!hasMore && "没有更多了"}
+        </List.Placeholder>
+      </List>
+      <Flex align="center" direction="column">
+        <Flex.Item>immediateCheck设为false,调用check，触发onLoad</Flex.Item>
+        <Flex.Item>
+          <Button
+            onClick={() => {
+              ref.current?.check()
+            }}
+          >
+            check
+          </Button>
+        </Flex.Item>
+      </Flex>
+    </>
+  )
+}
+
+function ErrorList({ disabled }) {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(false)
+
+  return (
+    <List
+      loading={loading}
+      hasMore={hasMore}
+      disabled={disabled}
+      onLoad={() => {
+        setLoading(true)
+        setTimeout(() => {
+          for (let i = 0; i < 10; i++) {
+            const text = list.length + 1
+            list.push(text < 10 ? "0" + text : String(text))
+          }
+          const newList = [...list]
+
+          setHasMore(!(newList.length <= 10 || newList.length >= 40))
+          setError(newList.length <= 10)
+          setList(newList)
+          setLoading(false)
+        }, 1000)
+      }}
+    >
+      {list.map((item) => (
+        <Cell key={item}>{item}</Cell>
+      ))}
+      <List.Placeholder
+        onClick={() => {
+          if (error) {
+            setHasMore(true)
+            setError(false)
+          }
+        }}
+      >
+        {loading && <Loading>加载中...</Loading>}
+        {error && "请求失败，点击重新加载"}
+        {!error && !hasMore && "没有更多了"}
+      </List.Placeholder>
+    </List>
+  )
+}
+
+function PullRefreshList({ disabled }) {
+  const [hasMore, setHasMore] = useState(true)
+  const [list, setList] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const refreshingRef = useRef(false)
+  const [reachTop, setReachTop] = useState(true)
+
+  usePageScroll(({ scrollTop: aScrollTop }) => {
+    setReachTop(aScrollTop === 0)
+  })
+
+  const onLoad = () => {
+    setLoading(true)
+    const newList = refreshingRef.current ? [] : list
+    setTimeout(() => {
+      refreshingRef.current = false
+      for (let i = 0; i < 10; i++) {
+        const text = newList.length + 1
+        newList.push(text < 10 ? "0" + text : String(text))
+      }
+      setList(newList)
+      setLoading(false)
+      setHasMore(newList.length < 40)
+    }, 1000)
+  }
+
+  function onRefresh() {
+    refreshingRef.current = true
+    setLoading(false)
+    onLoad()
+  }
+
+  return (
+    <List loading={loading} hasMore={hasMore} onLoad={onLoad} disabled={disabled}>
+      <PullRefresh loading={refreshingRef.current} reachTop={reachTop} onRefresh={onRefresh}>
+        {
+          //
+          list.map((item) => (
+            <Cell key={item}>{item}</Cell>
+          ))
+        }
+        {!refreshingRef.current && (
+          <List.Placeholder>
+            {loading && <Loading>加载中...</Loading>}
+            {!hasMore && "没有更多了"}
+          </List.Placeholder>
+        )}
+      </PullRefresh>
+    </List>
+  )
+}
+
+export default function ListDemo() {
+  const [tab, setTab] = useState(0)
+
+  return (
+    <Page title="List 列表" className="list-demo">
+      <Tabs value={tab} onChange={setTab}>
+        <Tabs.TabPane title="基础用法">
+          <BasicList disabled={tab !== 0} />
+        </Tabs.TabPane>
+        <Tabs.TabPane title="固定高度">
+          <FixedHeightList disabled={tab !== 1} />
+        </Tabs.TabPane>
+        <Tabs.TabPane title="错误提示">
+          <ErrorList disabled={tab !== 2} />
+        </Tabs.TabPane>
+        <Tabs.TabPane title="下拉刷新">
+          <PullRefreshList disabled={tab !== 3} />
+        </Tabs.TabPane>
+      </Tabs>
+    </Page>
+  )
+}

package/metaData/components/loading/api.md

@@ -0,0 +1,10 @@
+## API
+
+### Props
+
+| 参数       | 说明                          | 类型               | 默认值     |
+| ---------- | ----------------------------- | ------------------ | ---------- |
+| type       | 类型，可选值为 `spinner`      | _string_           | `circular` |
+| size       | 加载图标大小，默认单位为 `px` | _number \| string_ | `30px`     |
+| direction | 排列方向，可选值为 `horizontal` | _string_ | `vertical` |
+| children   | 加载文案    | _ReactNode_          | -    |

package/metaData/components/loading/doc.md

@@ -0,0 +1,113 @@
+# Loading 加载
+
+### 介绍
+
+加载图标，用于表示加载中的过渡状态。
+
+### 引入
+
+```tsx
+import { Loading } from "@fjyueke/bify-core"
+```
+
+## 代码演示
+
+### 加载类型
+
+通过 `type` 属性可以设置加载图标的类型，默认为 `circular`，可选值为 `spinner`。
+
+```tsx
+<Loading />
+<Loading type="spinner" />
+```
+
+### 自定义颜色
+
+通过 `css` 设置加载图标的颜色。
+
+```tsx
+<Loading />
+<Loading type="spinner" />
+```
+
+```scss
+.custom-color {
+  color: #1989fa;
+  
+  .taroify-loading__text {
+    color: #1989fa;
+  }
+}
+```
+
+### 自定义大小
+
+通过 `size` 属性设置加载图标的大小，默认单位为 `px`。
+
+```tsx
+<Loading size="24px" />
+<Loading type="spinner" size="24px" />
+```
+
+### 加载文案
+
+可以使用默认插槽在图标的右侧插入加载文案。
+
+```tsx
+<Loading size="24px">加载中...</Loading>
+```
+
+### 垂直排列
+
+设置 `vertical` 属性后，图标和文案会垂直排列。
+
+```tsx
+<Loading size="24px" direction="vertical">加载中...</Loading>
+```
+
+### 自定义文案颜色
+
+通过 `css` 设置加载文案的颜色。
+
+```tsx
+<!-- 可修改文案和加载图标的颜色 -->
+<Loading className="custom-color" />
+
+<!-- 只修改文案颜色 -->
+<Loading className="custom-text-color" />
+```
+
+```scss
+.custom-text-color {
+  .taroify-loading__text {
+    color: #1989fa;
+  }
+}
+```
+
+## API
+
+### Props
+
+| 参数       | 说明                          | 类型               | 默认值     |
+| ---------- | ----------------------------- | ------------------ | ---------- |
+| type       | 类型，可选值为 `spinner`      | _string_           | `circular` |
+| size       | 加载图标大小，默认单位为 `px` | _number \| string_ | `30px`     |
+| direction | 排列方向，可选值为 `horizontal` | _string_ | `vertical` |
+| children   | 加载文案    | _ReactNode_          | -    |
+
+## 主题定制
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/) 组件。
+
+| 名称                              | 默认值                   | 描述  |
+|---------------------------------|-----------------------|-----|
+| --loading-color                 | _var(--gray-5)_       | -   |
+| --loading-size                  | _30px * $hd_          | -   |
+| --loading-animation-duration    | _0.8s_                | -   |
+| --loading-circular-border-width | _1px * $hd_           | -   |
+| --loading-text-color            | _var(--gray-6)_       | -   |
+| --loading-text-font-size        | _var(--font-size-md)_ | -   |
+| --loading-text-line-height      | _20px * $hd_          | -   |

package/metaData/components/loading/example/index.tsx

@@ -0,0 +1,47 @@
+import { Loading, Space } from "@fjyueke/bify-core"
+import Block from "../../../components/block"
+import Page from "../../../components/page"
+import "./index.scss"
+
+export default function LoadingDemo() {
+  return (
+    <Page title="Loading 加载" className="loading-demo">
+      <Block title="加载类型">
+        <Space>
+          <Loading />
+          <Loading type="spinner" />
+        </Space>
+      </Block>
+      <Block title="自定义颜色">
+        <Space>
+          <Loading className="custom-color" />
+          <Loading className="custom-color" type="spinner" />
+        </Space>
+      </Block>
+      <Block title="自定义大小">
+        <Space>
+          <Loading size="24" />
+          <Loading type="spinner" size="24" />
+        </Space>
+      </Block>
+      <Block title="加载文案">
+        <Loading size="24">加载中...</Loading>
+      </Block>
+      <Block title="垂直排列">
+        <Loading direction="vertical" size="24">
+          加载中...
+        </Loading>
+      </Block>
+      <Block title="垂直排列">
+        <Space size="large">
+          <Loading className="custom-color" direction="vertical">
+            加载中...
+          </Loading>
+          <Loading className="custom-text-color" direction="vertical">
+            加载中...
+          </Loading>
+        </Space>
+      </Block>
+    </Page>
+  )
+}