jsbox-cview 1.0.0

package/controller/base-controller.ts

@@ -0,0 +1,216 @@
+/** 
+ * # CView Base Controller
+ * 
+ * Cview 控件尽量保持非侵入性和功能专注。而控制器负责控件之间的关联和数据更新。
+ * 另外，控制器可以实现一些常用的页面构建形式，比如底部Tab分页，左侧滑动分页，弹出式页面等。
+ * 
+ * ## 属性
+ * 
+ * - id?: string 可以指定 id，如不指定，会自动赋值全局唯一 id
+ * - 只写 bgcolor?: UIColor = $color("primarySurface") rootView 的 bgcolor
+ * - 只读 cviews: {}
+ * - 只读 rootView
+ * - 只读 status
+ *   - created = 0 被创建，未被加载
+ *   - loaded = 1 被加载，显示状态未知
+ *   - appearing = 2 处于可显示状态
+ *   - disappearing = 3 处于不显示状态
+ *   - removed = 4 根视图被移除
+ * 
+ * ## 事件
+ * 
+ * 5 个生命周期节点：创建、加载、显示、隐藏、销毁。后面四个具有生命周期事件。
+ * 
+ * 创建阶段没有对应事件，此阶段适合为 rootView 添加子 view，不能涉及对 UIView 的任何操作，因为此时 rootView 还未加载。
+ * 
+ * 生命周期事件：
+ *
+ * 1. didLoad: controller => void 在 rootView 被加载之后执行
+ *    - 可以在 rootView 的 ready 事件中自动执行，也可以手动执行加快速度
+ *    - 也可以在这个节点为 rootView 添加子 view
+ *    - 这个节点可以对 UIView 进行操作了
+ *    - 可以向 Model 层请求初始数据
+ * 2. didAppear: controller => void 在 rootView 显现的时候执行
+ *    - 向 Model 层请求刷新数据
+ * 3. didDisappear: controller => void 在 rootView 不可见的时候执行
+ *    - 如果是持续执行的刷新行为，可以在此处转为暂停
+ * 4. didRemove: controller => void 在 rootView 被移除的时候执行
+ *    - 应该在此节点释放自定义的 objc
+ *    - 数据持久化
+ * 
+ * ## 方法
+ * 
+ * 加载方法：
+ * 
+ * 1. uirender(props) 此方法只能使用一次，对应的 Controller 将成为顶级 Controller
+ * 2. uipush(props)
+ * 3. 直接让 rootView.definition 包含在其他 View 的 views 参数中
+ * 
+ * 生命周期管理：
+ * 
+ * 1. load() 会在 rootView 的 ready 事件中自动调用，也可以手动调用，以加速运行
+ * 2. appear()
+ * 3. disappear()
+ * 4. remove() 用来移除 Router 中的当前 Controller，**请注意此方法和 rootView 的移除无关**，如果通过 uirender 和 uipush，可以在销毁时自动执行 remove()
+ * 
+ * ## 其他
+ * 
+ * - rootView 可以直接通过 rootView.views 设置其_views 属性，其中元素可以为 view 定义也可以为 cview
+ */
+
+import { Base } from '../components/base';
+import { ContentView } from '../components/single-views';
+import { cvid } from "../utils/cvid";
+import { router } from "./controller-router";
+
+/**
+ * status
+ *   - created = 0 被创建，未被加载
+ *   - loaded = 1 被加载，显示状态未知
+ *   - appeared= 2 处于可显示状态
+ *   - disappeared = 3 处于不显示状态
+ *   - removed = 4 根视图被移除
+ * 其中只有 2 和 3 可以相互转化，其他不可以
+ */
+const controllerStatus = {
+  created: 0,
+  loaded: 1,
+  appeared: 2,
+  disappeared: 3,
+  removed: 4
+};
+
+export class ControllerRootView extends ContentView {
+  constructor({
+    props,
+    layout,
+    events
+  }: {
+    props: { bgcolor: UIColor };
+    layout: (make: MASConstraintMaker, view: UIView) => void;
+    events: { ready: (sender: UIView) => void };
+  }) {
+    super({ props, layout, events });
+  }
+
+  set views(views: UiTypes.AllViewOptions[] | Base<any, any>[]) {
+    const _views: UiTypes.AllViewOptions[] = views.map(v => {
+      if (v instanceof Base) return v.definition;
+      return v;
+    })
+    this._views = _views;
+  }
+}
+
+export interface BaseControllerProps {
+  id?: string;
+  bgcolor?: UIColor;
+}
+
+export interface BaseControllerEvents {
+  didCreate?: (controller: BaseController) => void;
+  didLoad?: (controller: BaseController) => void;
+  didAppear?: (controller: BaseController) => void;
+  didDisappear?: (controller: BaseController) => void;
+  didRemove?: (controller: BaseController) => void;
+}
+
+export class BaseController {
+  protected _props: BaseControllerProps;
+  protected _events: BaseControllerEvents;
+  readonly id: string;
+  private _status: number;
+  cviews: {
+    [key: string]: Base<any, any>;
+  };
+  readonly rootView: ControllerRootView;
+  constructor({ props, layout = $layout.fill, events = {} }: {
+    props?: BaseControllerProps;
+    layout?: (make: MASConstraintMaker, view: UIView) => void;
+    events?: BaseControllerEvents;
+  } = {}) {
+    this._props = props || {};
+    this._events = events;
+    this.id = this._props.id || cvid.newId;
+
+    this._status = controllerStatus.created; // status使用额外的get来使其只读
+    this.rootView = new ControllerRootView({
+      props: {
+        bgcolor: this._props.bgcolor || $color("primarySurface")
+      },
+      layout,
+      events: {
+        ready: sender => this.load()
+      }
+    })
+    this.cviews = {};
+  }
+
+  load() {
+    // 只有status为created才可以运行
+    if (this._status !== controllerStatus.created) return;
+    this._status = controllerStatus.loaded;
+    if (this._events.didLoad) this._events.didLoad(this);
+    router.add(this)
+  }
+
+  appear() {
+    // 只有status为loaded或者disappeared，才可以运行
+    if (
+      this._status !== controllerStatus.loaded &&
+      this._status !== controllerStatus.disappeared
+    )
+      return;
+    if (this._events.didAppear) this._events.didAppear(this);
+    this._status = controllerStatus.appeared;
+  }
+
+  disappear() {
+    // 只有status为loaded或者appeared，才可以运行
+    if (
+      this._status !== controllerStatus.loaded &&
+      this._status !== controllerStatus.appeared
+    )
+      return;
+    if (this._events.didDisappear) this._events.didDisappear(this);
+    this._status = controllerStatus.disappeared;
+  }
+
+  // 此方法不能用于移除rootView，其作用是将控制器从Router中移除，并触发didRemove事件
+  remove() {
+    // 如果已经移除，不可以再次运行
+    if (this._status === controllerStatus.removed) return;
+    if (this._events.didRemove) this._events.didRemove(this);
+    router.delete(this)
+    this._status = controllerStatus.removed;
+  }
+
+  uirender(props: UiTypes.RootViewPrefs) {
+    router.root = this;
+    $ui.render({
+      props,
+      views: [this.rootView.definition],
+      events: {
+        appeared: () => this.appear(),
+        disappeared: () => this.disappear(),
+        dealloc: () => this.remove()
+      }
+    });
+  }
+
+  uipush(props: UiTypes.RootViewPrefs) {
+    $ui.push({
+      props,
+      views: [this.rootView.definition],
+      events: {
+        appeared: () => this.appear(),
+        disappeared: () => this.disappear(),
+        dealloc: () => this.remove()
+      }
+    });
+  }
+
+  get status() {
+    return this._status;
+  }
+}

package/controller/controller-router.ts

@@ -0,0 +1,74 @@
+/**
+ * 控制器的路由器，用于管理控制器的集合和操作。
+ * 
+ * ## 属性
+ * - `root`：根控制器。
+ * - `appeared`：状态为appeared的控制器列表。
+ * - `controllerSet`：控制器集合。
+ * 
+ * ## 方法
+ * - `add(controller: BaseController)`：添加控制器到路由器中。
+ * - `delete(controller: BaseController)`：从路由器中删除控制器。
+ * - `get(id: string)`：根据控制器的ID获取控制器。
+ * 
+ */
+
+import { BaseController } from "./base-controller";
+
+class Router {
+  private _set: Set<BaseController>;
+  root?: BaseController;
+  constructor() {
+    this._set = new Set();
+  }
+
+  /**
+   * 添加控制器到路由器中。
+   * @param controller 要添加的控制器。
+   */
+  add(controller: BaseController) {
+    this._set.add(controller);
+  }
+
+  /**
+   * 从路由器中删除控制器。
+   * @param controller 要删除的控制器。
+   */
+  delete(controller: BaseController) {
+    this._set.delete(controller);
+  }
+
+  /**
+   * 根据控制器的ID获取控制器。
+   * @param id 控制器的ID。
+   * @returns 匹配的控制器，如果找不到则返回undefined。
+   */
+  get(id: string) {
+    for (const c of this._set) {
+      if (c.id === id) return c;
+    }
+    return;
+  }
+
+  /**
+   * 获取状态为appeared的控制器集合。
+   * @returns 控制器集合。
+   */
+  get appeared() {
+    const appearedControllers = [];
+    for (const c of this._set) {
+      if (c.status === 2) appearedControllers.push(c);
+    }
+    return appearedControllers;
+  }
+
+  /**
+   * 获取控制器集合。
+   * @returns 控制器集合。
+   */
+  get controllerSet() {
+    return this._set;
+  }
+}
+
+export const router = new Router();

package/controller/pageviewer-controller.ts

@@ -0,0 +1,86 @@
+/** 
+ * # CView PageViewer Controller
+ * 
+ * 一个可以左右滑动翻页的控制器。
+ * 
+ * Props:
+ * 
+ * - items: { controller: Controller, title: string }[]
+ * - navBarProps: {} 可用于 navBar 的其他属性，不包括 title 和 titleView
+ */
+
+import { BaseController, BaseControllerProps, BaseControllerEvents, ControllerRootView } from "./base-controller";
+import { PageViewer } from "../components/pageviewer";
+import { PageViewerTitleBar } from "../components/pageviewer-titlebar";
+import { CustomNavigationBar, NavigationBarProps } from "../components/custom-navigation-bar";
+
+interface PageViewerControllerProps extends BaseControllerProps {
+  items: { controller: BaseController, title: string }[];
+  navBarProps?: NavigationBarProps;
+  index?: number;
+}
+
+export class PageViewerController extends BaseController {
+  protected _props: PageViewerControllerProps;
+  cviews: {
+    pageviewer: PageViewer;
+    titlebar: PageViewerTitleBar;
+    navbar: CustomNavigationBar;
+  }
+  constructor({ props, layout, events = {} }: {
+    props: PageViewerControllerProps;
+    layout?: (make: MASConstraintMaker, view: UIView) => void;
+    events?: BaseControllerEvents;
+  }) {
+    super({ props: {
+      id: props.id,
+      bgcolor: props.bgcolor
+    }, layout, events });
+    this._props = props;
+    this.cviews = {} as {
+      pageviewer: PageViewer;
+      titlebar: PageViewerTitleBar;
+      navbar: CustomNavigationBar;
+    };
+    this.cviews.pageviewer = new PageViewer({
+      props: {
+        page: this._props.index,
+        cviews: this._props.items.map(n => n.controller.rootView)
+      },
+      layout: (make, view) => {
+        make.left.right.bottom.inset(0)
+        make.top.equalTo(view.prev.bottom)
+      },
+      events: {
+        floatPageChanged: (cview, floatPage) => (this.cviews.titlebar.floatedIndex = floatPage)
+      }
+    });
+    this.cviews.titlebar = new PageViewerTitleBar({
+      props: {
+        items: this._props.items.map(n => n.title),
+        index: this._props.index
+      },
+      layout: $layout.fill,
+      events: {
+        changed: (cview, index) => this.cviews.pageviewer.scrollToPage(index)
+      }
+    });
+    this.cviews.navbar = new CustomNavigationBar({
+      props: {
+        ...this._props.navBarProps,
+        titleView: this.cviews.titlebar
+      }
+    });
+    this.rootView.views = [this.cviews.navbar, this.cviews.pageviewer]
+  }
+
+  get index() {
+    return this._props.index || 0
+  }
+
+  set index(num) {
+    this.cviews.titlebar.index = num
+    this.cviews.pageviewer.page = num
+    this._props.index = num
+  }
+}

package/controller/presented-page-controller.ts

@@ -0,0 +1,57 @@
+/** # CView PresentedPageController
+ * 
+ * ## Props
+ * 
+ * - presentMode?: number = 1
+ * - animated?: boolean = true
+ * - interactiveDismissalDisabled?: boolean = false
+ * - bgcolor?: UIColor = $color("secondarySurface")
+ * 
+ * ## 专用方法
+ * 
+ * - present() 在 `sheet.present()` 之后会先后执行 `load()` 和 `appear()`
+ * - dismiss()
+ * 
+ * ## 布局
+ * 此控制器的 layout 必定为 `$layout.fill`，无需自行设定
+ */
+
+import { BaseController, BaseControllerProps, BaseControllerEvents, ControllerRootView } from "./base-controller";
+import { Sheet } from "../components/sheet";
+
+interface PresentedPageControllerProps extends BaseControllerProps {
+  presentMode?: number;
+  animated?: boolean;
+  interactiveDismissalDisabled?: boolean;
+}
+
+export class PresentedPageController extends BaseController {
+  private _sheet: Sheet<ControllerRootView, UIView, UiTypes.ViewOptions>;
+  constructor({ props, layout, events }: {
+    props?: Partial<PresentedPageControllerProps>;
+    layout?: (make: MASConstraintMaker, view: UIView) => void;
+    events?: BaseControllerEvents;
+  } = {}) {
+    super({ props: {
+      id: props?.id
+    }, layout, events });
+    this._sheet = new Sheet<ControllerRootView, UIView, UiTypes.ViewOptions>({
+      presentMode: props?.presentMode || 1,
+      animated: props?.animated || true,
+      interactiveDismissalDisabled: props?.interactiveDismissalDisabled || false,
+      bgcolor: props?.bgcolor || $color("secondarySurface"),
+      cview: this.rootView,
+      dismissalHandler: () => this.remove()
+    });
+  }
+
+  present() {
+    if (this._sheet) this._sheet.present()
+    this.load()
+    this.appear()
+  }
+
+  dismiss() {
+    if (this._sheet) this._sheet.dismiss()
+  }
+}