Skip to content
/ zz Public

zz is a javascript calendar library that runs on the browser. zz 是一個以 js 撰寫的日曆庫,可運行在瀏覽器上。

License

Notifications You must be signed in to change notification settings

jzovvo/zz

Repository files navigation

ZZ

NPM version GITHUB LICENSE NPM size GITHUB issues GITHUB TOP LAN

zz is a javascript calendar library that runs on the browser.

Table of Contents

Features

  • Compare before switching months
  • Only manipulate the DOM with differences
  • Provides many customization options and life cycle functions
  • Use plug-in mode to maintain the scalability of this library, and have the effect of importing on demand

Installation

npm

npm install @jyunzn/zz
  • commonJS

    const zz = require("@jyunzn/zz");
  • ES module

    import zz from "@jyunzn/zz";

CDN

  • unpkg

    <script src="https://unpkg.com/@jyunzn/zz"></script>
  • jsdelivr ( npm )

    <script src="https://cdn.jsdelivr.net/npm/@jyunzn/zz"></script>
  • jsdelivr ( gh )

    <script src="https://cdn.jsdelivr.net/gh/jyunzn/zz/dist/zz.min.js"></script>

Example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <!-- set some style -->
    <link href="https://cdn.jsdelivr.net/gh/jyunzn/zz@0.0.0-alpha.3/examples/default.min.css" rel="stylesheet"/>
    <style>
      .caledar {
        border: 1px solid black;
        position: relative;
        padding: 50px 30px;
        box-sizing: border-box;
      }

      .prev-btn.p_btn1 {
        left: 100px;
      }

      .next-btn.n_btn1 {
        right: 100px;
      }
    </style>
    <script src="https://kit.fontawesome.com/36ce20503e.js" crossorigin="anonymous"></script>

    <!-- step1. import the module -->
    <script src="https://unpkg.com/@jyunzn/zz"></script>
  </head>
  <body>
    <!-- step2. Create a container -->
    <div class="caledar"></div>
    <script>
      // step3. call zz function and mount into the container
      //        If you want to use custom options,
      //        you can set it in the first parameter in the zz function
      zz(/*{

      // - Set options

      cmz_quan: 12,
      cmz_ymStart: '2020-01',
      cmz_ymPos: 'my',
      cmz_yNames: { 2020: '貳零貳零', 2021: '貳零貳壹' },
      cmz_mNames: { 
        1: 'Jan', 2: 'Feb', 3: 'Mar', 4: 'Apr', 
        5: 'May', 6: 'Jun', 7: 'Jul', 8: 'Aug',
        9: 'Sep', 10: 'Oct', 11: 'Nov', 12: 'Dec'
      },
      cmz_wMarks: {
        sun: 'S',
        mon: 'M',
        tue: 'T',
        wed: 'W',
        thu: 'T',
        fri: 'F',
        sat: 'S'
      },
      cmz_swBtns: [
        ['i', { direct: 'prev', step: 12, class: "prev-btn p_btn12" }, '<<<<<'],
        // use font-awesome
        ['i', { direct: 'prev', step: 1, class: "prev-btn p_btn1 fas fa-angle-left" }, ''],
        ['i', { direct: 'next', step: 1, class: "next-btn n_btn1" }, '>'],
        // set children, children can always be nested!
        ['i', { direct: 'next', step: 12, class: "next-btn n_btn12" }, [
          '>',
          ['i', { style: 'color: pink;' }, '>'],
          ['span', {}, [
            '>',
            ['i', { style: { color: 'skyblue' }}, '>']
          ]]
        ]]
      ],
      
      cls_year: 'my-year',
      cls_month: 'my-month',

      // - Set life cycle

      onPreved: (...args) => { console.log('onPreved', ...args) }, 
      onNexted: (...args) => { console.log('onNexted', ...args) },

      onBeforeCreate: (...args) => { console.log('onBeforeCreate', ...args) },
      onCreated: (...args) => { console.log('onCreated', ...args) },
      onBeforeMount: (...args) => { console.log('onBeforeMount', ...args) },
      onMounted: (...args) => { console.log('onMounted', ...args) },
      onBeforeUnmount: (...args) => { console.log('onBeforeUnmount', ...args) },
      onUnmounted: (...args) => { console.log('onUnmounted', ...args) }
    }*/).mount(".caledar");
    </script>
  </body>
</html>

Options

class options

  • All customizable class name settings
  • If you need to set more than two class names, please separate them with spaces, such as 'apple banana'
option default
cls_ymContainer 'ym-container'
cls_monthWrap 'month-wrap'
cls_monthHeader 'month-header'
cls_monthContent 'month-content'
cls_weekMarkWrap 'week-mark-wrap'
cls_weekMark 'week-mark'
cls_w4Content 'w-4'
cls_w5Content 'w-5'
cls_w6Content 'w-6'
cls_year 'year'
cls_month 'month'
cls_week 'week'
cls_date 'date'
cls_empFDate 'empty-f'
cls_empBDate 'empty-b'
cls_passYear 'pass-y'
cls_passMonth 'pass-m'
cls_passWeek 'pass-w'
cls_passDate 'pass-d'
cls_passEmpFDate 'pass-emp-f'
cls_passEmpBDate 'pass-emp-b'
cls_unPassYear 'unpass-y'
cls_unPassMonth 'unpass-m'
cls_unPassWeek 'unpass-w'
cls_unPassDate 'unpass-d'
cls_unPassEmpFDate 'unpass-emp-f'
cls_unPassEmpBDate 'unpass-emp-b'
cls_curDate 'cur-d'
cls_curMonth 'cur-m'
cls_curYear 'cur-y'
cls_curWeek 'cur-w'

tag options

  • All customizable label settings
  • value: HTML Tag | SVG Tag | Custom Element Name( The name must be kebab-case )
option default
tag_ymContainer 'div'
tag_monthWrap 'div'
tag_monthHeader 'div'
tag_monthContent 'div'
tag_weekMarkWrap 'ul'
tag_weekMark 'li'
tag_year 'span'
tag_month 'span'
tag_week 'ul'
tag_date 'li'
tag_empFDate 'li'
tag_empBDate 'li'

other options

option default description
cmz_quan 1

Number of calendars

type: Number

cmz_yNames null

Name the year

  • Type: Object
  • syntax: { year: name }
  • Usage: { 2020: '貳零貳零', 2021: '貳零貳壹' }
cmz_mNames

{
  1: 'January', 
  2: 'February', 
  3: 'March', 
  4: 'April', 
  5: 'May', 
  6: 'June', 
  7: 'July', 
  8: 'August', 
  9: 'Septemper', 
  10: 'October', 
  11: 'November', 
  12: 'December'
}       

Name the month

  • Type: Object
  • Syntax: { month: name }
  • Usage: { 1: 'JAN', 2: 'FEB' }
cmz_wMarks

{ 
  sun: 'Su',
  mon: 'Mo',
  tue: 'Tu',
  wed: 'We',
  thu: 'Th',
  fri: 'Fr',
  sat: 'Sa'
}       

Name the day of the week marker

  • Type: Object
  • Syntax: { mark-key: name }
  • mark-key: sun | mon | tue | wed | thu | fri | sat
  • Usage: { sun: 'Sunday', mon: 'Monday' }
cmz_ymStart Current month

Leftmost calendar month

  • Type: String
  • Syntax: 'yyyy-mm'
  • Usage: '2018-07'
cmz_ymPos ym

Relative position of year and month,

Value: 'ym' | 'my'

cmz_swBtns

[
  ['i', 
    { 
      direct: 
      "prev", 
      class: 'prev-btn', 
      step: dSwBtnStep 
    }, 
  '<'],
  ['i', 
    { 
      direct: "next", 
      class: 'next-btn', 
      step: dSwBtnStep 
    }, 
  '>']
]       

Button to switch month,Each top button setting represents a whole button

  • Type: Array<array>
  • Syntax: [[Tag name, Tag props, Children], [switch Btn Setting], ...]

    • Tag name:

      • Type: String
      • Value: HTML Tag | SVG Tag | Custom Element Name( The name must be kebab-case )
    • Tag props:

      • Type: Object
      • Value:

        1. All the attributes you want to add to the label.
        2. The style attribute supports Object writing, and the key must be converted from kebab-case to lower camel case
        3. There must be at least one direct attribute to indicate that the button is 'next' or 'prev'.
        4. By default, the button switching month is one month. If you want to set the number of months, you can set the step attribute here
    • Children:

      • Type: String | Array<array>
      • Syntax: [[Tag name, Tag props, Children], child2, ...] | text
      • Value:

        • String: If you only need a simple text, then just use String directly
        • Array: If you need to use tags, then use array to set each tag

          1. Similar to the top-level setting
          2. the difference is that prop does not need to write direct, the direction and number of steps of this button depend on the top-level setting
          3. And if there is no property to be set, the second parameter can be null
          4. Another difference is that the string is accepted in the array, and it will be added as a node of the text

Life Cycle

The life cycle architecture refers to VueJS, so the trigger timing is similar to the life cycle of VueJS

hook description
onBeforeCreate
  • Timing: After initializing options, before creating DOM
  • Parameter: options
onCreated
  • Timing: After all DOMs are created
  • Parameter: { opts, ymData, pointers, doms }
onBeforeMount
  • Timing: After calling the mount function, before mounting to the container
  • Parameter: { opts, ymData, pointers, doms }
onMounted
  • Timing: After mounting on the container
  • Parameter: { opts, ymData, pointers, doms }
onBeforeUnmount
  • Timing: After calling the unmount function, before unmount from the container
  • Parameter: { opts, ymData, pointers, doms }
onUnmounted
  • Timing: After unmount on the container
onPreved
  • Timing: Click the prev button
  • Parameter: { doms, diffMs, opts, step, ymData, pointers }
onNexted
  • Timing: Click the next button
  • Parameter: { doms, diffMs, opts, step, ymData, pointers }
  • Parameter Description:

    • opts: options
    • ymData: { todayInfo, ymCache }

      • todayInfo: Today's year, month and day
      • ymCache: All created year and month data, including:

        • days: Number of days in the month
        • weeks: Number of weeks in the month
        • firstDay: The day of the week of the first day of the month, 0 is Sunday
        • lastDay: The day of the week of the last day of the month, 0 is Sunday
        • ymStatus: The relationship between the year and month relative to the current year and month

          1. -1 means the past, 0 means the present, 1 means the future
          2. If it is a month other than the current month ( month !== 0 ), the values ​​of dStatus and wStatus are both null
          3. If it is the current month ( month === 0 ), the value of dStatus is today’s date, and the value of wStatus is the number of weeks in the current month.
    • pointers:

      1. Year and month data at the far left and right
      2. pL is the left, pR is the right
    • doms: Dom of all parts created

      • swBtnDs: Button to switch months
      • ymCD: Containers for all months
      • ymDs: Dom for each month

        • mWD: month wrap dom
        • mHD: month header dom
        • mCD: month content dom
        • yD: year dom
        • mD: month dom
        • wDs: week doms
        • wMD: week mark dom
        • dDs: day doms
        • empFDDs: Empty dom before date
        • empBDDs: Empty dom after date
    • diffMs: Compare all the months that will change, the difference data before and after the change

      • beforeYM: Month before change
      • nextYM: Month after change
      • beforeYMCache: Month data before the change
      • nextYMCache: Month data after the change
      • diffResult:

        • calcWs Week difference
        • calcDs Difference in days
        • calcFD The first day of the week difference
        • calcLD The last day of the week difference
        • statusChange Does the status of the year and month make a difference

Methods

The zz function will return an object with mount and unmount methods

function description
mount Mount the dom created by the zz function to the specified container, Accepts a selectors parameter
unmount Unmount the calendar mounted in the container

Plugins

  • The plug-in mode of zz also refers to VueJS,
  • The zz object has a use function. The plugin can be installed by passing the plugin into the use parameter.
  • The plug-in object must have an install method

usage

const plugin = { install() {} };
zz.use(plugin);

plugin list

plugin description
zzsper ZZ Single Picker, provides the function of selecting a single day
zzrper ZZ Range Picker, provides the function of selecting the range of days

License

MIT

About

zz is a javascript calendar library that runs on the browser. zz 是一個以 js 撰寫的日曆庫,可運行在瀏覽器上。

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published