{"id":13601682,"url":"https://github.com/Zhouzi/TheaterJS","last_synced_at":"2025-04-11T04:31:18.776Z","repository":{"id":25266145,"uuid":"28691440","full_name":"zhouzi/TheaterJS","owner":"zhouzi","description":"Typing animation mimicking human behavior.","archived":false,"fork":false,"pushed_at":"2023-01-04T09:25:10.000Z","size":783,"stargazers_count":3232,"open_issues_count":18,"forks_count":162,"subscribers_count":74,"default_branch":"master","last_synced_at":"2024-10-29T15:33:07.446Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://codepen.io/Zhouzi/pen/JoRazP","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"apache/incubator-htrace","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhouzi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-01T17:30:25.000Z","updated_at":"2024-10-25T08:58:29.000Z","dependencies_parsed_at":"2023-01-14T02:26:03.302Z","dependency_job_id":null,"html_url":"https://github.com/zhouzi/TheaterJS","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2FTheaterJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2FTheaterJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2FTheaterJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2FTheaterJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhouzi","download_url":"https://codeload.github.com/zhouzi/TheaterJS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248341657,"owners_count":21087703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T18:01:06.246Z","updated_at":"2025-04-11T04:31:18.732Z","avatar_url":"https://github.com/zhouzi.png","language":"JavaScript","readme":"# TheaterJS\n\nTyping animation mimicking human behavior.\n\n- [CodePen Demo](http://codepen.io/Zhouzi/full/JoRazP/)\n- [Showcase](https://github.com/Zhouzi/TheaterJS#showcase)\n- [Installation](https://github.com/Zhouzi/TheaterJS#installation)\n- [Documentation](https://github.com/Zhouzi/TheaterJS#documentation)\n- [Localized Keyboards](https://github.com/Zhouzi/TheaterJS#localized-keyboards)\n- [Change Log](https://github.com/Zhouzi/TheaterJS#change-log)\n- [Path from v1.x to v2](https://github.com/Zhouzi/TheaterJS/blob/master/MIGRATING.md)\n\n_If you're not particularly interested in managing multiple actors and the several features TheaterJS has to offer (e.g mistakes, variable speed, callbacks, html support, and so on), have a look at this [fiddle](https://jsfiddle.net/p1e9La6w/). It's a minimalist version that supports play/stop, it has a lot of comments so you understand what's going on under the hood. It might well be enough for you usage :)_\n\n## Installation\n\nWith npm:\n\n```\nnpm install theaterjs\n```\n\nWith yarn:\n\n```\nyarn add theaterjs\n```\n\n## Example\n\n```html\n\u003cdiv id=\"vader\"\u003e\u003c/div\u003e\n\u003cdiv id=\"luke\"\u003e\u003c/div\u003e\n\n\u003cscript src=\"path/to/theater.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  var theater = theaterJS();\n\n  theater\n    .on(\"type:start, erase:start\", function() {\n      // add a class to actor's dom element when he starts typing/erasing\n      var actor = theater.getCurrentActor();\n      actor.$element.classList.add(\"is-typing\");\n    })\n    .on(\"type:end, erase:end\", function() {\n      // and then remove it when he's done\n      var actor = theater.getCurrentActor();\n      actor.$element.classList.remove(\"is-typing\");\n    });\n\n  theater.addActor(\"vader\").addActor(\"luke\");\n\n  theater\n    .addScene(\"vader:Luke...\", 400)\n    .addScene(\"luke:What?\", 400)\n    .addScene(\"vader:I am\", 200, \".\", 200, \".\", 200, \". \")\n    .addScene(\"Your father!\")\n    .addScene(theater.replay);\n\u003c/script\u003e\n```\n\n## Documentation\n\nTo get started, you'll first need to create a new TheaterJS object by eventually providing some options.\n\n**Example**\n\n```javascript\nvar theater = theaterJS({ locale: \"fr\" });\n```\n\n**Usage**\n\n```javascript\ntheaterJS(\u003coptions\u003e)\n```\n\n| Param   | Default                                  | Description            |\n| ------- | ---------------------------------------- | ---------------------- |\n| options | `{autoplay, locale, minSpeed, maxSpeed}` | Options _(see below)_. |\n\nBreakdown of the available options:\n\n| Option   | Default                     | Description                                                                                                                                                    |\n| -------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| autoplay | `true`                      | If true, automatically play the scenario (when calling `addScene`).                                                                                            |\n| locale   | `detect`                    | Determine which keyboard to use when typing random characters (mistakes). Note: `\"detect\"` is an option to detect the user's locale and use if it's supported. |\n| minSpeed | `{ erase: 80, type: 80 }`   | Minimum delay between each typed characters (the lower, the faster).                                                                                           |\n| maxSpeed | `{ erase: 450, type: 450 }` | The maximum delay between each typed characters (the greater, the slower).                                                                                     |\n\nRegarding minSpeed and maxSpeed, you can also just pass a number instead of an object.\nIf you do so, this value will be used for both the erase and type speed, e.g:\n\n```json\n{\n  \"minSpeed\": {\n    \"erase\": 80,\n    \"type\": 80\n  },\n\n  \"maxSpeed\": {\n    \"erase\": 450,\n    \"type\": 450\n  }\n}\n```\n\nIs equivalent to:\n\n```json\n{\n  \"minSpeed\": 80,\n  \"maxSpeed\": 450\n}\n```\n\nTheaterJS objects have two public (read only) properties:\n\n- `theater.options`: object's options.\n- `theater.status`: object's status (whether \"playing\", \"stopping\" or \"ready\").\n\n### addActor\n\nAdd an actor to the casting.\n\n**Example**\n\n```javascript\nvar theater = theaterJS();\n\ntheater\n  .addActor(\"vader\")\n  .addActor(\"luke\", 0.8, \".luke-selector\")\n  .addActor(\"yoda\", { accuracy: 0.4, speed: 0.6 }, function(displayValue) {\n    console.log(\"%s said yoda\", displayValue);\n  });\n```\n\n**Usage**\n\n```javascript\ntheater.addActor(\u003cname\u003e, \u003coptions\u003e, \u003ccallback\u003e)\n```\n\n| Param    | Default         | Description                                            |\n| -------- | --------------- | ------------------------------------------------------ |\n| name     |                 | Name used to identify the actor.                       |\n| options  | 0.8             | Actor's options **(see below)**.                       |\n| callback | **(see below)** | A function to call when actor's display value changes. |\n\nActors have two options:\n\n- `accuracy` (number between 0 and 1): used to determine how often an actor should make mistakes.\n- `speed` (number between 0 and 1): used to determine how fast the actor types.\n\nNote: the delay between each typed character varies to \"mimick human behavior\".\n\nAn actor callback is a function that is called when its display value is set.\nIt can also be a string, in such case TheaterJS will assume it's a DOM selector and will look for the corresponding element.\nIt's then going to set the element's innerHTML when the value changes.\nYou can safely ignore this argument if you gave the target element an id with the name of the actor, i.e:\n\n```javascript\ntheater.addActor(\"vader\");\n```\n\nIn this situation, TheaterJS will look for an element that matches the selector `#vader`.\nAlso note that the actor will have an additional `$element` property referring to the DOM element when using a selector string.\n\n### getCurrentActor\n\nReturn the actor that is currently playing.\n\n**Example**\n\n```javascript\nvar theater = theaterJS();\n\ntheater\n  .addActor(\"vader\")\n  .addScene(\"vader:Luke...\")\n  .addScene(function(done) {\n    var vader = theater.getCurrentActor();\n    vader.$element.classList.add(\"dying\");\n    done();\n  });\n```\n\n**Usage**\n\n```javascript\ntheater.getCurrentActor();\n```\n\n### addScene\n\nAdd scenes to the scenario and play it if `options.autoplay` is true.\n\n**Example**\n\n```javascript\nvar theater = theaterJS();\n\ntheater\n  .addActor(\"vader\")\n  .addScene(\"vader:Luke... \", \"Listen to me!\", 500)\n  .addScene(theater.replay);\n```\n\n**Usage**\n\n```javascript\ntheater.addScene(\u003cscene\u003e)\n```\n\nA scene can be of 5 different types:\n\n```javascript\ntheater\n  .addScene(\"vader:Luke... \") // 1\n  .addScene(800) // 2\n  .addScene(\"I am your father!\") // 3\n  .addScene(-7) // 4\n  .addScene(\"mother!\")\n  .addScene(function(done) {\n    // do stuff\n    done();\n  }); // 5\n```\n\n1. `.addScene('vader:Luke... ')` erase actor's current display value, then type the new value.\n2. `.addScene(800)` make a break of `800` milliseconds before playing the next scene.\n3. `.addScene('I am your father!')` append value to the current actor's display value.\n4. `.addScene(-7)` erase `7` characters.\n5. `.addScene(fn)` call fn which receives a done callback as first argument (calling `done()` plays the next scene in the scenario).\n\nNote that addScene actually accepts an infinite number of arguments so you could just do:\n\n```javascript\ntheater\n  .addScene(\"vader:Luke... \", 800, \"I am your father!\")\n  .addScene(-7, \"mother!\")\n  .addScene(fn);\n```\n\n### getCurrentSpeech\n\nReturn the speech that is currently playing.\n\n**Example**\n\n```javascript\nvar theater = theaterJS();\n\ntheater\n  .addActor(\"vader\")\n  .addScene(\"vader:Luke...\")\n  .on(\"type:start\", function() {\n    console.log(theater.getCurrentSpeech()); // outputs 'Luke...'\n  });\n```\n\n**Usage**\n\n```javascript\ntheater.getCurrentSpeech();\n```\n\n### play\n\nPlay the scenario.\n\n**Example**\n\n```javascript\nvar theater = theaterJS({ autoplay: false });\n\ntheater.addActor(\"vader\").addScene(\"vader:Luke...\");\n\ndocument.querySelector(\"button\").addEventListener(\n  \"click\",\n  function() {\n    theater.play();\n  },\n  false\n);\n```\n\n**Usage**\n\n```javascript\ntheater.play();\n```\n\n### replay\n\nReplay the scenario from scratch (can be used as a callback to create a loop).\n\n**Example**\n\n```javascript\nvar theater = theaterJS();\n\ntheater\n  .addActor(\"vader\")\n  .addScene(\"vader:Luke...\")\n  .addScene(theater.replay);\n```\n\n**Usage**\n\n```javascript\ntheater.replay();\n```\n\n### stop\n\nStop the scenario after the current playing scene ends.\n\n**Example**\n\n```javascript\nvar theater = theaterJS();\n\ntheater.addActor(\"vader\").addScene(\"vader:Luke... \", \"I am your father...\");\n\ndocument.querySelector(\"button\").addEventListener(\n  \"click\",\n  function() {\n    theater.stop();\n  },\n  false\n);\n```\n\n**Usage**\n\n```javascript\ntheater.stop();\n```\n\n### on\n\nAdd a callback to execute when an event is emitted (e.g when a scene starts/ends).\n\n**Example**\n\n```javascript\nvar theater = theaterJS();\n\ntheater\n  .on(\"type:start, erase:start\", function() {\n    var actor = theater.getCurrentActor();\n    actor.$element.classList.add(\"blinking-caret\");\n  })\n  .on(\"type:end, erase:end\", function() {\n    var actor = theater.getCurrentActor();\n    actor.$element.classList.remove(\"blinking-caret\");\n  });\n\ntheater.addActor(\"vader\").addScene(\"vader:Luke...\");\n```\n\n**Usage**\n\n```javascript\ntheater.on(\u003ceventName\u003e, \u003ccallback\u003e)\n```\n\n| Param     | Default | Description                                    |\n| --------- | ------- | ---------------------------------------------- |\n| eventName |         | Event's name to listen to.                     |\n| callback  |         | Function to call when the event got published. |\n\nThe callback function receives the event's name as first argument.\n\nA couple of things to note:\n\n- Listen to all event by using the shortcut: `theater.on('*', callback)`.\n- An event is emitted when a sequence starts (`sequence:start`) and ends (`sequence:end`), e.g `theater.addScene('vader:Luke.', 'vader:I am your father.')` is one sequence.\n- An event is emitted when the scenario starts and ends, respectively `scenario:start` and `scenario:end`.\n- The scenario is stoppable within `:end` event listeners. It means that calling `theater.stop()` within a callback that listen for the `:end` of a scene will stop the scenario. This is useful for asynchronous callbacks (e.g animations).\n\n## Localized Keyboards\n\nWhen making a mistake, an actor's gonna type a random character near the one he intended to.\nThose characters are taken from a \"mapped\" keyboard that you can configure on TheaterJS' instantiation: `theaterJS({locale: 'en'})`.\n\n## Change Log\n\n### 3.2.0 - 2018-06-04\n\n- add \"getCurrentSpeech()\"\n\n### 3.1.0 - 2016-11-14\n\n- add \"main\" property to the package.json\n- remove irrelevant files from the npm package\n\n### 3.0.0 - 2016-03-20\n\n- disabling the erase option should still clear display value\n\n### 2.2.1 - 2016-03-19\n\n- fix end scenes event that throwed an error due to how `.replay()` works\n\n### 2.2.0 - 2016-03-17\n\n- publish an event when the scenario starts and ends\n- scenario should be stoppable in `:end` events callbacks\n\n### 2.1.0 - 2016-03-15\n\n- emit an event when a sequence starts and ends\n\n### 2.0.2 - 2016-03-13\n\n- compile a non-minified version along with the minified one\n- fix `window` detection\n- fix bower.json configuration\n- add support for slash-less void elements (e.g `\u003cbr\u003e` instead of `\u003cbr/\u003e`)\n- fix play/stop issue [#49](https://github.com/Zhouzi/TheaterJS/issues/49)\n- add option to configure erase's min/max speed independently\n\n### 2.0.1 - 2015-11-02\n\n- publish to npm, fix for non-browser environment\n- add a `.npmignore` file\n- add source map\n\n### 2.0.0 - 2015-11-02\n\n- Brand new version\n","funding_links":[],"categories":["Web 前端","Javascript","JavaScript Libs","Client-side"],"sub_categories":["Misc"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZhouzi%2FTheaterJS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FZhouzi%2FTheaterJS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZhouzi%2FTheaterJS/lists"}