jsbox-cview 1.3.4 → 1.4.0

package/components/flowlayout.ts

@@ -0,0 +1,233 @@
+import { Base } from "./base";
+
+/**
+ * 流式布局：间距固定，项目高度固定但宽度不定，左对齐，自动换行，不能滚动。
+ * 
+ * 注意事项:
+ * 1. 此控件默认是可变高度的，但前提是布局中必须有关于高度的约束。如果不需要可变高度，可以设置fixedHeight为true
+ * 1. 此控件的边缘是不留白的，这和Matrix不同
+ * 2. itemWidth 如果超过总宽度，会被设定为总宽度
+ * 3. maxRows 可以控制最大行数，如果超过则会被截断
+ * 
+ * ## 属性
+ * 属性的写法尽可能和Matrix的风格保持一致
+ * - items: FlowlayoutItem[] 关键参数，必须实现一个方法itemWidth(): number, 用于告知自身理想的宽度
+ * - spacing: number
+ * - itemHeight: number
+ * - maxRows?: number
+ * - fixedHeight?: boolean
+ * - menu?: UiTypes.ContextMenuOptions
+ * 
+ * ## 事件
+ * - didSelect: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void
+ * - didLongPress: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void
+ *
+ * ## 方法
+ * - heightToWidth(width: number): height: number  根据宽度计算其应有的高度
+ * - cell(index: number): FlowlayoutItem  获取对应位置的 cview
+ * - set items(items: FlowlayoutItem[])  设置子视图
+ * - get items(): FlowlayoutItem[]  获取子视图
+ */
+export class Flowlayout extends Base<UIView, UiTypes.ViewOptions> {
+  private _width: number; // 缓存宽度，用于判断是否需要重新布局
+  private _props: {
+    items: FlowlayoutItem[];
+    spacing: number;
+    itemHeight: number;
+    fixedRows?: number;
+    fixedHeight?: boolean;
+    menu?: UiTypes.ContextMenuOptions;
+  }
+  private _wrappers: WrapperView[];
+  private _events?: {
+    didSelect?: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void;
+    didLongPress?: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void;
+  }
+  _defineView: () => UiTypes.ViewOptions;
+
+  constructor({ props, layout, events }: {
+    props: {
+      items: FlowlayoutItem[];
+      spacing: number;
+      itemHeight: number;
+      fixedRows?: number;
+      fixedHeight?: boolean;
+      menu?: UiTypes.ContextMenuOptions;
+    };
+    layout: (make: MASConstraintMaker, view: UIView) => void;
+    events?: {
+      didSelect?: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void;
+      didLongPress?: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void;
+    }
+  }) {
+    super();
+    this._width = 0;
+    this._props = props;
+    this._events = events;
+    this._wrappers = props.items.map((item, index) => new WrapperView({
+      item,
+      menu: props.menu,
+      didSelect: events?.didSelect,
+      didLongPress: events?.didLongPress,
+      flowlayout: this,
+      index
+    }));
+    this._defineView = () => ({
+      type: "view",
+      props: {
+        id: this.id
+      },
+      layout,
+      events: {
+        layoutSubviews: sender => {
+          if (this._width !== sender.frame.width) {
+            this._width = sender.frame.width;
+            const height = this._layoutWrappers();
+            if (!this._props.fixedHeight) sender.updateLayout((make) => make.height.equalTo(height));
+          }
+        }
+      },
+      views: this._wrappers.map(wrapper => wrapper.definition)
+    });
+  }
+
+  cell(index: number): FlowlayoutItem {
+    return this._props.items[index];
+  }
+
+  get items(): FlowlayoutItem[] {
+    return this._props.items;
+  }
+
+  set items(items: FlowlayoutItem[]) {
+    this._props.items = items;
+    this._wrappers = items.map((item, index) => new WrapperView({
+      item,
+      menu: this._props.menu,
+      didSelect: this._events?.didSelect,
+      didLongPress: this._events?.didLongPress,
+      flowlayout: this,
+      index
+    }));
+    this.view.views.forEach(v => v.remove());
+    this._wrappers.forEach(wrapper => this.view.add(wrapper.definition));
+    const height = this._layoutWrappers();
+    if (!this._props.fixedHeight) this.view.updateLayout((make) => make.height.equalTo(height));
+  }
+
+  _layoutWrappers(): number {
+    const totalWidth = this._width;
+    const itemHeight = this._props.itemHeight;
+    const itemSpacing = this._props.spacing;
+    let x = 0;
+    let y = 0;
+    let line = 1;
+    this._wrappers.forEach((wrapper, index) => {
+      const itemWidth = wrapper.item.itemWidth();
+      const width = Math.min(itemWidth, totalWidth);
+      if (x + width > totalWidth) {
+        x = 0;
+        y += itemHeight + itemSpacing;
+        line++;
+      }
+      if (this._props.fixedRows && line > this._props.fixedRows) {
+        wrapper.hidden = true;
+      } else {
+        wrapper.hidden = false;
+      }
+      wrapper.frame = $rect(x, y, width, itemHeight);
+      x += width + itemSpacing;
+    });
+    if (this._props.fixedRows && line > this._props.fixedRows) {
+      return this._props.fixedRows * (itemHeight + itemSpacing) - itemSpacing;
+    }
+    return y + itemHeight;
+  }
+
+  heightToWidth(width: number): number {
+    const totalWidth = width;
+    const itemHeight = this._props.itemHeight;
+    const itemSpacing = this._props.spacing;
+    let x = 0;
+    let y = 0;
+    let line = 1;
+    this._wrappers.forEach((wrapper, index) => {
+      const itemWidth = wrapper.item.itemWidth();
+      const width = Math.min(itemWidth, totalWidth);
+      if (x + width > totalWidth) {
+        x = 0;
+        y += itemHeight + itemSpacing;
+        line++;
+      }
+      x += width + itemSpacing;
+    });
+    if (this._props.fixedRows && line > this._props.fixedRows) {
+      return this._props.fixedRows * (itemHeight + itemSpacing) - itemSpacing;
+    }
+    return y + itemHeight;
+  }
+}
+
+interface FlowlayoutItem extends Base<any, any> {
+  itemWidth: () => number;
+}
+
+class WrapperView extends Base<UIView, UiTypes.ViewOptions> {
+  _defineView: () => UiTypes.ViewOptions;
+  item: FlowlayoutItem;
+  constructor({
+    item,
+    menu,
+    didSelect,
+    didLongPress,
+    flowlayout,
+    index
+  }: {
+    item: FlowlayoutItem;
+    menu?: UiTypes.ContextMenuOptions;
+    didSelect?: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void;
+    didLongPress?: (sender: Flowlayout, index: number, item: FlowlayoutItem) => void;
+    flowlayout: Flowlayout;
+    index: number;
+  }) {
+    super();
+    this.item = item;
+    const props: UiTypes.BaseViewProps = {
+      id: this.id,
+      frame: $rect(0, 0, 0, 0),
+      userInteractionEnabled: true,
+    }
+    if (menu) {
+      props.menu = menu;
+    }
+    this._defineView = () => ({
+      type: "view",
+      props,
+      views: [item.definition],
+      events: {
+        tapped: sender => {
+          if (didSelect) didSelect(flowlayout, index, item)
+        },
+        longPressed: sender => {
+          if (didLongPress) didLongPress(flowlayout, index, item)
+        }
+      }
+    });
+  }
+
+  set frame(frame: JBRect) {
+    this.view.frame = frame;
+  }
+
+  get frame(): JBRect {
+    return this.view.frame;
+  }
+
+  set hidden(hidden: boolean) {
+    this.view.hidden = hidden;
+  }
+
+  get hidden(): boolean {
+    return this.view.hidden;
+  }
+}

package/components/image-pager.ts

@@ -1,17 +1,12 @@
+import { Base } from "./base";
+import { Matrix } from "./single-views";
+
 /**
- * 与内置的Gallery组件相比，ImagePager组件可以动态刷新，适用于图片数量较多的场景，以及需要动态加载图片列表的场景
+ * 图片浏览组件
  * 
- * # Props
- * srcs: string[] - 图片地址列表
- * page: number - 当前页码
+ * 与内置的Gallery组件相比，ImagePager组件可以动态刷新，适用于图片数量较多的场景，以及需要动态加载图片列表的场景
  * 
- * # Events
- * changed: (page: number) => void - 页码变化时触发
- * tapped: (sender: ImagePager) => void - 点击图片时触发
  */
-import { Base } from "./base";
-import { Matrix } from "./single-views";
-
 export class ImagePager extends Base<UIView, UiTypes.ViewOptions> {
   _props: {
     srcs: string[];
@@ -20,6 +15,17 @@ export class ImagePager extends Base<UIView, UiTypes.ViewOptions> {
   _matrix: Matrix;
   _pageLoadRecorder: { [key: number]: boolean };
   _defineView: () => UiTypes.ViewOptions;
+
+  /**
+   * 
+   * @param props 
+   * - srcs: string[] - 图片地址列表
+   * - page: number - 当前页码
+   * @param layout
+   * @param events 
+   * - changed: (page: number) => void - 页码变化时触发
+   * - tapped: (sender: ImagePager) => void - 点击图片时触发
+   */
   constructor({ props, layout, events = {} }: {
     props: {
       srcs?: string[];

package/components/page-control.ts

@@ -1,24 +1,14 @@
+import { Runtime } from "./single-views";
+
 /**
- * # CView PageControl
  * 
  * 基于 Runtime 构建 PageControl
  * 
  * 请注意本视图如果没有足够的横向宽度，会显示不全
- * ## Props
  * 
- * - 只写 numberOfPages: numnber
- * - 读写 currentPage: number
- * - 只写 pageIndicatorTintColor?: JSBoxColor
- * - 只写 currentPageIndicatorTintColor?: JSBoxColor
- * - 其他通用属性
+ * @property currentPage: number
  * 
- * ## Events
- * 
- * changed: (cview: Cview, currentPage: number) => void
  */
-
-import { Runtime } from "./single-views";
-
 export class PageControl extends Runtime {
   private _numberOfPages: number;
   private _currentPage: number;
@@ -26,6 +16,19 @@ export class PageControl extends Runtime {
   private _currentPageIndicatorTintColor?: UIColor;
   private _changed?: (sender: PageControl, currentPage: number) => void;
   private _pageControl: any;
+
+  /**
+   * 
+   * @param props 属性
+   * - numberOfPages: 页面数量
+   * - currentPage: 当前页面
+   * - pageIndicatorTintColor?: 页面指示器颜色
+   * - currentPageIndicatorTintColor?: 当前页面指示器颜色
+   * @param layout 布局
+   * @param events 事件
+   * - changed: (sender: PageControl, currentPage: number) => void
+   * 
+   */
   constructor({ props, layout, events = {} }: {
     props: {
       numberOfPages?: number;

package/components/pageviewer-titlebar.ts

@@ -1,21 +1,5 @@
-/** 
- * # CView PageViewer TitleBar
- *
- * props:
- *
- * - 只写 items: string[]
- * - 读写 index: number
- * - 只写 selectedItemColor
- * - 只写 defaultItemColor
- *
- * events:
- *
- * - changed: (cview, index) => void 在点击变更 index 的时候回调
- */
-
 import { Base } from './base';
 import { ContentView, Label, Stack } from "./single-views";
-//const { getTextWidth } = require("cview-util-ui");
 
 function weightedAverageColors(c0: UIColor, c1: UIColor, w: number) {
   const red = c0.components.red * w + c1.components.red * (1 - w);
@@ -35,6 +19,10 @@ interface PageViewerTitleBarEvents extends UiTypes.BaseViewEvents {
   changed?: (cview: PageViewerTitleBar, index: number) => void;
 }
 
+/** 
+ * [PageViewer](./pageviewer.ts)配套的标题栏
+ * @property index: number
+ */
 export class PageViewerTitleBar extends Base<UIView, UiTypes.ViewOptions> {
   private _props: Required<PageViewerTitleBarProps>;
   private _floatedIndex: number;
@@ -46,6 +34,17 @@ export class PageViewerTitleBar extends Base<UIView, UiTypes.ViewOptions> {
 
   _defineView: () => UiTypes.ViewOptions;
 
+  /**
+   * 
+   * @param props 属性
+   * - items: string[]
+   * - index: number
+   * - selectedItemColor
+   * - defaultItemColor
+   * @param layout 布局
+   * @param events 事件
+   * - changed: (cview, index) => void 在点击变更 index 的时候回调
+   */
   constructor({ props, layout, events = {} }: {
     props: PageViewerTitleBarProps;
     layout: (make: MASConstraintMaker, view: UIView) => void;

package/components/pageviewer.ts

@@ -1,21 +1,12 @@
-/**
- * # CView PageViewer
- * 
- * props:
- * - 读写 page: number  
- * - 只写 cviews: cview[] cview的布局会被自动指定为占用一整页
- * 
- * events: 
- * - changed: (cview, page) => void 页面改变时回调
- * - floatPageChanged: (cview, floatPage) => void 滚动时回调（用于绑定其他联合滚动的控件）
- * 
- * methods:
- * - scrollToPage(page: number) 滚动到某一页（带有动画效果）
- */
-
 import { Base } from './base';
 import { ContentView, Scroll } from "./single-views";
 
+/**
+ * 与JSBox内置的Gallery功能类似，但是效果更好，可以伴随翻页实现联动效果，参见[pageviewer-titlebar.ts](./pageviewer-titlebar.ts)
+ * 
+ * @property page: number 当前页码（无动画效果）
+ * @method scrollToPage(page: number) 滚动到某一页（带有动画效果）
+ */
 export class PageViewer extends Base<UIView, UiTypes.ViewOptions> {
   private _props: {
     page: number;
@@ -30,6 +21,16 @@ export class PageViewer extends Base<UIView, UiTypes.ViewOptions> {
   scroll: Scroll;
   _defineView: () => UiTypes.ViewOptions;
 
+  /**
+   * 
+   * @param props 属性
+   * - page: number
+   * - cviews: Base<any, any>[]
+   * @param layout 布局
+   * @param events 事件
+   * - changed: (cview, page) => void 页面改变时回调
+   * - floatPageChanged: (cview, floatPage) => void 滚动时回调（用于绑定其他联合滚动的控件）
+   */
   constructor({ props, layout, events = {} }: {
     props: {
       page?: number;

package/components/rotating-view.ts

@@ -1,22 +1,3 @@
-/**
- * 创建一个可以旋转的视图。理论上来说，这个视图的布局必须是方形的。
- *
- * props: 
- * - image 图片
- * - tintColor
- * - contentMode = 1
- * - cview 使用自定义的cview，上面两项将失效
- * - rps = 0.5 每秒转多少圈
- * - clockwise = true 是否顺时针旋转
- * 
- * events:
- * - ready: cview => void 可以在ready事件中启动旋转
- * 
- * methods:
- * - startRotating() 开始旋转
- * - stopRotating() 结束旋转，请注意旋转是不能立即结束的，必须等到动画归位
- */
-
 import { Base } from "./base";
 import { Image } from "./single-views";
 
@@ -29,15 +10,35 @@ interface RotatingViewProps {
   clockwise?: boolean;
 }
 
-export class RotatingView extends Base<UIView, UiTypes.ViewOptions>{
+/**
+ * 创建一个可以旋转的视图。理论上来说，这个视图的布局必须是方形的。
+ * 
+ * @method startRotating() 开始旋转
+ * @method stopRotating() 结束旋转，请注意旋转是不能立即结束的，必须等到动画归位
+ */
+export class RotatingView extends Base<UIView, UiTypes.ViewOptions> {
   private _props: RotatingViewProps;
   private _rotatingFlag: boolean;
   private _innerView: Base<any, any>
   _defineView: () => UiTypes.ViewOptions;
+
+  /**
+   * 
+   * @param props 属性
+   * - image: UIImage
+   * - tintColor: UIColor
+   * - contentMode = 1
+   * - cview 使用自定义的cview，如果设置上面三项将失效
+   * - rps = 0.5 每秒转多少圈
+   * - clockwise = true 是否顺时针旋转
+   * @param layout 布局
+   * @param events 事件
+   * - ready?: (cview: RotatingView) => void 默认的ready事件是自动开始旋转；也可以手动指定其他效果
+   */
   constructor({ props, layout, events = {} }: {
     props: RotatingViewProps;
     layout: (make: MASConstraintMaker, view: UIView) => void;
-    events?: {
+    events: {
       ready?: (cview: RotatingView) => void;
     }
   }) {
@@ -74,8 +75,12 @@ export class RotatingView extends Base<UIView, UiTypes.ViewOptions>{
         layout,
         events: {
           ready: sender => {
-              if (events.ready) events.ready(this);
+            if (events.ready) {
+              events.ready(this);
+            } else {
+              this.startRotating();
             }
+          }
         },
         views: [this._innerView.definition]
       };

package/components/searchbar.ts

@@ -1,28 +1,3 @@
-/**
- * # CView SearchBar
- *
- * props
- *
- * - 读写 text: string
- * - style: number 搜索框的样式
- *   - 0: 取消按钮在输入框内，聚焦时显示取消按钮
- *   - 1: 取消按钮在输入框右侧，聚焦时会有左右移动的动画
- *   - 2: 取消按钮布局同 1，但是 placeholder 平时显示在中间，聚焦时才会移动到左边。
- *     如果使用此样式，建议每次 blur 的时候都清除 text
- * - accessoryCview: cview 请通过下面的事件来和 SearchBar 互相操作
- * - placeholder: string
- * - cancelText: string
- * - tintColor: \$color("systemLink")
- * - bgcolor: colors.searchBarBgcolor
- *
- * events
- *
- * - didBeginEditing: cview => void
- * - didEndEditing: cview => void
- * - changed: cview => void
- * - returned: cview => void
- */
-
 import { Base } from "./base";
 import { Input, Label, ContentView } from "./single-views";
 import { searchBarBgcolor } from "../utils/colors";
@@ -38,6 +13,15 @@ interface SearchBarProps {
   accessoryCview?: Base<any, any>;
 }
 
+/**
+ * 搜索框
+ * 
+ * 有三种样式可供选择，通过 style 属性设置
+ *
+ * @method focus() 聚焦
+ * @method blur() 失焦
+ * @property text: string 文本
+ */
 export class SearchBar extends Base<UIView, UiTypes.ViewOptions> {
   _props: SearchBarProps;
   _defineView: () => UiTypes.ViewOptions;
@@ -61,6 +45,27 @@ export class SearchBar extends Base<UIView, UiTypes.ViewOptions> {
     };
   };
   _focused: boolean;
+
+  /**
+   * 
+   * @param props 属性
+   * - text: string
+   * - style: number 搜索框的样式
+   *   - 0: 取消按钮在输入框内，聚焦时显示取消按钮
+   *   - 1: 取消按钮在输入框右侧，聚焦时会有左右移动的动画
+   *   - 2: 取消按钮布局同 1，但是 placeholder 平时显示在中间，聚焦时才会移动到左边。如果使用此样式，建议每次 blur 的时候都清除 text。
+   * - accessoryCview: cview 请通过下面的事件来和 SearchBar 互相操作
+   * - placeholder: string
+   * - cancelText: string
+   * - tintColor: \$color("systemLink")
+   * - bgcolor: colors.searchBarBgcolor
+   * @param layout 布局
+   * @param events 事件
+   * - didBeginEditing: cview => void
+   * - didEndEditing: cview => void
+   * - changed: cview => void
+   * - returned: cview => void
+   */
   constructor({ props, layout, events = {} }: {
     props: Partial<SearchBarProps>;
     layout: (make: MASConstraintMaker, view: UIView) => void;

package/components/sheet.ts

@@ -1,5 +1,20 @@
+import {cvid} from "../utils/cvid";
+import {Base} from "./base";
+
+const UIModalPresentationStyle = {
+  automatic: -2,
+  pageSheet: 1,
+  formSheet: 2,
+  fullScreen: 0,
+  currentContext: 3,
+  custom: 4,
+  overFullScreen: 5,
+  overCurrentContext: 6,
+  popover: 7,
+  none: -1
+};
+
 /**
- * # cview Sheet
  * 
  * 创建新的 UIViewController，主要用于 formSheet 和 pageSheet
  * 
@@ -16,22 +31,6 @@
  * - dismiss()
  * 
  */
-import {cvid} from "../utils/cvid";
-import {Base} from "./base";
-
-const UIModalPresentationStyle = {
-  automatic: -2,
-  pageSheet: 1,
-  formSheet: 2,
-  fullScreen: 0,
-  currentContext: 3,
-  custom: 4,
-  overFullScreen: 5,
-  overCurrentContext: 6,
-  popover: 7,
-  none: -1
-};
-
 export class Sheet<T extends Base<U, R>, U extends AllUIView, R extends UiTypes.AllViewOptions> {
   id: string;
   _animated: boolean;