{"id":29926671,"url":"https://github.com/ecomfe/js-native","last_synced_at":"2025-08-13T18:44:39.239Z","repository":{"id":57283371,"uuid":"141539849","full_name":"ecomfe/js-native","owner":"ecomfe","description":null,"archived":false,"fork":false,"pushed_at":"2023-05-05T08:06:11.000Z","size":167,"stargazers_count":120,"open_issues_count":3,"forks_count":17,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-08-10T13:48:15.128Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecomfe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-19T07:17:52.000Z","updated_at":"2025-05-16T11:48:41.000Z","dependencies_parsed_at":"2024-06-21T15:34:55.688Z","dependency_job_id":"bc5cbfc7-ddd7-4654-b9e0-d9a6039f35dd","html_url":"https://github.com/ecomfe/js-native","commit_stats":null,"previous_names":["errorrik/js-native"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/ecomfe/js-native","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomfe%2Fjs-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomfe%2Fjs-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomfe%2Fjs-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomfe%2Fjs-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecomfe","download_url":"https://codeload.github.com/ecomfe/js-native/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomfe%2Fjs-native/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270293535,"owners_count":24560038,"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","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-08-02T12:42:32.180Z","updated_at":"2025-08-13T18:44:38.955Z","avatar_url":"https://github.com/ecomfe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"jsNative\n---------\n\n[![npm version](https://img.shields.io/npm/v/js-native.svg?style=flat-square)](https://www.npmjs.com/package/js-native)\n[![GitHub license](https://img.shields.io/github/license/ecomfe/js-native.svg?style=flat-square)](https://github.com/ecomfe/js-native/blob/master/LICENSE)\n[![codecov](https://img.shields.io/codecov/c/github/ecomfe/js-native/master.svg?style=flat-square)](https://codecov.io/gh/ecomfe/js-native)\n[![CircleCI](https://circleci.com/gh/ecomfe/js-native.svg?style=svg)](https://circleci.com/gh/ecomfe/js-native)\n\n\n\njsNative 是一个 JavaScript 与 Native 通信管理的库。其基于 [通信接口描述](doc/description.md)，生成可调用 API。\n\n- [了解为什么设计成这样](doc/design.md)\n- [实现的一些约束](doc/spec.md)\n- [通信接口描述](doc/description.md)\n\n\n## 引入\n\n### 下载\n\n`NPM:`\n\n```\n$ npm i js-native --save\n```\n\n`保存:`\n\n[请点击右键另存为](https://unpkg.com/js-native@latest)\n\n\n### 引用\n\n```html\n\u003c!-- 引用通过 NPM 下载的本地文件 --\u003e\n\u003cscript src=\"node_modules/js-native/index.js\"\u003e\u003c/script\u003e\n\n\u003c!-- 通过 CDN 引用 --\u003e\n\u003cscript src=\"https://unpkg.com/js-native@latest\"\u003e\u003c/script\u003e\n```\n\n\n## 使用\n\n通过接口描述可以直接调用。\n\n\n```js\nlet apiList = jsNative.invokeAPI({\n    \"invoke\": \"method.json\",\n    \"name\": \"na.getAPIs\",\n    \"method\": \"_na.getAPIs\"\n});\n```\n\n\njsNative 是一个默认的 api 容器对象，通过 `add` 方法可以添加接口描述。\n\n```js\njsNative.add({\n    \"invoke\": \"method.json\",\n    \"name\": \"net.request\",\n    \"method\": \"_naNet.request\",\n    \"args\": [\n        {\"name\": \"url\", \"value\": \"string\"},\n        {\"name\": \"method\", \"value\": \"string\"},\n        {\"name\": \"onsuccess\", \"value\": \"function\"}\n    ]\n});\n```\n\napi 容器对象上，可以使用 `invoke` 方法调用 api。\n\n```js\njsNative.invoke('net.request', ['my-url', 'GET', data =\u003e {}]);\n```\n\napi 容器对象上，通过 `map` 方法可以生成一个对象，对象上包含接口直接调用的方法。\n\n```js\nlet mod = jsNative\n    .add({\n        \"invoke\": \"method.json\",\n        \"name\": \"net.request\",\n        \"method\": \"_naNet.request\",\n        \"args\": [\n            {\"name\": \"url\", \"value\": \"string\"},\n            {\"name\": \"method\", \"value\": \"string\"},\n            {\"name\": \"onsuccess\", \"value\": \"function\"}\n        ]\n    })\n    .map({\n        'net.request': 'fetch'\n    });\n\nmod.fetch('my-url', 'GET', data =\u003e {});\n```\n\napi 容器对象上，可以使用 `fromNative` 方法直接从一个 **返回所有接口描述信息的接口** 获取接口并添加。\n\n```js\nlet mod = jsNative\n    .fromNative({\n        \"invoke\": \"method\",\n        \"name\": \"na.getAPIs\",\n        \"method\": \"_na.getAPIs\"\n    })\n    .map(name =\u003e name.slice(name.indexOf('.') + 1));\n```\n\n\n当你不想使用默认的 api 容器对象，或者需要多个 api 容器对象时，可以使用 `createContainer` 方法创建新的 api 容器对象。\n\n```js\nlet apiContainer = jsNative.createContainer();\n```\n\n新的 api 容器对象上拥有 `add` 、`fromNative`、`invoke`、`map` 方法，你可以正常使用它。\n\n```js\nlet mod = jsNative\n    .createContainer()\n    .add({\n        \"invoke\": \"method.json\",\n        \"name\": \"net.request\",\n        \"method\": \"_naNet.request\",\n        \"args\": [\n            {\"name\": \"url\", \"value\": \"string\"},\n            {\"name\": \"method\", \"value\": \"string\"},\n            {\"name\": \"onsuccess\", \"value\": \"function\"}\n        ]\n    })\n    .map({\n        'net.request': 'fetch'\n    });\n\nmod.fetch('my-url', 'GET', data =\u003e {});\n```\n\n## API\n\n### jsNative\n\n通常，对于一个应用场景，我们倾向于在一个地方管理所有的 Native 通信接口 。所以 jsNative 是 [APIContainer](#apicontainer) 的一个实例，在这个实例上额外提供了：\n\n- [createContainer](#jsnativecreatecontainer) 方法。在不想用默认 [APIContainer](#apicontainer) 实例时，可以创建自己的 [APIContainer](#apicontainer) 实例\n- [invokeAPI](#jsnativeinvokeapi) 方法。可以直接调用 Native 通信接口\n\njsNative 上的其他属性和方法请参考 [APIContainer](#apicontainer) 的文档。\n\n\n#### jsNative.createContainer\n\n`说明`\n\n创建 [APIContainer](#apicontainer) 实例。\n\n`参数`\n\n- `{Object}` options 参数对象\n- `{string=}` options.errorTitle 显示报错信息的标题\n- `{string=}` options.namingConflict 名字冲突时的处理策略\n\n详细请参考 [config](#config) 方法\n\n`返回`\n\n[APIContainer](#apicontainer) 实例。\n\n`示例`\n\n```js\nlet apiContainer = jsNative.createContainer();\n```\n\n#### jsNative.invokeAPI\n\n`说明`\n\n通过[通信接口描述](doc/description.md)，直接调用。\n\n`参数`\n\n- `{Object} description` [通信接口描述](doc/description.md)对象\n- `{Array=} args` 调用参数\n\n`返回`\n\n`{*}` 调用结果\n\n`示例`\n\n```js\nlet apiList = jsNative.invokeAPI(\n    {\n        \"invoke\": \"method.json\",\n        \"name\": \"net.request\",\n        \"method\": \"_naNet.request\",\n        \"args\": [\n            {\"name\": \"url\", \"value\": \"string\"},\n            {\"name\": \"method\", \"value\": \"string\"},\n            {\"name\": \"onsuccess\", \"value\": \"function\"}\n        ]\n    },\n    [\n        'https://yourdomain.com/path',\n        'get',\n        content =\u003e {\n            console.log(content);\n        }\n    ]\n);\n```\n\n\n### APIContainer\n\n通信接口容器类。用于通信接口的管理功能，包括多种注册方式、调用、编译出可被直接调用函数组成的对象等。\n\n\n#### add\n\n`说明`\n\n添加 Native 通信接口描述\n\n`参数`\n\n- `{Object|Array}` description [通信接口描述](doc/description.md)对象，或多个对象组成的数组\n\n`返回`\n\n`{APIContainer}` this\n\n`示例`\n\n```js\napiContainer.add({\n    \"invoke\": \"method.json\",\n    \"name\": \"net.request\",\n    \"method\": \"_naNet.request\",\n    \"args\": [\n        {\"name\": \"url\", \"value\": \"string\"},\n        {\"name\": \"method\", \"value\": \"string\"},\n        {\"name\": \"onsuccess\", \"value\": \"function\"}\n    ]\n});\n```\n\n#### addProcessorCreator\n\n`说明`\n\n新增 processorCreator ，新增的 processorCreator 可以在描述的 invoke 中进行调用(但不可以冲掉内置的 processorCreator )\n\n`参数`\n\n- `{string}` name 注册的 processorCreator 名称\n- `{Function}` processorCreator 的创建函数，需要返回真正的processor\n\n其中 processorCreator 接受三个参数：\n\n- description: 当前调用能力的description\n- option: 调用能力时，invoke配置的参数（如：ReturnDecode:JSON 中的JSON）\n- apiContainer: 调用能力发生的container对象\n\nprocessorCreator 的返回值接受调用能力时真正传入的参数\n\n`返回`\n\n`{APIContainer}` this\n\n`示例`\n\n```js\napis.addProcessorCreator(\n    'ArgAddToken',\n    function (description, option, apiContainer) {\n        return function (args) {\n            return true;\n        }\n    }\n);\n```\n\n#### config\n\n`说明`\n\n配置参数，设置的参数将被合并到现有参数中\n\n`参数`\n\n- `{Object}` options 参数对象\n- `{string=}` options.errorTitle 显示报错信息的标题\n- `{string=}` options.namingConflict 名字冲突时的处理策略\n\nnamingConflict 的取值可以是：\n\n- error: 抛出错误\n- ignore: 保留现有api\n- override: 覆盖现有api\n\n`返回`\n\n`{APIContainer}` this\n\n`示例`\n\n```js\napiContainer.config({\n    namingConflict: 'ignore'\n});\n```\n\n\n#### fromNative\n\n`说明`\n\n从 `返回所有接口描述信息的接口` 调用的结果，添加调用API。该接口 Native 上的实现必须遵循[如下约束](doc/spec.md#强制-返回所有接口描述信息的接口必须是同步的并遵循如下定义)。\n\n`参数`\n\n- `{Object}` description 要调用的[通信接口描述](doc/description.md)对象\n\n`返回`\n\n`{APIContainer}` this\n\n`示例`\n\n```js\napiContainer.fromNative({\n    \"invoke\": \"method\",\n    \"name\": \"na.getAPIs\",\n    \"method\": \"_na.getAPIs\"\n});\n```\n\n#### invoke\n\n`说明`\n\n通过描述对象的 name 属性进行调用。\n\n`参数`\n\n- `{string} name` 调用描述对象的 name\n- `{Array=} args` 调用参数\n\n`返回`\n\n`{*}` 调用结果\n\n`示例`\n\n```js\napiContainer\n    .add({\n        \"invoke\": \"method.json\",\n        \"name\": \"net.request\",\n        \"method\": \"_naNet.request\",\n        \"args\": [\n            {\"name\": \"url\", \"value\": \"string\"},\n            {\"name\": \"method\", \"value\": \"string\"},\n            {\"name\": \"onsuccess\", \"value\": \"function\"}\n        ]\n    })\n    .invoke(\n        \"net.request\",\n        [\n            'https://yourdomain.com/path',\n            'get',\n            content =\u003e {\n                console.log(content);\n            }\n        ]\n    );\n```\n\n#### map\n\n`说明`\n\n生成一个对象，其上的方法是 API 容器对象中调用描述对象编译成的，可被直接调用的函数\n\n`参数`\n\n- `{Object|Function}` mapAPI 调用描述对象名称的映射表或映射函数\n\n`返回`\n\n`{Object}` 生成的对象\n\n`示例`\n\n```js\napiContainer.add({\n    \"invoke\": \"method.json\",\n    \"name\": \"net.request\",\n    \"method\": \"_naNet.request\",\n    \"args\": [\n        {\"name\": \"url\", \"value\": \"string\"},\n        {\"name\": \"method\", \"value\": \"string\"},\n        {\"name\": \"onsuccess\", \"value\": \"function\"}\n    ]\n});\n\n// 通过 Object map。mod 对象上包含 fetch 方法，可直接调用\nlet mod = apiContainer.map({\n    'net.request': 'fetch'\n});\nmod.fetch('https://yourdomain.com/path', 'GET', data =\u003e {});\n\n// 通过 function map。mod2 对象上包含 request 方法，可直接调用\nlet mod2 = apiContainer.map(name =\u003e name.slice(name.indexOf('.') + 1));\nmod2.request('https://yourdomain.com/path', 'GET', data =\u003e {});\n```\n\n#### setExternalDescriptionProps\n\n`说明`\n\n设置额外的 description 属性列表。\n\n若设置了额外的 description 属性列表，不在列表中的属性将被忽略。该接口应仅用于性能优化，不应改变默认行为。\n\n`参数`\n\n- `{Array}` props 额外的description属性列表\n\n`返回`\n\n无\n\n`示例`\n\n```js\napis.setExternalDescriptionProps(['myProp']);\n\napis.addProcessorCreator(\n    'ReadMyProp',\n    function (description) {\n        return function () {\n            return description.myProp;\n        }\n    }\n);\n```\n\n## License\n\njsNative is [MIT licensed](./LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecomfe%2Fjs-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecomfe%2Fjs-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecomfe%2Fjs-native/lists"}