{"title":"File 对象","version":"5.0","locale":"zh-hans","docname":"ref/files/file","url":"/zh-hans/5.0/ref/files/file/","canonical":"https://djangodocs.dev/zh-hans/5.0/ref/files/file/","summary":"django.core.files 模块及其子模块包含了 Django 中基本的文件处理的内置类。File 类是对 Python file object 的一个简单的封装，并增加了一些 Django 特有的功能。","html":"<h1><code class=\"docutils literal notranslate\">File</code> 对象<a class=\"heading-anchor\" href=\"#the-file-object\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h1>\n<p><a class=\"reference internal\" href=\"/zh-hans/5.0/ref/files/#module-django.core.files\" title=\"django.core.files: File handling and storage\"><code class=\"xref py py-mod docutils literal notranslate\">django.core.files</code></a> 模块及其子模块包含了 Django 中基本的文件处理的内置类。</p>\n<section id=\"the-file-class\">\n<h2><code class=\"docutils literal notranslate\">File</code> 类<a class=\"heading-anchor\" href=\"#the-file-class\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File\">\n<em class=\"property\"><span class=\"k\">class</span> </em><span class=\"sig-name descname\">File</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">file_object</em>, <em class=\"sig-param\">name<span class=\"o\">=</span><span class=\"default_value\">None</span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p><a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 类是对 Python <a class=\"reference external\" href=\"https://docs.python.org/3/glossary.html#term-file-object\" title=\"(in Python v3.14)\"><span class=\"xref std std-term\">file object</span></a> 的一个简单的封装，并增加了一些 Django 特有的功能。在内部，当 Django 需要表示一个文件时，会使用这个类。</p>\n<p><a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 对象具有以下属性和方法：</p>\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.name\">\n<span class=\"sig-name descname\">name</span><a class=\"heading-anchor\" href=\"#django.core.files.File.name\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>文件名，包括 <a class=\"reference internal\" href=\"/zh-hans/5.0/ref/settings/#std-setting-MEDIA_ROOT\"><code class=\"xref std std-setting docutils literal notranslate\">MEDIA_ROOT</code></a> 的相对路径。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.size\">\n<span class=\"sig-name descname\">size</span><a class=\"heading-anchor\" href=\"#django.core.files.File.size\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>文件的大小，单位为字节。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.file\">\n<span class=\"sig-name descname\">file</span><a class=\"heading-anchor\" href=\"#django.core.files.File.file\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>该类封装的底层 <a class=\"reference external\" href=\"https://docs.python.org/3/glossary.html#term-file-object\" title=\"(in Python v3.14)\"><span class=\"xref std std-term\">file object</span></a>。</p>\n<aside class=\"admonition-be-careful-with-this-attribute-in-subclasses admonition\" role=\"note\">\n<p class=\"admonition-title\">在子类中要小心这个属性。</p>\n<p>一些 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 的子类，包括 <a class=\"reference internal\" href=\"#django.core.files.base.ContentFile\" title=\"django.core.files.base.ContentFile\"><code class=\"xref py py-class docutils literal notranslate\">ContentFile</code></a> 和 <code class=\"xref py py-class docutils literal notranslate\">FieldFile</code>，可以用 Python <a class=\"reference external\" href=\"https://docs.python.org/3/glossary.html#term-file-object\" title=\"(in Python v3.14)\"><span class=\"xref std std-term\">file object</span></a> 以外的对象来替换这个属性。在这些情况下，这个属性本身可能是一个 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 子类（而且不一定是同一个子类）。只要有可能，就使用子类本身的属性和方法，而不是子类的 <code class=\"docutils literal notranslate\">file</code> 属性。</p>\n</aside>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.mode\">\n<span class=\"sig-name descname\">mode</span><a class=\"heading-anchor\" href=\"#django.core.files.File.mode\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>文件的读／写模式。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.open\">\n<span class=\"sig-name descname\">open</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">mode<span class=\"o\">=</span><span class=\"default_value\">None</span></em>, <em class=\"sig-param\"><span class=\"o\">*</span>args</em>, <em class=\"sig-param\"><span class=\"o\">**</span>kwargs</em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File.open\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>打开或重新打开文件（这也会执行 <code class=\"docutils literal notranslate\">File.seek(0)</code>）。<code class=\"docutils literal notranslate\">mode</code> 参数允许与 Python 内置的 <a class=\"reference external\" href=\"https://docs.python.org/3/library/functions.html#open\" title=\"(in Python v3.14)\"><code class=\"docutils literal notranslate\">open()</code></a> 相同的值。<code class=\"docutils literal notranslate\">*args</code> 和 <code class=\"docutils literal notranslate\">**kwargs</code> 在 <code class=\"docutils literal notranslate\">mode</code> 之后传递给 Python 内置的 <a class=\"reference external\" href=\"https://docs.python.org/3/library/functions.html#open\" title=\"(in Python v3.14)\"><code class=\"docutils literal notranslate\">open()</code></a>。</p>\n<p>当重新打开一个文件时，<code class=\"docutils literal notranslate\">mode</code> 将覆盖文件原来打开的任何模式；<code class=\"docutils literal notranslate\">None</code> 表示用原来的模式重新打开。</p>\n<p>它可以作为一个上下文管理器使用，例如 <code class=\"docutils literal notranslate\">with file.open() as f:</code>。</p>\n<aside class=\"version-note version-changed\" data-version=\"5.0\" role=\"note\">\n<p class=\"version-note-title\">Changed in Django 5.0</p><p>已添加支持传递 <code class=\"docutils literal notranslate\">*args</code> 和 <code class=\"docutils literal notranslate\">**kwargs</code>。</p>\n</aside>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.__iter__\">\n<span class=\"sig-name descname\">__iter__</span><span class=\"sig-paren\">(</span><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File.__iter__\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>在文件上迭代，每次只产生一行。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.chunks\">\n<span class=\"sig-name descname\">chunks</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">chunk_size<span class=\"o\">=</span><span class=\"default_value\">None</span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File.chunks\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>对文件进行迭代，产生给定大小的“块”。<code class=\"docutils literal notranslate\">chunk_size</code> 默认为 64KB。</p>\n<p>这对非常大的文件特别有用，因为它允许将它们从磁盘上串联起来，避免将整个文件存储在内存中。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.multiple_chunks\">\n<span class=\"sig-name descname\">multiple_chunks</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">chunk_size<span class=\"o\">=</span><span class=\"default_value\">None</span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File.multiple_chunks\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>如果文件足够大，需要多个分块才能访问其所有内容，则返回 <code class=\"docutils literal notranslate\">True</code>。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.close\">\n<span class=\"sig-name descname\">close</span><span class=\"sig-paren\">(</span><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File.close\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>关闭文件。</p>\n</dd></dl>\n\n<p>除了列出的方法外，<a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 还暴露了它的 <code class=\"docutils literal notranslate\">file</code> 对象的以下属性和方法：<code class=\"docutils literal notranslate\">encoding</code>、<code class=\"docutils literal notranslate\">fileno</code>、<code class=\"docutils literal notranslate\">flush</code>、<code class=\"docutils literal notranslate\">isat</code>。<code class=\"docutils literal notranslate\">encoding</code>、<code class=\"docutils literal notranslate\">fileno</code>、<code class=\"docutils literal notranslate\">flush</code>、<code class=\"docutils literal notranslate\">isatty</code>、<code class=\"docutils literal notranslate\">newlines</code>、<code class=\"docutils literal notranslate\">read</code>、<code class=\"docutils literal notranslate\">readinto</code>、<code class=\"docutils literal notranslate\">readline</code>、<code class=\"docutils literal notranslate\">readlines</code>、<code class=\"docutils literal notranslate\">seek</code>、<code class=\"docutils literal notranslate\">tell</code>、<code class=\"docutils literal notranslate\">truncate</code>、<code class=\"docutils literal notranslate\">write</code>、<code class=\"docutils literal notranslate\">writelines</code>、<code class=\"docutils literal notranslate\">readable()</code>、<code class=\"docutils literal notranslate\">writable()</code> 和 <code class=\"docutils literal notranslate\">seekable()</code>。</p>\n</dd></dl>\n\n</section>\n<section id=\"the-contentfile-class\">\n<h2><code class=\"docutils literal notranslate\">ContentFile</code> 类<a class=\"heading-anchor\" href=\"#the-contentfile-class\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.base.ContentFile\">\n<em class=\"property\"><span class=\"k\">class</span> </em><span class=\"sig-name descname\">ContentFile</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">content</em>, <em class=\"sig-param\">name<span class=\"o\">=</span><span class=\"default_value\">None</span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.base.ContentFile\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p><code class=\"docutils literal notranslate\">ContentFile</code> 类继承自 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a>，但与 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 不同的是，它操作的是字符串内容（也支持字节），而不是实际的文件。例如：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"kn\">from</span> <span class=\"nn\">django.core.files.base</span> <span class=\"kn\">import</span> ContentFile\n\nf1 <span class=\"o\">=</span> ContentFile<span class=\"p\">(</span><span class=\"s2\">&quot;esta frase está en español&quot;</span><span class=\"p\">)</span>\nf2 <span class=\"o\">=</span> ContentFile<span class=\"p\">(</span><span class=\"sa\">b</span><span class=\"s2\">&quot;these are bytes&quot;</span><span class=\"p\">)</span>\n</code></pre></div>\n</dd></dl>\n\n</section>\n<section id=\"the-imagefile-class\">\n<h2><code class=\"docutils literal notranslate\">ImageFile</code> 类<a class=\"heading-anchor\" href=\"#the-imagefile-class\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<dl class=\"py class\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.images.ImageFile\">\n<em class=\"property\"><span class=\"k\">class</span> </em><span class=\"sig-name descname\">ImageFile</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">file_object</em>, <em class=\"sig-param\">name<span class=\"o\">=</span><span class=\"default_value\">None</span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.images.ImageFile\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>Django 提供了一个专门针对图片的内置类。 <a class=\"reference internal\" href=\"#django.core.files.images.ImageFile\" title=\"django.core.files.images.ImageFile\"><code class=\"xref py py-class docutils literal notranslate\">django.core.files.images.ImageFile</code></a> 继承了 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 的所有属性和方法，并额外提供了以下内容。</p>\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.images.ImageFile.width\">\n<span class=\"sig-name descname\">width</span><a class=\"heading-anchor\" href=\"#django.core.files.images.ImageFile.width\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>图像的宽度，单位为像素。</p>\n</dd></dl>\n\n<dl class=\"py attribute\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.images.ImageFile.height\">\n<span class=\"sig-name descname\">height</span><a class=\"heading-anchor\" href=\"#django.core.files.images.ImageFile.height\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>图像的高度，单位为像素。</p>\n</dd></dl>\n\n</dd></dl>\n\n</section>\n<section id=\"additional-methods-on-files-attached-to-objects\">\n<h2>附加在对象上的文件方法<a class=\"heading-anchor\" href=\"#additional-methods-on-files-attached-to-objects\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>任何与对象相关联的 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> （如下面的 <code class=\"docutils literal notranslate\">Car.photo</code>）也会有几个额外的方法：</p>\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.save\">\n<span class=\"sig-prename descclassname\">File.</span><span class=\"sig-name descname\">save</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">name</em>, <em class=\"sig-param\">content</em>, <em class=\"sig-param\">save<span class=\"o\">=</span><span class=\"default_value\">True</span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File.save\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>使用提供的文件名和内容保存一个新文件。这不会替换现有文件，而是创建一个新文件并更新对象以指向它。如果 <code class=\"docutils literal notranslate\">save</code> 是 <code class=\"docutils literal notranslate\">True</code>，则在文件保存后将调用模型的 <code class=\"docutils literal notranslate\">save()</code> 方法。也就是说，以下两行代码：</p>\n<div class=\"code-block\" data-language=\"pycon\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Python console</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Python console code\"><code><span class=\"gp\">&gt;&gt;&gt; </span>car<span class=\"o\">.</span>photo<span class=\"o\">.</span>save<span class=\"p\">(</span><span class=\"s2\">&quot;myphoto.jpg&quot;</span><span class=\"p\">,</span> content<span class=\"p\">,</span> save<span class=\"o\">=</span><span class=\"kc\">False</span><span class=\"p\">)</span>\n<span class=\"gp\">&gt;&gt;&gt; </span>car<span class=\"o\">.</span>save<span class=\"p\">()</span>\n</code></pre></div>\n<p>等同于：</p>\n<div class=\"code-block\" data-language=\"pycon\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Python console</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Python console code\"><code><span class=\"gp\">&gt;&gt;&gt; </span>car<span class=\"o\">.</span>photo<span class=\"o\">.</span>save<span class=\"p\">(</span><span class=\"s2\">&quot;myphoto.jpg&quot;</span><span class=\"p\">,</span> content<span class=\"p\">,</span> save<span class=\"o\">=</span><span class=\"kc\">True</span><span class=\"p\">)</span>\n</code></pre></div>\n<p>请注意，<code class=\"docutils literal notranslate\">content</code> 参数必须是 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 或 <a class=\"reference internal\" href=\"#django.core.files.File\" title=\"django.core.files.File\"><code class=\"xref py py-class docutils literal notranslate\">File</code></a> 的子类的实例，如 <a class=\"reference internal\" href=\"#django.core.files.base.ContentFile\" title=\"django.core.files.base.ContentFile\"><code class=\"xref py py-class docutils literal notranslate\">ContentFile</code></a>。</p>\n</dd></dl>\n\n<dl class=\"py method\">\n<dt class=\"sig sig-object py\" id=\"django.core.files.File.delete\">\n<span class=\"sig-prename descclassname\">File.</span><span class=\"sig-name descname\">delete</span><span class=\"sig-paren\">(</span><em class=\"sig-param\">save<span class=\"o\">=</span><span class=\"default_value\">True</span></em><span class=\"sig-paren\">)</span><a class=\"heading-anchor\" href=\"#django.core.files.File.delete\"><span class=\"visually-hidden\">Link to this definition</span><span aria-hidden=\"true\">#</span></a></dt>\n<dd><p>从模型实例中删除文件并删除底层文件。如果 <code class=\"docutils literal notranslate\">save</code> 是 <code class=\"docutils literal notranslate\">True</code>，一旦文件被删除，模型的 <code class=\"docutils literal notranslate\">save()</code> 方法将被调用。</p>\n</dd></dl>\n\n</section>","rootId":"the-file-object","toc":[{"title":"File 类","anchor":"the-file-class","children":[]},{"title":"ContentFile 类","anchor":"the-contentfile-class","children":[]},{"title":"ImageFile 类","anchor":"the-imagefile-class","children":[]},{"title":"附加在对象上的文件方法","anchor":"additional-methods-on-files-attached-to-objects","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/5.0/ref/"},{"docname":"ref/files/index","title":"文件处理","url":"/zh-hans/5.0/ref/files/"}],"prev":{"docname":"ref/files/index","title":"文件处理","url":"/zh-hans/5.0/ref/files/"},"next":{"docname":"ref/files/storage","title":"文件存储 API","url":"/zh-hans/5.0/ref/files/storage/"},"formats":{"html":"/zh-hans/5.0/ref/files/file/","markdown":"/zh-hans/5.0/ref/files/file.md","json":"/zh-hans/5.0/ref/files/file.json"},"source":"https://github.com/django/django/blob/stable/5.0.x/docs/ref/files/file.txt","official":"https://docs.djangoproject.com/zh-hans/5.0/ref/files/file/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}