@aamasri/dialog 中文文档教程

发布于 3年前 浏览 29 项目主页 更新于 3年前

Dialog

一个灵活的 javascript 弹出对话框。

dialog.open({
        title: 'Dialog Title',
        source: 'Body content can be (HTML, CSS selector, DOM element, or URL)',
    }).then(...);


Features

  • Easy to use.
  • Lazy loading (3kb initial page load).
  • Usable as a webpack/ES6 module or a pre-built browser bundle.
  • Handles multiple programming scenarios and content sources.
  • Simple HTML structure and easy custom styling using CSS3 variables.
  • Dialogs can be 'modal', and/or can be layered on top of each other.
  • Implements the 'Promise' interface, allowing sequential notifications.



Demo

试试我



Installation

Dialog 是一个为 ES6 模块系统构建并使用它的 javascript 包,但它也作为预构建提供,缩小的浏览器包(在这个包的“dist”文件夹中)。


Browser

  1. Download & copy this package's "dist" folder into your web server's public folder eg. public/js/dist/*.
  2. Rename "dist" to "dialog" eg. public/js/dialog
  3. Load the dialog script at the end of your web page (before the closing body tag) like this:
<body>
    ...

    <script src="/js/dialog/dialog.js"></script>
</body>
</html>
  1. When the browser loads, dialog will be attached to the browser's global window object. Use it anywhere in your scripts like this:
<button>Target</button>

<script>
    dialog.open();          // Display the dialog cheat sheet

    ...

    dialog.closeLast();     // close the on-top dialog

    ...

    dialog.closeAll();

</script>


ES6 module

使用 npm 将对话框包安装到您的项目中:

$ cd to/your/project
$ npm install @aamasri/dialog

然后在项目的 ES6 模块中导入并使用它:

Static import

import dialog from 'dialog';

function helloWorld() {
    dialog.open({ title: 'Greetings', source: 'Hello World' });
}

Dynamic import

利用 Webpack 的按需(惰性)加载和代码拆分:

import(/* webpackChunkName: "dialog" */ 'dialog').then((dialog) => {
    dialog.closeAll();

    dialog.open(...
});



Dialog Functions

dialog.open({ .. }).then((dialogElement) => { .. })    // create a new dialog
dialog.close(dialogElement)                            // close a specific dialog instance
dialog.closeAll()                                      // close all dialogs
dialog.closeLast()                                     // close the on-top dialog



Dialog.open Options

这是另一个具有不同选项的示例; 例如。 加载/显示 URL 返回的 HTML 片段:

    dialog.open({ 
             title: `${userName}'s User Profile`, 
             source: userUrl,
             fragment: '.contact-info'
             modal: true,
             onClose: function() { alert: `Don't hesitate to call ${userName}!`; }
         }).then( function(dialogElement) {
             console.log('fyi the contact info dialog just launched');

             window.setTimeout( function() {
                dialog.close(dialogElement);
             }, 10000);
         });



以下是 dialog.open 选项的完整列表:

OptionTypeDescriptionDefault
titlestring | undefineddialog title, else source element title attribute"Missing Title"
sourcestring | object | undefinedthe content source: html content, selector, url, or elementusage instructions
fragment**string | undefinedselector by which to extract a portion of the source HTML
modal**boolean | undefineddialog background blurring & dimmingfalse
iframeboolean | undefinedif the source is a url, whether to load it in an iFrame. Adds a full-screen link.false
fullscreenUrlstring | undefinedforces a full-screen button (or for case that the fullscreen url differs from the source url)false
replaceboolean | undefinedwhether to close any existing dialogs or layer upfalse
persistentboolean | undefinedwhether ESC key or blur events close the dialogfalse
onClosefunction | string | undefinedcallback function or eval(string) to execute after dialog dismissed
classesstring | undefinedadditional classes to apply to the dialog container element
attributesstring | undefinedattributes to apply to the dialog container element eg. 'data-ignore-events="true"'

Notes

  1. To create a chrome-less dialog (ie. one with no padding or header, where the specified content completely fills the dialog box), simply omit the title option.
  2. If loading a URL fails then it may be due to a CORS issue (if it's for a different domain).


** 建议在加载返回 FULL HTML 文档的 URL 时使用“iframe”或“fragment”选项。
这是因为没有 iframe 就不能嵌套 HTML 文档; 不指定“iframe”或“fragment”选项将导致对话框重新加载 iframe 中的 URL(这可能会不必要地增加对话框加载时间)。



Dialog Styling

对话框的默认 CSS 样式可以很容易地设置主题以适合您的应用程序。 在您的 CSS :root 或 body 范围内更改任何这些默认样式:

:root {
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBackground: #FFF;
    --dialogBorder: 1px solid #DDD;
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBorderRadius: 4px;
    --dialogFontFamily: Helvetica, Verdana, sans-serif;
    --dialogLineHeight: 1.8;
    --dialogTitleSize: 1.3rem;
    --dialogTitleColor: #888;
    --dialogTitleWeight: bold;
    --dialogModalBackground: rgba(170, 170, 170, 0.3);
    --dialogModalOpacity: 0.3;




Package Management

对话框支持 npm 在名称 @aamasri/dialog 下。

NPM

$ npm install @aamasri/dialog --save


Dependencies

Dialog 依赖于 2 个外部包:

  1. jquery
  2. animejs
  3. @aamasri/dom-utils

这些依赖项被捆绑(作为单独的预构建“块”)在此包的“dist”文件夹中。

调用 dialog() 函数将在运行时动态加载这些依赖项(如果页面上尚不存在这些脚本)并将它们添加到全局窗口对象中。

如果您的页面已经加载了 jQuery、animejs 或 @aamasri/dom-utils 包,dialog 将使用它们。



Manual release steps

  1. Increment the "version" attribute of `package.json`.
  2. Re-build the browser output bundle...
    npm run build-production
    ...and observe that webpack completed with no errors.
  3. Test the bundle by loading page: "dist/index.html" in a browser.
  4. Commit
    git commit -a -m "Release version x.x.x - description"
  5. Tag the commit with it's version number
    git tag x.x.x
  6. Change the "latest" tag pointer to the latest commit & push:
    git tag -f latest
    git push origin master :refs/tags/latest
    git push origin master --tags
  7. Publish to npm registry:
    npm publish


Authors

Dialog

A flexible javascript popup dialog.

dialog.open({
        title: 'Dialog Title',
        source: 'Body content can be (HTML, CSS selector, DOM element, or URL)',
    }).then(...);


Features

  • Easy to use.
  • Lazy loading (3kb initial page load).
  • Usable as a webpack/ES6 module or a pre-built browser bundle.
  • Handles multiple programming scenarios and content sources.
  • Simple HTML structure and easy custom styling using CSS3 variables.
  • Dialogs can be 'modal', and/or can be layered on top of each other.
  • Implements the 'Promise' interface, allowing sequential notifications.



Demo

Try me



Installation

Dialog is a javascript package built for and using the ES6 module system, but it's also provided as a pre-built, minified browser package (in this package's "dist" folder).


Browser

  1. Download & copy this package's "dist" folder into your web server's public folder eg. public/js/dist/*.
  2. Rename "dist" to "dialog" eg. public/js/dialog
  3. Load the dialog script at the end of your web page (before the closing body tag) like this:
<body>
    ...

    <script src="/js/dialog/dialog.js"></script>
</body>
</html>
  1. When the browser loads, dialog will be attached to the browser's global window object. Use it anywhere in your scripts like this:
<button>Target</button>

<script>
    dialog.open();          // Display the dialog cheat sheet

    ...

    dialog.closeLast();     // close the on-top dialog

    ...

    dialog.closeAll();

</script>


ES6 module

Install the dialog package into your project using npm:

$ cd to/your/project
$ npm install @aamasri/dialog

Then import and use it in your project's ES6 modules:

Static import

import dialog from 'dialog';

function helloWorld() {
    dialog.open({ title: 'Greetings', source: 'Hello World' });
}

Dynamic import

Leveraging Webpack's on-demand (lazy) loading and code-splitting:

import(/* webpackChunkName: "dialog" */ 'dialog').then((dialog) => {
    dialog.closeAll();

    dialog.open(...
});



Dialog Functions

dialog.open({ .. }).then((dialogElement) => { .. })    // create a new dialog
dialog.close(dialogElement)                            // close a specific dialog instance
dialog.closeAll()                                      // close all dialogs
dialog.closeLast()                                     // close the on-top dialog



Dialog.open Options

Here's another example with different options; eg. to load/display a fragment of the HTML returned by a URL:

    dialog.open({ 
             title: `${userName}'s User Profile`, 
             source: userUrl,
             fragment: '.contact-info'
             modal: true,
             onClose: function() { alert: `Don't hesitate to call ${userName}!`; }
         }).then( function(dialogElement) {
             console.log('fyi the contact info dialog just launched');

             window.setTimeout( function() {
                dialog.close(dialogElement);
             }, 10000);
         });



Here's the full list of dialog.open options:

OptionTypeDescriptionDefault
titlestring | undefineddialog title, else source element title attribute"Missing Title"
sourcestring | object | undefinedthe content source: html content, selector, url, or elementusage instructions
fragment**string | undefinedselector by which to extract a portion of the source HTML
modal**boolean | undefineddialog background blurring & dimmingfalse
iframeboolean | undefinedif the source is a url, whether to load it in an iFrame. Adds a full-screen link.false
fullscreenUrlstring | undefinedforces a full-screen button (or for case that the fullscreen url differs from the source url)false
replaceboolean | undefinedwhether to close any existing dialogs or layer upfalse
persistentboolean | undefinedwhether ESC key or blur events close the dialogfalse
onClosefunction | string | undefinedcallback function or eval(string) to execute after dialog dismissed
classesstring | undefinedadditional classes to apply to the dialog container element
attributesstring | undefinedattributes to apply to the dialog container element eg. 'data-ignore-events="true"'

Notes

  1. To create a chrome-less dialog (ie. one with no padding or header, where the specified content completely fills the dialog box), simply omit the title option.
  2. If loading a URL fails then it may be due to a CORS issue (if it's for a different domain).


** it is recommended to use the "iframe" or "fragment" options when loading a URL that returns a FULL HTML document.
This is because HTML documents cannot be nested without an iframe; not specifying the "iframe" or "fragment" option will cause the dialog to reload the URL in an iframe (which may unnecessarily increase the dialog load time).



Dialog Styling

The dialog's default CSS styles may easily be themed to fit your application. Change any of these default styles in your CSS :root or body scope:

:root {
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBackground: #FFF;
    --dialogBorder: 1px solid #DDD;
    --dialogBoxShadow: 0 0 28px #CCC;
    --dialogBorderRadius: 4px;
    --dialogFontFamily: Helvetica, Verdana, sans-serif;
    --dialogLineHeight: 1.8;
    --dialogTitleSize: 1.3rem;
    --dialogTitleColor: #888;
    --dialogTitleWeight: bold;
    --dialogModalBackground: rgba(170, 170, 170, 0.3);
    --dialogModalOpacity: 0.3;




Package Management

Dialog supports npm under the name @aamasri/dialog.

NPM

$ npm install @aamasri/dialog --save


Dependencies

Dialog depends on 2 external packages:

  1. jquery
  2. animejs
  3. @aamasri/dom-utils

These dependencies are bundled (as separate pre-built 'chunks') in this package's "dist" folder.

Invoking the dialog() function will dynamically load these dependencies at run-time (if these scripts don't already exist on the page) and they'll be added to the global window object.

If your page already loads the jQuery, animejs, or @aamasri/dom-utils packages, dialog will use them instead.



Manual release steps

  1. Increment the "version" attribute of `package.json`.
  2. Re-build the browser output bundle...
    npm run build-production
    ...and observe that webpack completed with no errors.
  3. Test the bundle by loading page: "dist/index.html" in a browser.
  4. Commit
    git commit -a -m "Release version x.x.x - description"
  5. Tag the commit with it's version number
    git tag x.x.x
  6. Change the "latest" tag pointer to the latest commit & push:
    git tag -f latest
    git push origin master :refs/tags/latest
    git push origin master --tags
  7. Publish to npm registry:
    npm publish


Authors

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文