jsbox-cview 1.3.4 → 1.4.0

package/components/alert/input-alert.ts

@@ -1,9 +1,3 @@
-/**
- * # CView InputAlert
- * 
- * 显示一个输入框提示
- */
-
 import {
   UIAlertActionStyle,
   UIAlertControllerStyle,
@@ -13,6 +7,18 @@ import {
 
 import { l10n } from "../../utils/l10n";
 
+/**
+ * 显示一个输入框提示
+ * 
+ * @param title 标题
+ * @param message 内容
+ * @param text 输入框默认文字
+ * @param placeholder 输入框占位符
+ * @param type 输入框类型
+ * @param secure 是否安全输入
+ * @param cancelText 取消按钮文字
+ * @param confirmText 确认按钮文字
+ */
 export function inputAlert({
   title = "",
   message = "",

package/components/alert/login-alert.ts

@@ -1,9 +1,3 @@
-/**
- * # CView LoginAlert
- * 
- * 显示一个登录输入框提示
- */
-
 import {
   UIAlertActionStyle,
   UIAlertControllerStyle,
@@ -13,6 +7,16 @@ import {
 
 import { l10n } from "../../utils/l10n";
 
+/**
+ * 显示一个登录输入框提示
+ * 
+ * @param title 标题
+ * @param message 内容
+ * @param placeholder1 输入框1的占位符
+ * @param placeholder2 输入框2的占位符
+ * @param cancelText 取消按钮文字
+ * @param confirmText 确认按钮文字
+ */
 export function loginAlert({
   title = "",
   message = "",
@@ -27,7 +31,7 @@ export function loginAlert({
   placeholder2?: string;
   cancelText?: string;
   confirmText?: string;
-  } = {}): Promise<{ username: string; password: string }> {
+} = {}): Promise<{ username: string; password: string }> {
   return new Promise((resolve, reject) => {
     const alertVC = new UIAlertController(
       title,

package/components/alert/plain-alert.ts

@@ -1,9 +1,3 @@
-/**
- * # CView PlainAlert
- * 
- * 显示一个文字提示
- */
-
 import {
   UIAlertActionStyle,
   UIAlertControllerStyle,
@@ -13,6 +7,15 @@ import {
 
 import { l10n } from "../../utils/l10n";
 
+/**
+ * 显示一个文字提示
+ * 
+ * @param title 标题
+ * @param message 内容
+ * @param cancelText 取消按钮文字
+ * @param confirmText 确认按钮文字
+ * @returns Promise
+ */
 export function plainAlert({
   title = "",
   message = "",

package/components/alert/uialert.ts

@@ -1,7 +1,3 @@
-/**
- * Alert的基础类
- */
-
 export const UIAlertActionStyle = {
   Default: 0,
   Cancel: 1,
@@ -33,6 +29,9 @@ export class UIAlertAction {
   }
 }
 
+/**
+ * Alert的基础类
+ */
 export class UIAlertController {
   title: string;
   message: string;

package/components/base.ts

@@ -1,5 +1,7 @@
+import { cvid } from '../utils/cvid';
+
 /**
- * # Base<T extends AllUIView, R extends UiTypes.AllViewOptions>
+ * 
  * 组件 Base 基类，用于创建自定义组件。CView 的所有子类都应该继承自 Base。
  * 
  * ## 属性
@@ -15,9 +17,6 @@
  * - 通过组件化的方式，将JSBox view的定义和实例绑定，使用起来更加方便
  * - 可以便利地创建自定义组件
  */
-
-import { cvid } from '../utils/cvid';
-
 export abstract class Base<T extends AllUIView, R extends UiTypes.AllViewOptions> {
   readonly id: string;
   private _view?: T;

package/components/custom-navigation-bar.ts

@@ -1,56 +1,3 @@
-/** 
- * # CView Custom NavigationBar
- * 
- * 仿制 navBar
- * 
- * ## features:
- * 
- * - 拥有隐藏、最小化、普通、扩展四种布局方式
- *   - 隐藏: 什么都不显示
- *   - 最小化: safeAreaHeight 为 25, 只显示 titleView, 若用 title, font 为\$font(14)
- *   - 普通: safeAreaHeight 为 50, 显示 titleView, leftBarButtonItems 或 popButton, rightBarButtonItems, 若用 title, font 为\$font("bold", 17)
- *   - 扩展: safeAreaHeight 为 100, 除上面的之外, 再显示一个 toolView
- * - 自动适应全面屏和非全面屏
- * 
- * ## Arguments
- * 
- * props:
- * 
- * - 读写 style: number 0, 1, 2, 3，指定布局
- * - 读写 title: string 但必须使用此种方案才可以在生成后写入，自动创建 Label 作为 titleView
- * - titleView: cview 自定义的 titleView
- * - popButtonEnabled: boolean 返回上一级的按钮，若为 true，则 leftBarButtonItems 忽略
- * - popButtonTitle: string 返回上一级的按钮标题
- * - popToRootEnabled: boolean popButton 是否可以长按返回到顶级
- * - leftBarButtonItems: cview[]
- *   | {symbol: string, handler: () => void, tintColor?: UIColor}[]
- *   | {title: string, handler: () => void, tintColor?: UIColor}[]
- *   | {image: UIImage, handler: () => void, tintColor?: UIColor}[]  
- *   如果用的是 cview，其布局将被重新指定，即不需要（也不能）指定布局。可以通过 cview.width 来指定应有的宽度，如果没有此属性，则宽度为 50  
- *   建议最多放两个
- * - rightBarButtonItems 定义同上，建议最多放两个
- * - toolView: cview 在 expanded 模式下才会显现的
- * - tintColor: UIColor 这将作用于 title, popButton, 自动创建的 barButton
- * - bgcolor: UIColor 如不设置，则自动使用 blur(style 10)，如果设置则没有 blur 效果
- * 
- * events:
- * 
- * - hidden: cview => void  hide()时执行
- * - minimized: cview => void  minimize()时执行
- * - restored: cview => void  restore()时执行
- * - expanded: cview => void  expand()时执行
- * - popHandler: cview => void  返回上一级时执行，需要popButtonEnabled
- * - popToRootHandler: cview => void  返回顶级时执行，需要popButtonEnabled和popToRootEnabled
- * - titleTapped: cview => void 点击标题时执行，需要使用title
- * 
- * methods:
- * 
- * - hide() 隐藏布局
- * - minimize() 最小化布局
- * - restore() 普通布局
- * - expand() 扩展布局
- */
-
 import { Base } from "./base";
 import { ContentView, Label, Button, Blur } from "./single-views";
 import { SymbolButton } from "./symbol-button";
@@ -126,6 +73,58 @@ interface NavigationBarCViews {
   separator?: ContentView;
 }
 
+/** 
+ * # CView Custom NavigationBar
+ * 
+ * 仿制 navBar
+ * 
+ * ## features:
+ * 
+ * - 拥有隐藏、最小化、普通、扩展四种布局方式
+ *   - 隐藏: 什么都不显示
+ *   - 最小化: safeAreaHeight 为 25, 只显示 titleView, 若用 title, font 为\$font(14)
+ *   - 普通: safeAreaHeight 为 50, 显示 titleView, leftBarButtonItems 或 popButton, rightBarButtonItems, 若用 title, font 为\$font("bold", 17)
+ *   - 扩展: safeAreaHeight 为 100, 除上面的之外, 再显示一个 toolView
+ * - 自动适应全面屏和非全面屏
+ * 
+ * ## Arguments
+ * 
+ * props:
+ * 
+ * - 读写 style: number 0, 1, 2, 3，指定布局
+ * - 读写 title: string 但必须使用此种方案才可以在生成后写入，自动创建 Label 作为 titleView
+ * - titleView: cview 自定义的 titleView
+ * - popButtonEnabled: boolean 返回上一级的按钮，若为 true，则 leftBarButtonItems 忽略
+ * - popButtonTitle: string 返回上一级的按钮标题
+ * - popToRootEnabled: boolean popButton 是否可以长按返回到顶级
+ * - leftBarButtonItems: cview[]
+ *   | {symbol: string, handler: () => void, tintColor?: UIColor}[]
+ *   | {title: string, handler: () => void, tintColor?: UIColor}[]
+ *   | {image: UIImage, handler: () => void, tintColor?: UIColor}[]  
+ *   如果用的是 cview，其布局将被重新指定，即不需要（也不能）指定布局。可以通过 cview.width 来指定应有的宽度，如果没有此属性，则宽度为 50  
+ *   建议最多放两个
+ * - rightBarButtonItems 定义同上，建议最多放两个
+ * - toolView: cview 在 expanded 模式下才会显现的
+ * - tintColor: UIColor 这将作用于 title, popButton, 自动创建的 barButton
+ * - bgcolor: UIColor 如不设置，则自动使用 blur(style 10)，如果设置则没有 blur 效果
+ * 
+ * events:
+ * 
+ * - hidden: cview => void  hide()时执行
+ * - minimized: cview => void  minimize()时执行
+ * - restored: cview => void  restore()时执行
+ * - expanded: cview => void  expand()时执行
+ * - popHandler: cview => void  返回上一级时执行，需要popButtonEnabled
+ * - popToRootHandler: cview => void  返回顶级时执行，需要popButtonEnabled和popToRootEnabled
+ * - titleTapped: cview => void 点击标题时执行，需要使用title
+ * 
+ * methods:
+ * 
+ * - hide() 隐藏布局
+ * - minimize() 最小化布局
+ * - restore() 普通布局
+ * - expand() 扩展布局
+ */
 export class CustomNavigationBar extends Base<UIView | UIBlurView, UiTypes.ViewOptions | UiTypes.BlurOptions> {
   _props: NavigationBarProps;
   _events: NavigationBarEvents;

package/components/dialogs/dialog-sheet.ts

@@ -1,16 +1,3 @@
-/**
- * # cview DialogSheet
- * 
- * dialog所需要的sheet
- * 
- * ## 参数
- * - `title` 标题
- * - `cview` CView
- * - `doneHandler` 完成时的回调
- * - `presentMode` presentMode
- * - `bgcolor` 背景颜色
- */
-
 import { Sheet } from "../sheet";
 
 import { CustomNavigationBar } from "../custom-navigation-bar";
@@ -18,8 +5,16 @@ import { l10n } from "../../utils/l10n";
 import { ContentView } from "../single-views";
 import { Base } from "../base";
 
-
-export class DialogSheet extends Sheet<ContentView, UIView, UiTypes.ViewOptions>{
+/**
+ * dialog所需要的sheet
+ * 
+ * @param title 标题
+ * @param cview 内容视图
+ * @param doneHandler 完成时的回调
+ * @param presentMode 显示模式
+ * @param bgcolor 背景颜色
+ */
+export class DialogSheet extends Sheet<ContentView, UIView, UiTypes.ViewOptions> {
   _props: {
     title: string;
     cview: Base<any, any>;

package/components/dialogs/form-dialog.ts

@@ -1,13 +1,11 @@
-/**
- * # CView Form Dialog
- * 
- * 显示一个表单
- */
-
 import { PreferenceListView, PreferenceSection } from "../static-preference-listview";
 import { DialogSheet } from "./dialog-sheet";
 
-
+/**
+ * 显示一个表单
+ * @param sections 表单分组, 请参考`PreferenceListView`中的`PreferenceSection`
+ * @param title 标题
+ */
 export function formDialog({ sections, title }: { sections: PreferenceSection[]; title: string }) {
   const view = new PreferenceListView({ sections });
   const sheet = new DialogSheet({

package/components/dialogs/list-dialog.ts

@@ -1,12 +1,15 @@
-/**
- * # CView List Dialog
- * 
- * 显示一个列表以供选择
- */
-
 import { DialogSheet } from './dialog-sheet';
 import { List } from '../single-views';
 
+/**
+ * 显示一个列表以供选择
+ * 
+ * @param items 选项
+ * @param multiSelectEnabled 是否允许多选
+ * @param value 默认选中的选项
+ * @param values 默认选中的选项, 配合multiSelectEnabled使用
+ * @param title 标题
+ */
 export function listDialog({ items, multiSelectEnabled, value, values = [], title }: {
   items: string[];
   multiSelectEnabled?: boolean;

package/components/dialogs/text-dialog.ts

@@ -1,12 +1,13 @@
-/**
- * # CView Text Dialog
- * 
- * 返回一个Promise用于输入文本
- */
-
 import { Text } from "../single-views";
 import { DialogSheet } from "./dialog-sheet";
 
+/**
+ * 返回一个Promise用于输入文本
+ * @param title 标题
+ * @param text 初始文本
+ * @param placeholder 占位符
+ * @param editable 是否可编辑
+ */
 export function textDialog({ title, text = "", placeholder = "", editable = true }: {
   title: string;
   text?: string;

package/components/dynamic-itemsize-matrix.ts

@@ -1,3 +1,28 @@
+import { Base } from './base';
+import { Matrix } from "./single-views";
+
+interface DynamicItemSizeMatrixProps extends UiTypes.MatrixProps {
+  fixedItemHeight: number;
+  minItemWidth: number;
+  maxColumns: number;
+  spacing: number;
+  maxTotalWidth: number;
+  dynamicHeightEnabled?: boolean;
+}
+
+interface DynamicItemSizeMatrixEvents extends UiTypes.MatrixEvents {
+  itemHeight?: (width: number) => number;
+  heightChanged?: (sender: DynamicItemSizeMatrix, height: number) => void;
+}
+
+interface DynamicItemSizeMatrixPropsPartial extends UiTypes.MatrixProps {
+  fixedItemHeight?: number;
+  minItemWidth?: number;
+  maxColumns?: number;
+  spacing?: number;
+  dynamicHeightEnabled?: boolean;
+}
+
 /**
  * # CView Dynamic ItemSize Matrix
  * 
@@ -40,32 +65,6 @@
  * 方法:
  * - heightToWidth(width) 计算特定width时的应有的高度
  */
-
-import { Base } from './base';
-import { Matrix } from "./single-views";
-
-interface DynamicItemSizeMatrixProps extends UiTypes.MatrixProps {
-  fixedItemHeight: number;
-  minItemWidth: number;
-  maxColumns: number;
-  spacing: number;
-  maxTotalWidth: number;
-  dynamicHeightEnabled?: boolean;
-}
-
-interface DynamicItemSizeMatrixEvents extends UiTypes.MatrixEvents {
-  itemHeight?: (width: number) => number;
-  heightChanged?: (sender: DynamicItemSizeMatrix, height: number) => void;
-}
-
-interface DynamicItemSizeMatrixPropsPartial extends UiTypes.MatrixProps {
-  fixedItemHeight?: number;
-  minItemWidth?: number;
-  maxColumns?: number;
-  spacing?: number;
-  dynamicHeightEnabled?: boolean;
-}
-
 export class DynamicItemSizeMatrix extends Base<UIView, UiTypes.ViewOptions> {
   private _props: DynamicItemSizeMatrixProps;
   private _events: DynamicItemSizeMatrixEvents;

package/components/dynamic-preference-listview.ts

@@ -1,32 +1,5 @@
-/**
- * # cview PreferenceListView_dynamic
- * 
- * 便捷的设置列表实现. 样式以及功能均以 PreferenceListView_static 为准.
- * 
- * 优势在于:
- * 
- * - 可以实现 sections 重新写入.
- * 
- * 劣势在于:
- * 
- * - 由于每个 cell 不能单独布局, 因此标题和内容的长度无法动态调整, 在两者都比较短的情况下没有问题, 长了布局可能会重叠.
- * - 不能真正实现 selectable 为 false, 分割线仍然会闪动
- * 
- * 为了缓解上面的问题, 让修改布局无需调整源代码, 增加下列 props:
- * 
- * - stringLeftInset?: number = 120 将同时作用于 string, number, integer, list, 但是由于后三者内容可控, 可视为只作用于 string
- * - infoAndLinkLeftInset?: number = 120 作用于 info, link
- * - sliderWidth?: number = 200 作用于 slider
- * - tabWidth?: number = 200 作用于 tab
- *   注意以上的修改是应用于 template, 而不是应用于单个 cell 的
- * 
- * 独特方法:
- * 
- * - cview.sections = sections 可以写入新的 sections
- */
-
 import { Base } from "./base";
-import { 
+import {
   PreferenceSection,
   PrefsRow,
   PrefsRowString,
@@ -43,7 +16,7 @@ import {
   PrefsRowAction,
   selectableTypes,
   excludedTypes
- } from "./static-preference-listview";
+} from "./static-preference-listview";
 
 
 interface CunstomProps extends UiTypes.ListProps {
@@ -60,8 +33,33 @@ interface RequiredCunstomProps extends UiTypes.ListProps {
   tabWidth: number;
 }
 
-
-export class DynamicPreferenceListView extends Base<UIListView, UiTypes.ListOptions>{
+/**
+ * # cview PreferenceListView_dynamic
+ * 
+ * 便捷的设置列表实现. 样式以及功能均以 PreferenceListView_static 为准.
+ * 
+ * 优势在于:
+ * 
+ * - 可以实现 sections 重新写入.
+ * 
+ * 劣势在于:
+ * 
+ * - 由于每个 cell 不能单独布局, 因此标题和内容的长度无法动态调整, 在两者都比较短的情况下没有问题, 长了布局可能会重叠.
+ * - 不能真正实现 selectable 为 false, 分割线仍然会闪动
+ * 
+ * 为了缓解上面的问题, 让修改布局无需调整源代码, 增加下列 props:
+ * 
+ * - stringLeftInset?: number = 120 将同时作用于 string, number, integer, list, 但是由于后三者内容可控, 可视为只作用于 string
+ * - infoAndLinkLeftInset?: number = 120 作用于 info, link
+ * - sliderWidth?: number = 200 作用于 slider
+ * - tabWidth?: number = 200 作用于 tab
+ *   注意以上的修改是应用于 template, 而不是应用于单个 cell 的
+ * 
+ * 独特方法:
+ * 
+ * - cview.sections = sections 可以写入新的 sections
+ */
+export class DynamicPreferenceListView extends Base<UIListView, UiTypes.ListOptions> {
   _defineView: () => UiTypes.ListOptions;
   private _sections: PreferenceSection[];
   private _props: RequiredCunstomProps;

package/components/dynamic-rowheight-list.ts

@@ -1,3 +1,11 @@
+import { Base } from './base';
+
+interface DynamicRowHeightListProps extends Omit<UiTypes.ListProps, "data" | "template"> { }
+interface DynamicRowHeightListEvents extends Omit<UiTypes.ListEvents, "rowHeight"> { }
+interface DynamicRowHeightListCView extends Base<any, any> {
+  heightToWidth: (width: number) => number;
+}
+
 /** 
  * # cview Dynamic RowHeight List
  * 
@@ -13,19 +21,10 @@
  * 
  * 除了 props.data, props.template 和 events.rowHeight 不可用，其他均和 list 一致
  */
-
-import { Base } from './base';
-
-interface DynamicRowHeightListProps extends Omit<UiTypes.ListProps, "data" | "template"> {}
-interface DynamicRowHeightListEvents extends Omit<UiTypes.ListEvents, "rowHeight"> {}
-interface DynamicRowHeightListCView extends Base<any, any> {
-  heightToWidth: (width: number) => number;
-}
-
-export class DynamicRowHeightList extends Base<UIListView, UiTypes.ListOptions>{
+export class DynamicRowHeightList extends Base<UIListView, UiTypes.ListOptions> {
   _defineView: () => UiTypes.ListOptions;
   constructor({ sections, rows, props, layout, events }: {
-    sections?: {title: string, rows: DynamicRowHeightListCView[]}[];
+    sections?: { title: string, rows: DynamicRowHeightListCView[] }[];
     rows?: DynamicRowHeightListCView[];
     props: DynamicRowHeightListProps;
     layout: (make: MASConstraintMaker, view: UIListView) => void;

package/components/enhanced-imageview.ts

@@ -1,3 +1,7 @@
+import { Base } from "./base";
+import { Scroll } from "./single-views";
+import { cvid } from "../utils/cvid";
+
 /**
  * 此组件是为了加强 imageView，实现以下目的：
  *  1. 点击实现上下翻页
@@ -15,10 +19,6 @@
  * upperLocationTouched: (sender: EnhancedImageView) => void, 上半部分被点击
  * lowerLocationTouched: (sender: EnhancedImageView) => void, 下半部分被点击
  */
-import { Base } from "./base";
-import { Scroll } from "./single-views";
-import { cvid } from "../utils/cvid";
-
 export class EnhancedImageView extends Base<UIView, UiTypes.ViewOptions> {
   private _props: { src: string; maxZoomScale: number };
   private _scroll: Scroll;