夕水

Posted on Nov 18

ew-message: A Simple Yet Powerful Message Plugin for Web Applications

Introducing

If you're looking for a lightweight and customizable message plugin for your web application, ew-message could be the perfect solution. Encapsulated in TypeScript and designed for modern web development, this message plugin enables you to display informative, success, warning, or error messages with ease. In this article, we'll guide you through the installation process, how to use the plugin, and its various configuration options to tailor it to your needs.

What is ew-message?

ew-message is a message plugin built on TypeScript that allows you to display customizable messages in your web application. Whether you want to show simple information, success alerts, warning messages, or error notifications, ew-message provides a clean and efficient way to present these messages with animations, icons, and customizable duration.

Key Features

Customizable Message Types: Easily show info, success, warning, or error messages.
Custom Animations: Add or remove animations such as fade-in and fade-out for smooth transitions.
Icon Support: Display different icons based on the message type, or add custom icons.
Close Button: Optional close button to allow users to dismiss the message.
Custom Duration: Configure how long the message stays on the screen before it disappears.
Flexible Positioning: Customize the position of messages on the screen, including the ability to center them.

Installation

To get started, you'll need to install ew-message into your project. You can either use npm or yarn to install it as a development dependency.

Using npm:

npm install ew-message --save-dev

Using yarn:

yarn add ew-message

Once installed, you can start using the plugin in your project.

Importing the Plugin

You can import ew-message in two main ways, depending on how you prefer to structure your project:

1. Import via CDN (Content Delivery Network)

If you're not using a module bundler like Webpack or Rollup, you can include the plugin directly in your HTML using a CDN link. Simply add the following <script> and <link> tags to your HTML:

<!-- Import the CSS file -->
<link rel="stylesheet" href="https://www.unpkg.com/ew-message/dist/ew-message.min.css" />

<!-- Import the JavaScript file -->
<script src="https://www.unpkg.com/ew-message/dist/ew-message.min.js"></script>

2. Import in a JavaScript/TypeScript Project

If you're using a modern JavaScript framework or bundler, you can import ew-message directly in your code:

// Import the plugin
import ewMessage from 'ew-message';
// Import the CSS
import 'ew-message/dist/ew-message.min.css';

Once imported, you can easily start using the plugin in your components.

Usage

Using ew-message is straightforward. You can call the ewMessage function and pass a configuration object to display a message.

Basic Usage Example

const msg = ewMessage('This is the default message');

This will display a message with the default configuration. The ewMessage function accepts a simple string as the message content.

Advanced Usage with Configuration Options

To customize the appearance, type, and behavior of the message, you can pass a configuration object:

const msg = ewMessage({
  content: 'This is a custom message',
  type: 'success', // Set message type: 'info', 'success', 'warning', 'error'
  duration: 3000,   // Duration before the message automatically closes (in milliseconds)
  showClose: true,  // Show the close button
  center: true,     // Center the message on the screen
  top: 50,          // Set the custom top offset
  showTypeIcon: true, // Display the type icon (default is true)
  typeIcon: '👍',    // Custom icon for the message type
  closeIcon: '❌',   // Custom icon for the close button
  removeClassName: ['fadeOut'], // Remove built-in animation class names
  startClassName: ['fadeIn'],   // Add custom animation class names
});

Configuration Options

The configuration object accepts several options to customize the behavior and appearance of the message. Here are the key options:

interface ewMessageOption {
  content: string;         // Content of the message (required)
  center?: boolean;       // Whether to center the message (default is false)
  type?: string;          // Message type: 'info', 'success', 'warning', 'error' (default is 'info')
  duration?: number;      // Duration to close the message (in milliseconds, default is 2000ms)
  showClose?: boolean;    // Whether to show the close button (default is true)
  showTypeIcon?: boolean; // Whether to display the type icon (default is true)
  typeIcon?: string;      // Custom icon for the message type
  closeIcon?: string;     // Custom icon for the close button
  container?: string | HTMLElement; // Container element for mounting the message (default is body)
  removeClassName?: string[]; // Remove specific animation class names
  startClassName?: string[];  // Add custom animation class names
  top?: number;           // Customize the top offset for positioning (default is 20px)
}

Example Configuration

content: The message text that you want to display.
type: Choose the type of message. It can be 'info', 'success', 'warning', or 'error'. The type can also determine the icon shown alongside the message.
duration: The number of milliseconds the message will be visible before disappearing. By default, it is set to 2000ms.
center: Whether the message should be centered on the screen. This is particularly useful for modal-style notifications.
showClose: Allows you to show or hide the close button. Setting it to false removes the button.
typeIcon: Allows you to specify a custom icon to represent the message type. For example, you can use emojis or image URLs.
closeIcon: Allows you to specify a custom icon for the close button (e.g., a custom "X" icon).
top: Adjusts the position of the message from the top of the screen, which is useful when displaying multiple messages.

Example in a Component

Here is an example of how you might use ew-message in a component:

import ewMessage from 'ew-message';
import 'ew-message/dist/ew-message.min.css';

const showMessage = () => {
  const msg = ewMessage({
    content: 'Operation successful!',
    type: 'success',
    duration: 3000,
    showClose: true,
    top: 50,
  });
};

In this example, calling showMessage will display a success message that lasts for 3 seconds, with a close button and a custom top offset.

Conclusion

ew-message is a flexible and powerful message plugin that can enhance the user experience in your web application by providing clean and customizable notifications. With support for various message types, custom icons, animations, and positioning, it is easy to integrate and tailor to your project's needs. Whether you are working on a simple website or a complex web application, ew-message can help you deliver important messages to your users in a stylish and efficient way.

For more information and detailed documentation, check out the official website.

contribute

Of course, this project is not the best yet. I sincerely invite you to contribute to this project. Thank you very much.

DEV Community